diff --git a/README.md b/README.md index 200ed89..4e97112 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

Claw Code Agent

- A Python reimplementation of the Claude Code agent architecture โ€” local models, full control. + A Python reimplementation of the Claude Code agent architecture โ€” local models, full control, zero dependencies.

@@ -13,12 +13,38 @@ GitHub vLLM Qwen3-Coder + Zero Dependencies Alpha License

--- +## ๐Ÿ“ข What's New + +> **April 2026 โ€” Major Update** + +| | Feature | Details | +|---|---------|---------| +| ๐Ÿ†• | **Interactive Chat Mode** | New `agent-chat` command โ€” multi-turn REPL with `/exit` to quit | +| ๐Ÿ†• | **Streaming Output** | Token-by-token streaming with `--stream` flag | +| ๐Ÿ†• | **Plugin Runtime** | Full manifest-based plugin system โ€” hooks, tool aliases, virtual tools, tool blocking | +| ๐Ÿ†• | **Nested Agent Delegation** | Delegate subtasks to child agents with dependency-aware topological batching | +| ๐Ÿ†• | **Agent Manager** | Lineage tracking, group membership, batch summaries for nested agents | +| ๐Ÿ†• | **Cost Tracking & Budgets** | Token budgets, cost budgets, tool-call limits, model-call limits, session-turn limits | +| ๐Ÿ†• | **Structured Output** | JSON schema response mode with `--response-schema-file` | +| ๐Ÿ†• | **Context Compaction** | Auto-snip, auto-compact, and reactive compaction on prompt-too-long errors | +| ๐Ÿ†• | **File History Replay** | Journaling of file edits with snapshot IDs, replay summaries on session resume | +| ๐Ÿ†• | **Truncation Continuation** | Automatic continuation when model response is cut off (`finish_reason=length`) | +| ๐Ÿ†• | **Ollama Support** | Works out of the box with Ollama's OpenAI-compatible API | +| ๐Ÿ†• | **LiteLLM Proxy Support** | Route through LiteLLM Proxy to any provider | +| ๐Ÿ†• | **OpenRouter Support** | Cloud API gateway โ€” access OpenAI, Anthropic, Google models via one endpoint | +| ๐Ÿ†• | **Query Engine** | Runtime event counters, transcript summaries, orchestration reports | +| ๐Ÿ†• | **Testing Guide** | Comprehensive [TESTING_GUIDE.md](TESTING_GUIDE.md) with commands for every feature | +| ๐Ÿ†• | **Parity Checklist** | Full [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) tracking implementation status vs npm source | + +--- + ## ๐Ÿ“– About This repository reimplements the [Claude Code](https://docs.anthropic.com/en/docs/claude-code) npm agent architecture **entirely in Python**, designed to run with **local open-source models** via an OpenAI-compatible API server. @@ -26,6 +52,8 @@ This repository reimplements the [Claude Code](https://docs.anthropic.com/en/doc Built on the public porting workspace from [instructkr/claw-code](https://github.com/instructkr/claw-code), the active development lives at [HarnessLab/claw-code-agent](https://github.com/HarnessLab/claw-code-agent). > **Goal:** Not to ship the original npm source, but to reimplement the full agent flow in Python โ€” prompt assembly, context building, slash commands, tool calling, session persistence, and local model execution. +> +> **Zero external dependencies** โ€” just Python's standard library.

Claw Code Agent demo @@ -38,48 +66,73 @@ Built on the public porting workspace from [instructkr/claw-code](https://github | Feature | Description | |---------|-------------| | ๐Ÿค– **Agent Loop** | Full agentic coding loop with tool calling and iterative reasoning | +| ๐Ÿ’ฌ **Interactive Chat** | Multi-turn REPL via `agent-chat` with session continuity | | ๐Ÿงฐ **Core Tools** | File read / write / edit, glob search, grep search, shell execution | +| ๐Ÿ”Œ **Plugin Runtime** | Manifest-based plugins with hooks, aliases, virtual tools, and tool blocking | +| ๐Ÿช† **Nested Delegation** | Delegate subtasks to child agents with dependency-aware topological batching | +| ๐Ÿ“ก **Streaming** | Token-by-token streaming output with `--stream` | | ๐Ÿ’ฌ **Slash Commands** | Local commands: `/help`, `/context`, `/tools`, `/memory`, `/status`, `/model`, and more | -| ๐Ÿง  **Context Engine** | Automatic context building with CLAUDE.md discovery and usage reporting | -| ๐Ÿ”„ **Session Persistence** | Save and resume agent sessions across runs | +| ๐Ÿง  **Context Engine** | Automatic context building with CLAUDE.md discovery, compaction, and snipping | +| ๐Ÿ”„ **Session Persistence** | Save and resume agent sessions with file-history replay | +| ๐Ÿ’ฐ **Cost & Budget Control** | Token budgets, cost limits, tool-call caps, model-call caps | +| ๐Ÿ“‹ **Structured Output** | JSON schema response mode for programmatic use | | ๐Ÿ” **Permission System** | Granular control: `--allow-write`, `--allow-shell`, `--unsafe` | -| ๐Ÿ—๏ธ **OpenAI-Compatible Runtime** | Python client targets an OpenAI-compatible API, with `vLLM` as the documented setup | +| ๐Ÿ—๏ธ **OpenAI-Compatible** | Works with vLLM, Ollama, LiteLLM Proxy, OpenRouter โ€” any OpenAI-compatible API | | ๐Ÿ‰ **Qwen3-Coder** | First-class support for `Qwen3-Coder-30B-A3B-Instruct` via vLLM | +| ๐Ÿ“ฆ **Zero Dependencies** | Pure Python standard library โ€” nothing to install | --- ## ๐Ÿ“‹ Roadmap -### Testing +### ๐Ÿ“š Documentation -- See [TESTING_GUIDE.md](TESTING_GUIDE.md) for concrete commands to verify the current implementation feature by feature. +| Document | Description | +|----------|-------------| +| [TESTING_GUIDE.md](TESTING_GUIDE.md) | Step-by-step commands to verify every feature | +| [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) | Full implementation status vs the npm source | -### Done +### โœ… Done - [x] Python CLI agent loop +- [x] Interactive chat mode (`agent-chat`) with multi-turn REPL - [x] OpenAI-compatible local model backend - [x] Qwen3-Coder support through vLLM with `qwen3_xml` tool parser +- [x] Ollama, LiteLLM Proxy, and OpenRouter backends - [x] Core tools: `list_dir`, `read_file`, `write_file`, `edit_file`, `glob_search`, `grep_search`, `bash` - [x] Context building and `/context`-style usage reporting - [x] Slash commands: `/help`, `/context`, `/context-raw`, `/prompt`, `/permissions`, `/model`, `/tools`, `/memory`, `/status`, `/clear` - [x] Session persistence and `agent-resume` flow - [x] Permission system (read-only, write, shell, unsafe tiers) +- [x] Streaming token-by-token assistant output +- [x] Truncated-response continuation flow +- [x] Auto-snip and auto-compact context reduction +- [x] Reactive compaction retry on prompt-too-long errors +- [x] Cost tracking and usage budget enforcement +- [x] Token, tool-call, model-call, and session-turn budgets +- [x] Structured output / JSON schema response mode +- [x] File history journaling with snapshot IDs and replay summaries +- [x] Nested agent delegation with dependency-aware topological batching +- [x] Agent manager with lineage tracking and group membership +- [x] Plugin runtime: manifest discovery, hooks, aliases, virtual tools, tool blocking +- [x] Plugin lifecycle hooks: resume, persist, delegate phases +- [x] Plugin session-state persistence and resume restoration +- [x] Query engine facade driving the real Python runtime +- [x] Compaction metadata with lineage IDs and revision summaries - [x] Unit tests for the Python runtime - [x] `pyproject.toml` packaging with `setuptools` -### In Progress +### ๐Ÿ”ฒ In Progress -- [ ] Full MCP support -- [ ] Full plugin system -- [ ] Full slash-command parity +- [ ] Full MCP server support +- [ ] Full slash-command parity with npm runtime - [ ] Full interactive REPL / TUI behavior -- [ ] Exact tokenizer / context accounting -- [ ] Hooks parity -- [ ] Remote modes parity -- [ ] Voice / VIM parity -- [ ] Some deeper runtime details from the npm source -- [ ] Cost tracking and budget limits - +- [ ] Exact tokenizer-accurate context accounting +- [ ] Hooks system parity +- [ ] Remote runtime modes (SSH, teleport, deep-link) +- [ ] Voice and VIM modes +- [ ] Editor and platform integrations +- [ ] Background and team features --- @@ -88,11 +141,13 @@ Built on the public porting workspace from [instructkr/claw-code](https://github ```text claw-code/ โ”œโ”€โ”€ README.md +โ”œโ”€โ”€ TESTING_GUIDE.md # How to test every feature +โ”œโ”€โ”€ PARITY_CHECKLIST.md # Implementation status vs npm source โ”œโ”€โ”€ pyproject.toml โ”œโ”€โ”€ .gitignore โ”œโ”€โ”€ images/ โ”‚ โ””โ”€โ”€ logo.png -โ”œโ”€โ”€ src/ # Python implementation +โ”œโ”€โ”€ src/ # Python implementation (75+ modules) โ”‚ โ”œโ”€โ”€ main.py # CLI entry point & argument parsing โ”‚ โ”œโ”€โ”€ agent_runtime.py # Core agent loop (LocalCodingAgent) โ”‚ โ”œโ”€โ”€ agent_tools.py # Tool definitions & execution engine @@ -101,14 +156,19 @@ claw-code/ โ”‚ โ”œโ”€โ”€ agent_context_usage.py # Context usage estimation & reporting โ”‚ โ”œโ”€โ”€ agent_session.py # Session state management โ”‚ โ”œโ”€โ”€ agent_slash_commands.py # Local slash command processing +โ”‚ โ”œโ”€โ”€ agent_manager.py # Nested agent lineage & group tracking โ”‚ โ”œโ”€โ”€ agent_types.py # Shared dataclasses & type definitions -โ”‚ โ”œโ”€โ”€ openai_compat.py # OpenAI-compatible API client +โ”‚ โ”œโ”€โ”€ openai_compat.py # OpenAI-compatible API client (streaming) +โ”‚ โ”œโ”€โ”€ plugin_runtime.py # Plugin manifest, hooks, aliases, virtual tools +โ”‚ โ”œโ”€โ”€ agent_plugin_cache.py # Plugin discovery & prompt injection cache โ”‚ โ”œโ”€โ”€ session_store.py # Session serialization & persistence +โ”‚ โ”œโ”€โ”€ transcript.py # Transcript block export & mutation tracking +โ”‚ โ”œโ”€โ”€ query_engine.py # Query engine facade & runtime orchestration โ”‚ โ”œโ”€โ”€ permissions.py # Tool permission filtering +โ”‚ โ”œโ”€โ”€ cost_tracker.py # Cost & budget enforcement โ”‚ โ”œโ”€โ”€ tools.py # Mirrored tool inventory โ”‚ โ”œโ”€โ”€ commands.py # Mirrored command inventory -โ”‚ โ”œโ”€โ”€ ... # 75+ modules across 30+ packages -โ”‚ โ”œโ”€โ”€ plugins/ # Plugin subsystem (WIP) +โ”‚ โ”œโ”€โ”€ plugins/ # Plugin subsystem โ”‚ โ”œโ”€โ”€ hooks/ # Hook system (WIP) โ”‚ โ”œโ”€โ”€ remote/ # Remote runtime modes (WIP) โ”‚ โ”œโ”€โ”€ voice/ # Voice mode (WIP) @@ -119,6 +179,8 @@ claw-code/ โ”œโ”€โ”€ test_agent_context_usage.py โ”œโ”€โ”€ test_agent_prompting.py โ”œโ”€โ”€ test_agent_slash_commands.py + โ”œโ”€โ”€ test_main.py + โ”œโ”€โ”€ test_query_engine_runtime.py โ””โ”€โ”€ test_porting_workspace.py ``` @@ -129,6 +191,7 @@ claw-code/ | Requirement | Details | |-------------|---------| | ๐Ÿ Python | `3.10` or higher | +| ๐Ÿ“š Dependencies | **None** โ€” pure Python standard library | | ๐Ÿ–ฅ๏ธ Model Server | `vLLM`, `Ollama`, `LiteLLM Proxy`, or `OpenRouter`, with tool calling support | | ๐Ÿง  Model | [`Qwen/Qwen3-Coder-30B-A3B-Instruct`](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct) (recommended) | @@ -285,6 +348,14 @@ python3 -m src.main agent \ python3 -m src.main agent \ "Run pwd and ls src, then summarize the result." \ --cwd . --allow-shell + +# Interactive chat mode +python3 -m src.main agent-chat --cwd . + +# Streaming output +python3 -m src.main agent \ + "Explain the current architecture." \ + --cwd . --stream ``` --- @@ -296,6 +367,7 @@ python3 -m src.main agent \ | Command | Description | |---------|-------------| | `agent ` | Run the agent with a prompt | +| `agent-chat [prompt]` | Start interactive multi-turn chat mode | | `agent-prompt` | Show the assembled system prompt | | `agent-context` | Show estimated context usage | | `agent-context-raw` | Show the raw context snapshot | @@ -311,11 +383,45 @@ python3 -m src.main agent \ | `--allow-write` | Allow the agent to modify files | | `--allow-shell` | Allow the agent to execute shell commands | | `--unsafe` | Allow destructive shell operations | +| `--stream` | Enable token-by-token streaming output | | `--show-transcript` | Print the full message transcript | | `--system-prompt ` | Set a custom system prompt | | `--append-system-prompt ` | Append to the system prompt | | `--add-dir ` | Add extra directories to context | +### Budget & Limit Flags + +| Flag | Description | +|------|-------------| +| `--max-total-tokens ` | Total token budget | +| `--max-input-tokens ` | Input token budget | +| `--max-output-tokens ` | Output token budget | +| `--max-reasoning-tokens ` | Reasoning token budget | +| `--max-budget-usd ` | Maximum cost in USD | +| `--max-tool-calls ` | Maximum tool calls per run | +| `--max-delegated-tasks ` | Maximum delegated subtasks | +| `--max-model-calls ` | Maximum model API calls | +| `--max-session-turns ` | Maximum session turns | +| `--input-cost-per-million ` | Input token pricing | +| `--output-cost-per-million ` | Output token pricing | + +### Context Control Flags + +| Flag | Description | +|------|-------------| +| `--auto-snip-threshold ` | Auto-snip older messages at this token count | +| `--auto-compact-threshold ` | Auto-compact at this token count | +| `--compact-preserve-messages ` | Messages to preserve during compaction | +| `--disable-claude-md` | Disable CLAUDE.md discovery | + +### Structured Output Flags + +| Flag | Description | +|------|-------------| +| `--response-schema-file ` | JSON schema file for structured output | +| `--response-schema-name ` | Schema name identifier | +| `--response-schema-strict` | Enforce strict schema validation | + ### Slash Commands These are handled **locally** before the model loop: @@ -351,7 +457,6 @@ python3 -m src.main tools --limit 10 # Tool inventory --- - ## ๐Ÿ”ง Built-in Tools The agent has access to 7 core tools: @@ -368,6 +473,54 @@ The agent has access to 7 core tools: --- +## ๐Ÿ”Œ Plugin System + +Claw Code Agent supports a **manifest-based plugin runtime**. Drop a `plugin.json` in a `plugins/` subdirectory: + +```json +{ + "name": "my-plugin", + "hooks": { + "beforePrompt": "Inject guidance into the system prompt.", + "afterTurn": "Run after each agent turn.", + "onResume": "Reapply state on session resume.", + "beforePersist": "Save state before session is saved.", + "beforeDelegate": "Inject guidance before child agents.", + "afterDelegate": "Process child agent results." + }, + "toolAliases": [ + { "name": "my_read", "baseTool": "read_file", "description": "Custom read alias." } + ], + "virtualTools": [ + { "name": "my_tool", "description": "A virtual tool.", "responseTemplate": "result: {input}" } + ] +} +``` + +> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 13** for full plugin testing commands. + +--- + +## ๐Ÿช† Nested Agent Delegation + +The agent can delegate subtasks to child agents with full context carryover: + +```bash +python3 -m src.main agent \ + "Delegate a subtask to inspect src/agent_runtime.py and return a summary." \ + --cwd . --show-transcript +``` + +Features: +- Sequential and parallel subtask execution +- Dependency-aware topological batching +- Child-session save and resume +- Agent manager lineage tracking + +> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 12** for delegation testing commands. + +--- + ## ๐Ÿ”„ Session Persistence Each `agent` run automatically saves a resumable session: @@ -385,6 +538,14 @@ python3 -m src.main agent-resume \ "Continue the previous task and finish the missing parts." ``` +Resume directly into interactive chat: + +```bash +python3 -m src.main agent-chat \ + --resume-session-id \ + --cwd . +``` + Inspect saved sessions: ```bash @@ -413,6 +574,8 @@ python3 -m src.main agent \ --cwd . ``` +> ๐Ÿ“š **Full testing guide:** See [TESTING_GUIDE.md](TESTING_GUIDE.md) for step-by-step commands covering all 16 feature areas. + --- ## ๐Ÿ” Permission Model @@ -426,27 +589,13 @@ Claw Code Agent uses a **tiered permission system** to keep the agent safe by de | **Shell** | + shell command execution | `--allow-shell` | | **Unsafe** | + destructive shell operations | `--unsafe` | -## ๐Ÿ”Ž Detailed Parity Status Against npm `src` +--- -The full implementation checklist now lives in [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md). +## ๐Ÿ”Ž Parity Status -It breaks parity down by: +The full implementation checklist tracking parity against the npm `src` lives in [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md). -- core agent runtime -- CLI/runtime modes -- prompt assembly -- context and memory -- slash commands -- built-in tools -- commands and task systems -- permissions, hooks, and policy -- MCP, plugins, and skills -- interactive REPL / TUI -- remote, background, and team features -- editor, platform, and native integrations -- services and internal subsystems -- mirrored workspace versus working runtime -- high-priority next steps +It covers: core runtime, CLI modes, prompt assembly, context/memory, slash commands, tools, permissions, plugins, MCP, REPL/TUI, remote features, editor integrations, and internal subsystems. --- @@ -459,5 +608,5 @@ It breaks parity down by: ---

- Built with ๐Ÿ Python ยท Powered by ๐Ÿ‰ HarnessLab Team. + Built with ๐Ÿ Python ยท Powered by ๐Ÿ‰ HarnessLab Team.