How harnesslab/claw-code-agent works
1. Top-level shape
- This is a Python CLI agent runtime, not a web service.
- The main flow is: user command → local orchestration layer → OpenAI-compatible model endpoint → tool calls back into the local runtime.
- Most of the code lives under src/, with tests/ validating each runtime slice and benchmarks/ measuring task-suite performance.
2. CLI and command routing
- src/main.py is the entrypoint and command dispatcher.
- It exposes agent modes like agent, agent-chat, agent-resume, background/daemon commands, and many inspection/mutation commands such as search-*, mcp-*, remote-*, config-*, and account-*.
- The CLI is the outer boundary that decides whether input becomes a model turn, a local slash command, or a utility/runtime action.
3. Core agent loop
- src/agent_runtime.py is the central loop for a single agent run.
- It coordinates prompt assembly, model calls, tool invocation, stop/continue handling, streaming output, truncation recovery, and final transcript persistence.
- src/query_engine.py acts as a higher-level orchestration facade around that runtime.
4. Prompt, context, and session state
- src/agent_prompting.py builds the system prompt.
- src/agent_context.py and src/context.py collect workspace context, including file tree/material, CLAUDE.md discovery, and other prompt inputs.
- src/agent_context_usage.py estimates token usage and drives /context-style reporting.
- src/agent_session.py, src/session_store.py, src/transcript.py, and src/history.py persist and restore conversation state, file edit history, and resumable sessions.
5. Tooling boundary and execution
- src/agent_tools.py, src/tools.py, src/tool_pool.py, and src/execution_registry.py define and execute the tool surface.
- Core tools include file operations, search, shell execution, web fetch/search, configuration/account/remote actions, task/plan/worktree actions, MCP calls, and nested delegation.
- src/permissions.py, src/bash_security.py, src/cost_tracker.py, and src/prompt_constants.py enforce the safety and budget boundary around those tools.
6. Model connectivity
- src/openai_compat.py is the transport layer to an OpenAI-compatible chat completions API.
- The repo is designed to work with local or proxied model backends such as vLLM, Ollama, LiteLLM Proxy, and OpenRouter.
- Streaming and tool calling are first-class; the model is expected to emit tool calls that the local runtime executes and feeds back into the next turn.
7. Local control-plane runtimes
- A large part of the repo is a set of local stateful runtimes that expose auxiliary agent features without depending on a server.
- These include search_runtime.py, mcp_runtime.py, remote_runtime.py, background_runtime.py, account_runtime.py, ask_user_runtime.py, config_runtime.py, plan_runtime.py, task_runtime.py, team_runtime.py, workflow_runtime.py, remote_trigger_runtime.py, and worktree_runtime.py.
- These runtimes typically manage manifests, profiles, histories, and activation state, then surface them both as slash commands and as tools.
8. Plugins and hook/policy layer
- src/plugin_runtime.py and src/agent_plugin_cache.py implement a manifest-based plugin system with hooks, tool aliases, and virtual tools.
- src/hook_policy.py provides local hook/policy manifests, trust reporting, safe environment handling, and budget or tool-blocking overrides.
- This layer sits between the core agent loop and the tool/prompt surface, letting plugins modify prompt assembly, resume behavior, persistence, and delegation.
9. Nested agents and workflow coordination
- src/agent_manager.py tracks nested agent lineage, group membership, and batched delegation.
- src/team_runtime.py, src/task_runtime.py, and src/plan_runtime.py represent higher-level coordination state for tasks, plans, and team-style message history.
- src/workflow_runtime.py and src/remote_trigger_runtime.py model reusable workflows and triggers as local artifacts with run history.
10. Persistence, snapshots, and parity data
- The repo stores state locally in serialized session data, runtime manifests, and file-history snapshots; the README references .port_sessions/ for resumable sessions.
- src/reference_data/ contains snapshot files for commands, tools, and surface metadata used by parity tracking and internal comparisons.
- src/commands.py, src/tools.py, and src/runtime.py appear to mirror the expected command/tool/runtime inventory for parity with the original npm architecture.
11. Tokenizer, compaction, and cost control
- src/tokenizer_runtime.py provides tokenizer-aware accounting with cached backends and heuristic fallback.
- src/compact.py and related context code implement snipping/compaction when prompts grow too large.
- Cost and quota enforcement is centralized in src/cost_tracker.py, with support for token budgets, model-call caps, tool-call caps, and session-turn limits.
12. Testing and benchmark harness
- tests/ is broad and maps closely to the runtime boundaries, which helps confirm the architecture is modular rather than monolithic.
- benchmarks/ contains task-suite runners and dataset loaders for evaluating agent performance across coding, math, QA, and SWE-style benchmarks.
- The benchmark subsystem is separate from the agent runtime, but it exercises the same model/tool/session stack used by the CLI.
13. External boundary summary
- The only hard external dependency in normal operation is the model API endpoint; everything else is intentionally local and standard-library based.
- Optional external-ish integrations are limited to model providers/backends and whatever remote resources the search/MCP/web fetch tools access.
Main entry points: main.py CLI entry · agent_runtime.py Agent loop · execution_registry.py Exec registry · agent_tools.py Agent tools
Components 34
CLI boundary
Command routing and top-level entrypoints.
- CLI entry · Top-level command dispatcher for agent modes and runtime utilities.
src/main.py - Slash cmds · Agent slash command handling and command mutations.
src/agent_slash_commands.py
Core agent
Prompting, context, session state, and the main agent loop.
- Query engine · Higher-level orchestration layer around the agent runtime.
src/query_engine.py - Agent loop · Single-run orchestration: prompt assembly, model calls, tool use, streaming, truncation recovery, and transcript persistence.
src/agent_runtime.py - Prompt build · Builds the system prompt and turn framing for the agent.
src/agent_prompting.py - Workspace ctx · Collects workspace material, file tree, and CLAUDE.md-style inputs.
src/agent_context.py - Token usage · Estimates token usage and powers context reporting.
src/agent_context_usage.py - Session state · Resumable session storage and conversation history.
src/agent_session.py - Transcript · Final and intermediate conversation transcript persistence.
src/transcript.py
Tools and safety
Tool registration, execution, permissions, and budgets.
- Tool surface · Defines the available tool surface and tool metadata.
src/tools.py - Agent tools · Agent-facing tool boundary that connects prompts to executable tools.
src/agent_tools.py - Tool pool · Pools and resolves tools for execution.
src/tool_pool.py - Exec registry · Executes registered tools and dispatches tool calls.
src/execution_registry.py - Permissions · Permission checks for tool and runtime actions.
src/permissions.py - Bash safety · Shell-command safety and command filtering boundary.
src/bash_security.py - Cost tracker · Tracks token, tool-call, model-call, and turn budgets.
src/cost_tracker.py
Local runtimes
Stateful auxiliary runtimes exposed as commands and tools.
- Plugins · Manifest-based plugin system with hooks, aliases, and virtual tools.
src/plugin_runtime.py - Hook policy · Local hook/policy manifests, trust reporting, and safe environment handling.
src/hook_policy.py - Agent manager · Tracks nested agent lineage, group membership, and batched delegation.
src/agent_manager.py - Search runtime · Local search state and search-oriented command surface.
src/search_runtime.py - MCP runtime · Local MCP integration and manifest/state handling.
src/mcp_runtime.py - Remote runtime · Remote resource and control-plane state management.
src/remote_runtime.py - Background · Background and daemon-style runtime actions.
src/background_runtime.py - Plan runtime · Plan artifacts and planning-oriented coordination state.
src/plan_runtime.py - Task runtime · Task artifacts and task-oriented coordination state.
src/task_runtime.py - Team runtime · Team-style message history and higher-level coordination state.
src/team_runtime.py - Workflow runtime · Reusable workflows and run history as local artifacts.
src/workflow_runtime.py - Trigger runtime · Remote trigger artifacts and trigger run history.
src/remote_trigger_runtime.py - Worktree runtime · Worktree-oriented state and actions for branch/workspace management.
src/worktree_runtime.py
Model and storage
External model transport and local persistence/compaction infrastructure.
- Session store · Backing store for sessions and transcript restoration.
src/session_store.py - Model API · OpenAI-compatible chat-completions transport to local or proxied model backends.
src/openai_compat.py - Compaction · Prompt snipping and compaction when context grows too large.
src/compact.py - Tokenizer · Tokenizer-aware accounting with cached backends and heuristic fallback.
src/tokenizer_runtime.py - Runtime core · Shared runtime utilities and inventory parity scaffolding.
src/runtime.py
Connections 32
- CLI entry → Query engine: dispatches agent mode · CLI routes agent commands into orchestration.
- CLI entry → Slash cmds: routes slash commands · CLI forwards slash and mutation commands.
- Query engine → Agent loop: runs agent loop · Facade invokes the core runtime for a turn.
- Agent loop → Prompt build: builds prompt · Agent loop assembles the system and turn prompt.
- Agent loop → Workspace ctx: loads context · Agent loop gathers workspace and repository context.
- Agent loop → Token usage: estimates tokens · Context usage informs reporting and truncation decisions.
- Agent loop → Session state: restores state · Run resumes from persisted session state.
- Session state → Session store: reads/writes · Session state is backed by local storage.
- Agent loop → Transcript: persists transcript · Completed turns and edits are saved as transcript history.
- Agent loop → Agent tools: invokes tools · Core loop hands model tool calls to the tool boundary.
- Agent tools → Tool surface: exposes surface · Agent tools are defined by the shared tool surface.
- Agent tools → Tool pool: resolves tools · Tool requests are mapped into executable tool instances.
- Tool pool → Exec registry: executes through · Resolved tools are executed by the registry.
- Exec registry → Permissions: checks permission · Tool execution is gated by permissions.
- Exec registry → Bash safety: checks shell safety · Shell-related execution is filtered by bash policy.
- Exec registry → Cost tracker: charges budget · Tool and model activity updates cost tracking.
- Agent loop → Model API: calls API · Core loop streams and receives chat-completions responses.
- Agent loop → Compaction: compacts context · Large prompts are truncated or compacted before retry.
- Compaction → Tokenizer: measures tokens · Compaction depends on tokenizer-aware accounting.
- Plugins → Hook policy: governs hooks · Plugin behavior is constrained by local hook policy.
- Plugins → Agent loop: modifies flow · Plugins can alter prompting, resume, persistence, and delegation.
- Agent manager → Agent loop: coordinates nested runs · Delegated and nested agent execution is tracked across runs.
- CLI entry → Search runtime: search commands · CLI surfaces search-oriented local runtime actions.
- CLI entry → MCP runtime: mcp commands · CLI surfaces MCP runtime actions.
- CLI entry → Remote runtime: remote commands · CLI surfaces remote-control actions.
- CLI entry → Background: daemon commands · CLI launches background and daemon workflows.
- CLI entry → Plan runtime: plan commands · CLI exposes planning state actions.
- CLI entry → Task runtime: task commands · CLI exposes task coordination actions.
- CLI entry → Team runtime: team commands · CLI exposes team coordination actions.
- CLI entry → Workflow runtime: workflow commands · CLI exposes reusable workflow actions.
- CLI entry → Trigger runtime: trigger commands · CLI exposes trigger management actions.
- CLI entry → Worktree runtime: worktree commands · CLI exposes workspace and worktree actions.