# ankur-sharma01/buildclaw architecture

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

- Interactive diagram: https://gitdiagram.com/ankur-sharma01/buildclaw
- Repository: https://github.com/ankur-sharma01/buildclaw

## Overview

BuildCLAW is a terminal and Telegram coding agent with three user workflows: read-only codebase Q&A, goal planning with optional research and Agent handoff, and tool-driven code changes staged for approval before application. The CLI and Telegram are separate entry surfaces into these modes; Telegram reuses agent tools and staging while adapting approval to chat callbacks. The graph follows the documented capabilities and sampled call sites; unsampled Telegram turn handlers and planning internals are represented only where README or visible callers support them.

Main entry points: [`modes/agent/toolExecutor.ts`](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/toolExecutor.ts) (Tool executor), [`modes/agent/orchestrator.ts`](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/orchestrator.ts) (Agent mode), [`modes/telegram/handlers.ts`](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/handlers.ts) (Update handlers), [`modes/ask/orchestrator.ts`](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/ask/orchestrator.ts) (Ask mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI mode picker<br/>[cli.ts]"]
  node_wakeup["Mode launcher<br/>[Wakeup.ts]"]
  node_terminal["Terminal renderer<br/>[terminal-md.ts]"]
end

subgraph group_modes["Work modes"]
  node_agentmode["Agent mode<br/>[orchestrator.ts]"]
  node_askmode["Ask mode<br/>[orchestrator.ts]"]
  node_planmode["Plan mode<br/>[orchestrator.ts]"]
  node_planner["Plan and research<br/>[planner.ts]"]
  node_selection["Step selection<br/>[selection.ts]"]
end

subgraph group_agent["Agent execution"]
  node_agenttools["Agent tool definitions<br/>[agent-tools.ts]"]
  node_executor["Tool executor<br/>[toolExecutor.ts]"]
  node_tracker["Staged action log<br/>[actiontracker.ts]"]
  node_review["Approval and diff<br/>[approval.ts]"]
  node_diff["Diff view<br/>[diff-view.ts]"]
end

subgraph group_telegram["Telegram delivery"]
  node_telegramclient["Telegram client<br/>[index.ts]"]
  node_handlers["Update handlers<br/>[handlers.ts]"]
  node_tgagent["Telegram agent turn<br/>[agent-run.ts]"]
  node_tgask["Telegram ask turn<br/>[ask-turn.ts]"]
  node_tgplan["Telegram plan turn<br/>[plan-session.ts]"]
  node_approvalsession["Chat approval session"]
  node_auth["User authorization<br/>[auth.ts]"]
end

subgraph group_services["Models and workspace"]
  node_modelconfig["Model configuration<br/>[ai.config.ts]"]
  node_modelservice{{"OpenRouter models"}}
  node_workspace[("Code workspace")]
  node_shell{{"System shell"}}
  node_botapi{{"Telegram Bot API"}}
end

node_user(("User"))

node_user -->|"starts"| node_wakeup
node_wakeup -->|"opens CLI"| node_cli
node_wakeup -->|"starts bot"| node_telegramclient
node_cli -->|"selects"| node_agentmode
node_cli -->|"selects"| node_askmode
node_cli -->|"selects"| node_planmode
node_planmode -->|"drafts plan"| node_planner
node_planmode -->|"edits steps"| node_selection
node_planmode -->|"hands off"| node_agentmode
node_planmode -->|"renders plan"| node_terminal
node_askmode -->|"gets model"| node_modelconfig
node_agentmode -->|"gets model"| node_modelconfig
node_modelconfig -->|"configures provider"| node_modelservice
node_askmode -->|"creates read-only tools"| node_agenttools
node_agentmode -->|"creates tools"| node_agenttools
node_agenttools -->|"invokes tools"| node_executor
node_askmode -->|"creates executor"| node_executor
node_agentmode -->|"creates executor"| node_executor
node_executor -->|"reads files"| node_workspace
node_executor -->|"queues commands"| node_shell
node_executor -->|"logs staged actions"| node_tracker
node_agentmode -->|"reads pending actions"| node_tracker
node_agentmode -->|"requests approval"| node_review
node_review -->|"updates decisions"| node_tracker
node_review -->|"shows changes"| node_diff
node_executor -->|"applies approved changes"| node_tracker
node_executor -->|"writes approved changes"| node_workspace
node_executor -->|"runs approved commands"| node_shell
node_askmode -->|"renders answer"| node_terminal
node_telegramclient -->|"polls and sends"| node_botapi
node_telegramclient -->|"dispatches updates"| node_handlers
node_handlers -->|"checks user"| node_auth
node_handlers -->|"dispatches agent"| node_tgagent
node_handlers -->|"dispatches ask"| node_tgask
node_handlers -->|"dispatches plan"| node_tgplan
node_tgagent -->|"manages approvals"| node_approvalsession
node_approvalsession -->|"updates action status"| node_tracker
node_handlers -->|"routes callbacks"| node_approvalsession

click node_cli "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/cli.ts"
click node_wakeup "https://github.com/ankur-sharma01/buildclaw/blob/main/tui/Wakeup.ts"
click node_terminal "https://github.com/ankur-sharma01/buildclaw/blob/main/tui/terminal-md.ts"
click node_agentmode "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/orchestrator.ts"
click node_askmode "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/ask/orchestrator.ts"
click node_planmode "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/plan/orchestrator.ts"
click node_planner "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/plan/planner.ts"
click node_selection "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/plan/selection.ts"
click node_modelconfig "https://github.com/ankur-sharma01/buildclaw/blob/main/ai/ai.config.ts"
click node_agenttools "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/agent-tools.ts"
click node_executor "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/toolExecutor.ts"
click node_tracker "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/actiontracker.ts"
click node_review "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/approval.ts"
click node_diff "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/diff-view.ts"
click node_telegramclient "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/index.ts"
click node_handlers "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/handlers.ts"
click node_tgagent "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/agent-run.ts"
click node_tgask "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/ask-turn.ts"
click node_tgplan "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/plan-session.ts"
click node_approvalsession "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/approval-session.ts"
click node_auth "https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/auth.ts"

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_wakeup,node_terminal,node_user toneBlue
class node_agentmode,node_askmode,node_planmode,node_planner,node_selection toneAmber
class node_agenttools,node_executor,node_tracker,node_review,node_diff toneMint
class node_telegramclient,node_handlers,node_tgagent,node_tgask,node_tgplan,node_approvalsession,node_auth toneRose
class node_modelconfig,node_modelservice,node_workspace,node_shell,node_botapi toneIndigo
```

## Components

### User interfaces

- [CLI mode picker](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/cli.ts): `modes/cli.ts`
- [Mode launcher](https://github.com/ankur-sharma01/buildclaw/blob/main/tui/Wakeup.ts): `tui/Wakeup.ts`
- [Terminal renderer](https://github.com/ankur-sharma01/buildclaw/blob/main/tui/terminal-md.ts): `tui/terminal-md.ts`

### Work modes

- [Agent mode](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/orchestrator.ts): `modes/agent/orchestrator.ts`
- [Ask mode](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/ask/orchestrator.ts): `modes/ask/orchestrator.ts`
- [Plan mode](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/plan/orchestrator.ts): `modes/plan/orchestrator.ts`
- [Plan and research](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/plan/planner.ts): `modes/plan/planner.ts`
- [Step selection](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/plan/selection.ts): `modes/plan/selection.ts`

### Agent execution

- [Agent tool definitions](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/agent-tools.ts): `modes/agent/agent-tools.ts`
- [Tool executor](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/toolExecutor.ts): `modes/agent/toolExecutor.ts`
- [Staged action log](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/actiontracker.ts): `modes/agent/actiontracker.ts`
- [Approval and diff](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/approval.ts): `modes/agent/approval.ts`
- [Diff view](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/agent/diff-view.ts): `modes/agent/diff-view.ts`

### Telegram delivery

- [Telegram client](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/index.ts): `modes/telegram/index.ts`
- [Update handlers](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/handlers.ts): `modes/telegram/handlers.ts`
- [Telegram agent turn](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/agent-run.ts): `modes/telegram/agent-run.ts`
- [Telegram ask turn](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/ask-turn.ts): `modes/telegram/ask-turn.ts`
- [Telegram plan turn](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/plan-session.ts): `modes/telegram/plan-session.ts`
- [Chat approval session](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/approval-session.ts): `modes/telegram/approval-session.ts`
- [User authorization](https://github.com/ankur-sharma01/buildclaw/blob/main/modes/telegram/auth.ts): `modes/telegram/auth.ts`

### Models and workspace

- [Model configuration](https://github.com/ankur-sharma01/buildclaw/blob/main/ai/ai.config.ts): `ai/ai.config.ts`
- **OpenRouter models**
- **Code workspace**
- **System shell**
- **Telegram Bot API**

### Other components

- **User**

## Connections

- User → Mode launcher: starts
- Mode launcher → CLI mode picker: opens CLI
- Mode launcher → Telegram client: starts bot
- CLI mode picker → Agent mode: selects
- CLI mode picker → Ask mode: selects
- CLI mode picker → Plan mode: selects
- Plan mode → Plan and research: drafts plan
- Plan mode → Step selection: edits steps
- Plan mode → Agent mode: hands off
- Plan mode → Terminal renderer: renders plan
- Ask mode → Model configuration: gets model
- Agent mode → Model configuration: gets model
- Model configuration → OpenRouter models: configures provider
- Ask mode → Agent tool definitions: creates read-only tools
- Agent mode → Agent tool definitions: creates tools
- Agent tool definitions → Tool executor: invokes tools
- Ask mode → Tool executor: creates executor
- Agent mode → Tool executor: creates executor
- Tool executor → Code workspace: reads files
- Tool executor → System shell: queues commands
- Tool executor → Staged action log: logs staged actions
- Agent mode → Staged action log: reads pending actions
- Agent mode → Approval and diff: requests approval
- Approval and diff → Staged action log: updates decisions
- Approval and diff → Diff view: shows changes
- Tool executor → Staged action log: applies approved changes
- Tool executor → Code workspace: writes approved changes
- Tool executor → System shell: runs approved commands
- Ask mode → Terminal renderer: renders answer
- Telegram client → Telegram Bot API: polls and sends
- Telegram client → Update handlers: dispatches updates
- Update handlers → User authorization: checks user
- Update handlers → Telegram agent turn: dispatches agent
- Update handlers → Telegram ask turn: dispatches ask
- Update handlers → Telegram plan turn: dispatches plan
- Telegram agent turn → Chat approval session: manages approvals
- Chat approval session → Staged action log: updates action status
- Update handlers → Chat approval session: routes callbacks