How ankur-sharma01/buildclaw works
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: toolExecutor.ts Tool executor · agent/orchestrator.ts Agent mode · handlers.ts Update handlers · ask/orchestrator.ts Ask mode
Components 26
User interfaces
- CLI mode picker
modes/cli.ts - Mode launcher
tui/Wakeup.ts - Terminal renderer
tui/terminal-md.ts
Work modes
- Agent mode
modes/agent/orchestrator.ts - Ask mode
modes/ask/orchestrator.ts - Plan mode
modes/plan/orchestrator.ts - Plan and research
modes/plan/planner.ts - Step selection
modes/plan/selection.ts
Agent execution
- Agent tool definitions
modes/agent/agent-tools.ts - Tool executor
modes/agent/toolExecutor.ts - Staged action log
modes/agent/actiontracker.ts - Approval and diff
modes/agent/approval.ts - Diff view
modes/agent/diff-view.ts
Telegram delivery
- Telegram client
modes/telegram/index.ts - Update handlers
modes/telegram/handlers.ts - Telegram agent turn
modes/telegram/agent-run.ts - Telegram ask turn
modes/telegram/ask-turn.ts - Telegram plan turn
modes/telegram/plan-session.ts - Chat approval session
modes/telegram/approval-session.ts - User authorization
modes/telegram/auth.ts
Models and workspace
- Model configuration
ai/ai.config.ts - OpenRouter models
- Code workspace
- System shell
- Telegram Bot API
Other components
- User
Connections 38
- 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