Architecture¶
This page sketches anthrogo's runtime topology and how the major packages fit together. For per-package API details see the API reference.
Top-level: one binary, four entry modes¶
flowchart LR
user([User])
subgraph cmd[cmd/anthrogo]
cli[anthrogo CLI]
end
user -->|terminal| cli
cli -->|default| tui[TUI mode<br/>Bubble Tea]
cli -->|"-p / --json"| headless[Headless mode]
cli -->|"serve"| serve[HTTP daemon<br/>internal/serve]
cli -->|"web"| web[Browser UI<br/>internal/web]
tui --> engine
headless --> engine
serve --> engine
web --> serve
subgraph engine[pkg/query · Engine]
loop[Turn loop]
subreg[Subagent registry]
toolreg[Tool registry]
permgate[Permission gate]
hooks[Hook manager]
end
engine --> provider
engine --> mcp[(internal/mcp<br/>MCP servers)]
engine --> session[(internal/session<br/>JSONL + SQLite L2)]
engine --> tools
subgraph provider[pkg/provider]
anthropic[Anthropic]
openai[OpenAI-compat]
bedrock[Bedrock]
vertex[Vertex]
ollama[Ollama]
failover[Failover]
end
subgraph tools[pkg/tool<br/>30+ built-ins]
readtool[Read/Write/Edit]
bashtool[Bash sandbox]
httptool[HTTPRequest +<br/>WebFetch +<br/>WebSearch]
netguard{{NetGuard<br/>SSRF block}}
browser[BrowserAction<br/>chromedp]
sql[SQLQuery]
pdfxlsx[PDFRead +<br/>XlsxRead]
commsl[SlackPost +<br/>Embed + ImageGen +<br/>CalendarEvent]
readtool & httptool & browser & sql & pdfxlsx & commsl
httptool -.-> netguard
end
Engine turn loop¶
sequenceDiagram
autonumber
participant Caller as Caller<br/>(TUI / serve / headless)
participant Engine as pkg/query · Engine
participant Provider as Provider
participant Gate as pkg/permissions
participant Tools as pkg/tool
participant Hooks as internal/hooks
Caller->>Engine: SubmitMessage(ctx, text)
Engine->>Provider: Stream(req)
loop until EventMessageStop
Provider-->>Engine: EventTextDelta / ToolUseStart / ...
Engine-->>Caller: forward as Event channel
end
alt stop_reason == tool_use
par concurrent dispatch (when all safe)
Engine->>Gate: Decide(ctx, c, tool, input)
Gate-->>Engine: Allow / Ask / Deny
Engine->>Hooks: FirePreToolUse(ctx, tool, input)
Hooks-->>Engine: HookDecision
Engine->>Tools: t.Call(ctx, input, ctx)
Tools-->>Engine: Result
Engine->>Hooks: FirePostToolUse(ctx, tool, in, out)
end
Engine->>Engine: append tool_results
Engine->>Provider: Stream(req with results)
end
Engine-->>Caller: Done
Subagent dispatch (M5.1+)¶
flowchart TB
parent[Parent Engine]
parentctx[Parent Tool ctx<br/>permissions + hooks + sessions]
parent -->|"Task tool"| dispatch[Engine.RunSubagent]
dispatch --> child[Child Engine]
parentctx -.->|Cloned<br/>permissions.Context.Clone| childctx
parentctx -.->|Shared by ref<br/>hooks.Manager| childctx[Child Tool ctx]
child --> childloop[Child Turn Loop]
childloop -->|"final text"| dispatch
dispatch -->|"tool_result"| parent
For KAIROS (cross-process subagent dispatch) see docs/kairos.md.
Session storage¶
flowchart LR
engine[Engine] -->|"records"| store[internal/session<br/>Store]
store -->|"flock LOCK_EX"| jsonl[(<cwd>/.anthrogo/<id>.jsonl<br/>mode 0o600)]
store -->|"Flush each record<br/>Sync on TurnComplete/Error/Compact"| jsonl
cli[anthrogo --resume<br/>anthrogo /sessions replay] --> replay[Replay]
replay --> jsonl
replay -->|"L1 miss"| persistent[PersistentCache<br/>SQLite WAL]
persistent -->|"<= 2000 rows<br/>LRU trim on insert"| db[(~/.anthrogo/cache.db)]
Hook flow¶
flowchart LR
engine[Engine] -->|"PreToolUse(ctx)"| runner[hooks.Runner]
runner --> exec[exec.CommandContext]
exec -->|"stdin: JSON payload"| script[(User-supplied script)]
script -->|"stdout: JSON Output"| runner
runner -.->|"strip ANTHROPIC_/<br/>OPENAI_/AWS_/<br/>GITHUB_TOKEN..."| sanitized[sanitizedEnv]
sanitized -.-> exec
MCP topology¶
flowchart LR
subgraph anthrogo
mgr[internal/mcp.Manager]
toolreg[(Tool Registry)]
end
mgr -->|"stdio"| s1[(MCP subprocess<br/>e.g. context7)]
mgr -->|"SSE / HTTP"| s2[(Remote MCP server)]
mgr -->|"Streamable HTTP +<br/>OAuth 2.1 PKCE"| s3[(Enterprise MCP)]
mgr -->|"WebSocket"| s4[(Realtime MCP)]
s1 & s2 & s3 & s4 -->|"tools/list"| mgr
mgr -->|"register as mcp__name__tool"| toolreg
Permission gate¶
The gate is the single point of decision for every tool invocation. Order
documented in pkg/permissions/gate.go::Decide:
ModeBypassPermissions+IsBypassAvailable→ allow always.- Deny rules win unconditionally.
ModeAcceptEditsauto-allowsWrite/Edit/NotebookEdit.HookDecide(ctx, tool, input)may short-circuit Allow / Deny / Pass.- Allow rules → allow (plan mode still locks write tools).
- Ask rules → ask (or deny if
ShouldAvoidPrompts). - Fallback → ask in default mode, deny in
ShouldAvoidPrompts.