# 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 `exec`s 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.