# whyiyhw/seek architecture

> Architecture diagram of the GitHub repository whyiyhw/seek, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whyiyhw/seek
- Repository: https://github.com/whyiyhw/seek

## Overview

seek is a local coding-agent platform. A user starts it through the CLI or an editor/browser/headless surface; the agent runs model-backed tool turns, with planning, goals, and sub-agents supporting larger tasks. Sessions, memory, skills, checkpoints, and scheduled routines preserve or extend work. The README documents several capabilities whose detailed implementations were not sampled; those branches are shown at subsystem-directory granularity. Edges use the README or SOURCE INDEX where available, so some internal wiring is intentionally omitted.

Main entry points: [`pkg/agent/agent.go`](https://github.com/whyiyhw/seek/blob/main/pkg/agent/agent.go) (Agent loop), [`cmd/seek/main.go`](https://github.com/whyiyhw/seek/blob/main/cmd/seek/main.go) (CLI entry), [`internal/tui`](https://github.com/whyiyhw/seek/tree/main/internal/tui) (Terminal UI), [`internal/controlplane`](https://github.com/whyiyhw/seek/tree/main/internal/controlplane) (Browser control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry surfaces"]
  node_cli["CLI entry<br/>[main.go]"]
  node_tui["Terminal UI"]
  node_control["Browser control"]
  node_acp["ACP editor"]
  node_rpc["JSON-RPC"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Agent loop<br/>[agent.go]"]
  node_tools["Agent tools"]
  node_prompt["System prompt<br/>[sysprompt.go]"]
end

subgraph group_work["Work orchestration"]
  node_plan["Plan workflow"]
  node_goal["Goal loop"]
  node_autopilot["Autopilot fleet"]
  node_subagents["Sub-agents<br/>[manager.go]"]
  node_worktrees["Git worktrees<br/>[worktree.go]"]
  node_routines["Scheduled runs"]
end

subgraph group_state["Knowledge and state"]
  node_session[("Session history<br/>[session.go]")]
  node_memory[("Three-tier memory")]
  node_skills["Skills lifecycle<br/>[skillmgr.go]"]
  node_distill["Skill distillation<br/>[skilldistill.go]"]
  node_checkpoint[("Checkpoints<br/>[file.go]")]
end

subgraph group_integration["Providers and integrations"]
  node_llm["LLM providers"]
  node_deepseek["DeepSeek API<br/>[client.go]"]
  node_mcp["MCP servers<br/>[client.go]"]
end

node_user(("User or host"))
node_external(("Model APIs"))

node_user -->|"starts"| node_cli
node_cli -->|"opens"| node_tui
node_cli -->|"serves"| node_control
node_cli -->|"starts"| node_acp
node_cli -->|"starts"| node_rpc
node_tui -->|"prompts"| node_agent
node_control -->|"drives"| node_agent
node_acp -->|"drives"| node_agent
node_rpc -->|"prompts"| node_agent
node_agent -->|"invokes"| node_tools
node_agent -->|"streams via"| node_llm
node_agent -->|"uses"| node_deepseek
node_agent -->|"uses"| node_prompt
node_tools -.->|"bridges"| node_mcp
node_user -->|"approves"| node_plan
node_plan -->|"gates work"| node_agent
node_cli -->|"runs"| node_goal
node_goal -->|"runs turns"| node_agent
node_cli -->|"runs"| node_autopilot
node_autopilot -->|"dispatches"| node_subagents
node_subagents -->|"isolates in"| node_worktrees
node_cli -->|"schedules"| node_routines
node_agent -.->|"persists"| node_session
node_agent -.->|"uses"| node_memory
node_agent -.->|"loads"| node_skills
node_session -->|"distills into"| node_distill
node_tui -->|"undoes via"| node_checkpoint
node_llm -.->|"calls"| node_external

click node_cli "https://github.com/whyiyhw/seek/blob/main/cmd/seek/main.go"
click node_tui "https://github.com/whyiyhw/seek/tree/main/internal/tui"
click node_control "https://github.com/whyiyhw/seek/tree/main/internal/controlplane"
click node_acp "https://github.com/whyiyhw/seek/tree/main/internal/acp"
click node_rpc "https://github.com/whyiyhw/seek/tree/main/internal/rpc"
click node_agent "https://github.com/whyiyhw/seek/blob/main/pkg/agent/agent.go"
click node_tools "https://github.com/whyiyhw/seek/tree/main/internal/tools"
click node_prompt "https://github.com/whyiyhw/seek/blob/main/internal/sysprompt/sysprompt.go"
click node_plan "https://github.com/whyiyhw/seek/tree/main/internal/tools/plan"
click node_goal "https://github.com/whyiyhw/seek/tree/main/internal/goal"
click node_autopilot "https://github.com/whyiyhw/seek/tree/main/internal/autopilot"
click node_subagents "https://github.com/whyiyhw/seek/blob/main/internal/subagent/manager.go"
click node_worktrees "https://github.com/whyiyhw/seek/blob/main/internal/worktree/worktree.go"
click node_session "https://github.com/whyiyhw/seek/blob/main/internal/session/session.go"
click node_memory "https://github.com/whyiyhw/seek/tree/main/internal/memory"
click node_skills "https://github.com/whyiyhw/seek/blob/main/internal/skillmgr/skillmgr.go"
click node_distill "https://github.com/whyiyhw/seek/blob/main/internal/skilldistill/skilldistill.go"
click node_checkpoint "https://github.com/whyiyhw/seek/blob/main/internal/checkpoint/file.go"
click node_routines "https://github.com/whyiyhw/seek/tree/main/internal/routines"
click node_llm "https://github.com/whyiyhw/seek/tree/main/pkg/llm"
click node_deepseek "https://github.com/whyiyhw/seek/blob/main/pkg/deepseek/client.go"
click node_mcp "https://github.com/whyiyhw/seek/blob/main/pkg/mcp/client.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_tui,node_control,node_acp,node_rpc,node_user toneBlue
class node_agent,node_tools,node_prompt toneAmber
class node_plan,node_goal,node_autopilot,node_subagents,node_worktrees,node_routines,node_external toneMint
class node_session,node_memory,node_skills,node_distill,node_checkpoint toneRose
class node_llm,node_deepseek,node_mcp toneIndigo
```

## Components

### Entry surfaces

- [CLI entry](https://github.com/whyiyhw/seek/blob/main/cmd/seek/main.go): `cmd/seek/main.go`
- [Terminal UI](https://github.com/whyiyhw/seek/tree/main/internal/tui): `internal/tui`
- [Browser control](https://github.com/whyiyhw/seek/tree/main/internal/controlplane): `internal/controlplane`
- [ACP editor](https://github.com/whyiyhw/seek/tree/main/internal/acp): `internal/acp`
- [JSON-RPC](https://github.com/whyiyhw/seek/tree/main/internal/rpc): `internal/rpc`

### Agent runtime

- [Agent loop](https://github.com/whyiyhw/seek/blob/main/pkg/agent/agent.go): `pkg/agent/agent.go`
- [Agent tools](https://github.com/whyiyhw/seek/tree/main/internal/tools): `internal/tools`
- [System prompt](https://github.com/whyiyhw/seek/blob/main/internal/sysprompt/sysprompt.go): `internal/sysprompt/sysprompt.go`

### Work orchestration

- [Plan workflow](https://github.com/whyiyhw/seek/tree/main/internal/tools/plan): `internal/tools/plan`
- [Goal loop](https://github.com/whyiyhw/seek/tree/main/internal/goal): `internal/goal`
- [Autopilot fleet](https://github.com/whyiyhw/seek/tree/main/internal/autopilot): `internal/autopilot`
- [Sub-agents](https://github.com/whyiyhw/seek/blob/main/internal/subagent/manager.go): `internal/subagent/manager.go`
- [Git worktrees](https://github.com/whyiyhw/seek/blob/main/internal/worktree/worktree.go): `internal/worktree/worktree.go`
- [Scheduled runs](https://github.com/whyiyhw/seek/tree/main/internal/routines): `internal/routines`

### Knowledge and state

- [Session history](https://github.com/whyiyhw/seek/blob/main/internal/session/session.go): `internal/session/session.go`
- [Three-tier memory](https://github.com/whyiyhw/seek/tree/main/internal/memory): `internal/memory`
- [Skills lifecycle](https://github.com/whyiyhw/seek/blob/main/internal/skillmgr/skillmgr.go): `internal/skillmgr/skillmgr.go`
- [Skill distillation](https://github.com/whyiyhw/seek/blob/main/internal/skilldistill/skilldistill.go): `internal/skilldistill/skilldistill.go`
- [Checkpoints](https://github.com/whyiyhw/seek/blob/main/internal/checkpoint/file.go): `internal/checkpoint/file.go`

### Providers and integrations

- [LLM providers](https://github.com/whyiyhw/seek/tree/main/pkg/llm): `pkg/llm`
- [DeepSeek API](https://github.com/whyiyhw/seek/blob/main/pkg/deepseek/client.go): `pkg/deepseek/client.go`
- [MCP servers](https://github.com/whyiyhw/seek/blob/main/pkg/mcp/client.go): `pkg/mcp/client.go`

### Other components

- **User or host**
- **Model APIs**

## Connections

- User or host → CLI entry: starts (evidence: `README.md`)
- CLI entry → Terminal UI: opens (evidence: `README.md`)
- CLI entry → Browser control: serves (evidence: `README.md`)
- CLI entry → ACP editor: starts (evidence: `README.md`)
- CLI entry → JSON-RPC: starts (evidence: `README.md`)
- Terminal UI → Agent loop: prompts (evidence: `README.md`)
- Browser control → Agent loop: drives (evidence: `README.md`)
- ACP editor → Agent loop: drives (evidence: `README.md`)
- JSON-RPC → Agent loop: prompts (evidence: `internal/rpc/server.go`)
- Agent loop → Agent tools: invokes (evidence: `pkg/agent/agent.go`)
- Agent loop → LLM providers: streams via (evidence: `pkg/agent/agent.go`)
- Agent loop → DeepSeek API: uses (evidence: `pkg/agent/agent.go`)
- Agent loop → System prompt: uses (evidence: `pkg/agent/agent.go`)
- Agent tools → MCP servers: bridges
- User or host → Plan workflow: approves (evidence: `README.md`)
- Plan workflow → Agent loop: gates work (evidence: `README.md`)
- CLI entry → Goal loop: runs (evidence: `README.md`)
- Goal loop → Agent loop: runs turns (evidence: `internal/goal/agentworker.go`)
- CLI entry → Autopilot fleet: runs (evidence: `README.md`)
- Autopilot fleet → Sub-agents: dispatches (evidence: `README.md`)
- Sub-agents → Git worktrees: isolates in (evidence: `README.md`)
- CLI entry → Scheduled runs: schedules (evidence: `README.md`)
- Agent loop → Session history: persists
- Agent loop → Three-tier memory: uses
- Agent loop → Skills lifecycle: loads
- Session history → Skill distillation: distills into (evidence: `README.md`)
- Terminal UI → Checkpoints: undoes via (evidence: `internal/tui/commands.go`)
- LLM providers → Model APIs: calls
