sherlock/docs/agents.md

Agents

Sherlock dispatches built-in agent profiles from internal/agent/.

Agent	CLI	MCP config
copilot	GitHub Copilot CLI	--additional-mcp-config @<path>
claude	Claude Code CLI	--mcp-config <path>

sherlock <agent> [args...] and sherlock run <agent> [args...] are equivalent. Unknown agent names exit with usage errors.

Spawn behavior

On spawn, sherlock resolves installed MCP binaries (gitea-mcp, grafana-mcp, gssh-mcp, searxng-mcp), skips missing ones with a warning, renders a 0600 .mcp.json file under $XDG_RUNTIME_DIR/sherlock/, and execs the target agent.

The child mostly inherits the parent environment. The Claude profile strips ANTHROPIC_API_KEY so a personal key does not override sherlock-managed behavior.

Changing agents

Adding a built-in agent is a code change under internal/agent/. Implement the small agent interface, register it in init, and use internal/mcp for config rendering. The exact API lives in internal/agent/agent.go; shared spawn helpers live in internal/agent/exec.go, and the per-CLI MCP/-env conventions ("backends") live in internal/agent/backend.go.

Custom agents (config)

Operators can register their own agents from config.toml without touching code — handy for wrapper commands such as a copilot-local script that points the Copilot CLI at a self-hosted model:

[agents.copilot-local]
command = "copilot-local"   # binary to exec; defaults to the name if omitted
backend = "copilot"         # which CLI's MCP/-env conventions to use

backend must be one of the built-in backends (copilot or claude); it tells sherlock how to format the MCP config (--additional-mcp-config @<path> vs --mcp-config <path>) and what env to scrub. The rendered MCP file is named after the agent (<name>.mcp.json).

sherlock copilot-local [args...] then dispatches exactly like a built-in. A custom agent whose name collides with a built-in agent, or that names an unknown backend, is a hard startup error. (Names matching a reserved subcommand — status, logout, run, update, version — are shadowed by that subcommand; reach them via sherlock run <name>.)