Project-local resources via `.agents/`

hoocode discovers project-local resources from four directory conventions. Each resource type (slash commands, subagents, MCP servers, skills) has its own precedence order across these roots.

Discovery roots

Root	Scope	Notes
`.hoocode/`	project + user (`~/.hoocode/`)	hoocode-native convention
`.agents/`	project (ancestor-walked) + user (`~/.agents/`)	cross-vendor convention
`.claude/`	project + user (`~/.claude/`)	Claude Code native import
`hoocode.*` manifest fields	installed packages	declared in `package.json`

Ancestor-walk-to-git-root rule

Source: packages/coding-agent/src/utils/paths.ts (collectAgentsAncestorDirs, findGitRepoRoot).

For .agents/<subdir> only, hoocode walks upward from the current working directory, collecting <dir>/.agents/<subdir> at each level, stopping at (and including) the nearest ancestor that contains a .git entry (the git repo root). If the cwd is not inside a git repo, the walk continues to the filesystem root.

Directories are collected cwd-first, so a closer .agents/ directory beats an ancestor under first-match-wins semantics.

Slash commands / prompt templates

Source: packages/coding-agent/src/core/resource-loader.ts (defaultSlashCommandDirs in reload()).

First-match-wins, highest precedence first:

{cwd}/.hoocode/commands
{cwd}/.claude/commands
.agents/commands — ancestor-walk from cwd up to git root, cwd-first
{agentDir}/commands (i.e. ~/.hoocode/commands)
~/.agents/commands
~/.claude/commands

Pass --no-slash-commands or --no-prompt-templates to disable discovery. Explicit --slash-command/--prompt-template paths still load when discovery is off.

Subagents

Source: packages/coding-agent/src/core/agent-registry.ts (loadAgentRegistry).

Registered lowest precedence first; later sources override earlier ones by name:

Built-in agents
Package-manifest agents (hoocode.agents in package.json)
~/.claude/agents (source claude-user)
{agentDir}/agents i.e. ~/.hoocode/agents (source user)
.agents/agents — ancestor-walk from cwd up to git root, registered git-root-first so the cwd-level entry overrides ancestors (source project)
{cwd}/.claude/agents (source claude-project)
{cwd}/.hoocode/agents (source project)
CLI --agent paths (highest precedence)

MCP servers

Source: packages/coding-agent/src/extensions/core/mcp-loader.ts (setupMcpLoader).

First-wins by server name, in this order:

~/.agents/mcp.json — user, standard format (mcpServers object)
./.agents/mcp.json — project, standard format
~/.config/claude/mcp.json — Claude Desktop, standard format
~/.hoocode/mcp-servers/*.json — user, one file per server (each with top-level name/command)
./.hoocode/mcp-servers/*.json — project, per-server format

Standard mcp.json format:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": { "API_KEY": "..." }
    }
  }
}

Per-server format (.hoocode/mcp-servers/<name>.json):

{
  "name": "my-server",
  "command": "npx",
  "args": ["-y", "my-mcp-server"]
}

Debugging discovery

Run hoocode resources to print everything that was discovered for the current cwd — skills, subagents, slash commands, and MCP servers — with source path and origin label.

Source: packages/coding-agent/src/resources-cli.ts.

$ hoocode resources
Resources discovered for /path/to/project

Skills (0)
  (none)

Subagents (1)
  docs - Maintain project documentation  [project (.hoocode)]
    /path/to/project/.hoocode/agents/docs.md

Slash commands (1)
  /review - Review a diff for risk  [project (.hoocode)]
    /path/to/project/.hoocode/commands/review.md

MCP servers (1)
  my-db-tools  [project (.agents)]
    /path/to/project/.agents/mcp.json

This is the fastest way to verify why a .agents/ resource is or is not being loaded.

Project-local resources via .agents/