sherlock/docs/architecture.md

Architecture

Sherlock is a local CLI, not a daemon. It either manages the wallet (status, logout) or replaces itself with an agent CLI (copilot, claude, ...). MCPs run as agent child processes and own service authentication.

Runtime flow

1. sherlock <agent> opens the keyring, resolves installed MCP binaries, writes $XDG_RUNTIME_DIR/sherlock/<agent>.mcp.json, and execs the agent.
2. The agent starts the configured stdio MCPs.
3. Each MCP loads its [services.<name>] config, authenticates on first tool call, keeps its token fresh, and calls the target service.

Code map

Area	Role
cmd/sherlock/	CLI, wallet commands, agent dispatch, update entry point.
cmd/*-mcp/	Service MCP binaries. Tool details live with each MCP.
internal/agent/	Registered agent profiles and spawn helpers.
internal/mcp/	MCP config rendering.
internal/config/	TOML loading and service/provider resolution.
internal/authn/	OAuth/PKCE login, refresh, token sources, locks.
internal/keyring/	OS keyring wallet.
internal/installer/, internal/selfupdate/	Install and update logic.

Boundaries

Sherlock does not federate identities, run a background broker, issue SSH credentials, enforce service policy, or define MCP tool behavior. It gets the right credential to the right local MCP process.