A Python reimplementation of the Claude Code agent architecture — local models, full control, zero dependencies.
- 🚀 Interactive Chat Mode: Multi-turn REPL with
/exitto quit - 📡 Streaming Output: Token-by-token streaming with
--streamflag - 🛠️ Plugin Runtime: Full manifest-based plugin system
- 🔗 Nested Agent Delegation: Subtask delegation with topological batching
- 📊 Agent Manager: Lineage tracking and batch summaries
- 📝 Custom Agent Profiles: Local markdown-defined agents
- 💰 Cost Tracking: Token budgets, cost limits, tool-call limits
- 📜 Structured Output: JSON schema response mode
- 🗜️ Context Compaction: Auto-snip, auto-compact, reactive compaction
- 📝 File History Replay: Journaling and replay summaries
- 🔄 Truncation Continuation: Automatic continuation on cut-off responses
- 🐳 Ollama Support: Out-of-the-box OpenAI-compatible API
- 🌐 LiteLLM Proxy Support: Route to any provider
- 🌍 OpenRouter Support: Cloud API gateway access
- 🔍 Query Engine: Runtime event counters and orchestration reports
- 🖥️ Remote Runtime: Manifest-backed local remote profiles
- 🛡️ Hook & Policy Runtime: Local policy manifests and trust reporting
- 📋 Task & Plan Runtime: Persistent local tasks and plans
- 📦 MCP Transport: Real stdio MCP transport
- 🔍 Search Runtime: Provider-backed
web_search - ⚙️ Config & Account Runtime: Local config mutation and account profiles
- 💬 Ask-User Runtime: Queued or interactive user questions
- 👥 Team Runtime: Persisted local teams and message history
- 📓 Notebook Edit Tool: Native
.ipynbcell editing - 🎛️ Workflow Runtime: Manifest-backed local workflows
- 📡 Remote Trigger Runtime: Local remote triggers
- 🌿 Worktree Runtime: Managed git worktrees
- 🔢 Tokenizer-Aware Context: Cached tokenizer backends
- ⚖️ Prompt Budget Preflight: Token-budget reporting and auto-compact
- 🛠️ LSP Runtime: Local LSP-style code intelligence
- 🌐 Local Web GUI: Browser-based chat UI
- 📜 Daemon Commands: Background session management
- 🔁 Background Sessions: Local background session workflows
| 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 |
| 🌐 Local Web GUI | Browser-based chat UI launched with python -m src.gui |
| 🛠️ 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 |
| 📝 Custom Agents | Load local agent profiles from ~/.claude/agents and ./.claude/agents |
| 📡 Streaming | Token-by-token streaming output with --stream |
| ⌨️ Slash Commands | Local commands for context, config, account, search, MCP, remote, tasks, etc. |
| 🖥️ Remote Runtime | Manifest-backed remote profiles with local remote-mode support |
| 📋 Task & Plan Runtime | Persistent tasks and plans with sync, next-task selection, and blocked/unblocked state |
| 📦 MCP Runtime | Local MCP manifests plus real stdio MCP transport |
| 🔍 Search Runtime | Provider-backed web_search plus provider activation and status reporting |
| ⚙️ Config & Account Runtime | Local config mutation, settings inspection, account profiles, and login/logout state |
| 💬 Ask-User Runtime | Queued answer or interactive user-question flow with history tracking |
| 👥 Team Runtime | Persisted local teams plus message history, handoff notes, and collaboration metadata |
| 📓 Notebook Editing | Native Jupyter notebook cell editing through notebook_edit |
| 🌿 Worktree Runtime | Managed git worktrees with worktree_enter, worktree_exit, and live cwd switching |
| 🎛️ Workflow Runtime | Manifest-backed workflows with slash commands, CLI inspection, and recorded runs |
| 📡 Remote Triggers | Local remote triggers with create/update/run flows and npm-style trigger actions |
| 🛡️ Hook & Policy Runtime | Trust reporting, safe env, managed settings, tool blocking, and budget overrides |
| 🔢 LSP Code Intelligence | Local LSP-style definitions, references, hover, symbols, diagnostics, and call hierarchy |
| 📚 Context Engine | Automatic context building with CLAUDE.md discovery, compaction, and snipping |
| 🔢 Tokenizer-Aware Accounting | Model-aware token counting with cached tokenizer backends and fallback heuristics |
| ⚖️ Prompt Budgeting | Soft/hard prompt-window checks, token-budget reports, and preflight context collapse |
| 💾 Session Persistence | Save and resume agent sessions with file-history replay |
| 📜 Background Sessions | agent-bg and local daemon wrappers for background runs, logs, attach, and kill |
| 💰 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 | Works with vLLM, Ollama, LiteLLM Proxy, OpenRouter |
| 🤖 Qwen3-Coder | First-class support for Qwen3-Coder-30B-A3B-Instruct via vLLM |
| 🚫 Zero Dependencies | Pure Python standard library — nothing to install |
This repository reimplements the Claude Code npm agent architecture entirely in Python, designed to run with local open-source models via an OpenAI-compatible API server.
Built on the public porting workspace from instructkr/claw-code, the active development lives at aliii-codes/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.
| Category | Technologies |
|---|---|
| Language | Python 3.10+ |
| Model Server | vLLM, Ollama, LiteLLM Proxy, OpenRouter |
| Model | Qwen3-Coder-30B-A3B-Instruct (recommended) |
| GUI | FastAPI, Uvicorn, Vanilla JS |
| Testing | Unittest |
| Packaging | setuptools, pyproject.toml |
-
Clone the repository
git clone https://github.com/aliii-codes/claw-code-agent.git cd claw-code-agent -
Start vLLM with Qwen3-Coder
python -m vllm.entrypoints.openai.api_server \ --model Qwen/Qwen3-Coder-30B-A3B-Instruct \ --host 127.0.0.1 \ --port 8000 \ --enable-auto-tool-choice \ --tool-call-parser qwen3_xml
-
Verify the server
curl http://127.0.0.1:8000/v1/models
-
Configure environment variables
export OPENAI_BASE_URL=http://127.0.0.1:8000/v1 export OPENAI_API_KEY=local-token export OPENAI_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
-
Run the agent
python3 -m src.main agent "Read src/agent_runtime.py and summarize the loop." --cwd .
| Command | Description |
|---|---|
agent <prompt> |
Run the agent with a prompt |
agent-chat [prompt] |
Start interactive multi-turn chat mode |
agent-bg <prompt> |
Run the agent in a local background session |
agent-ps |
List local background sessions |
agent-logs <id> |
Show background session logs |
agent-attach <id> |
Show the current background output snapshot |
agent-kill <id> |
Stop a background session |
daemon <subcommand> |
Daemon-style wrapper over local background sessions |
agent-prompt |
Show the assembled system prompt |
agent-context |
Show estimated context usage |
agent-context-raw |
Show the raw context snapshot |
token-budget |
Show prompt-window budget, reserves, and soft/hard input limits |
agents [agent_type] |
List active local agent definitions or show one agent profile |
agents-create <agent_type> |
Create a project or user agent definition markdown file |
agents-update <agent_type> |
Update an existing project or user agent definition |
agents-delete <agent_type> |
Delete an existing project or user agent definition |
agent-resume <id> <prompt> |
Resume a saved session |
| Flag | Description |
|---|---|
--cwd <path> |
Set the workspace directory |
--model <name> |
Override the model name |
--base-url <url> |
Override the API base URL |
--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 |
--scratchpad-root <path> |
Override the scratchpad directory |
--system-prompt <text> |
Set a custom system prompt |
--append-system-prompt <text> |
Append to the system prompt |
--override-system-prompt <text> |
Replace the generated system prompt |
--add-dir <path> |
Add extra directories to context |
claw-code-agent/
├── images/
│ ├── logo.png
│ └── demo_2.gif
├── src/
│ ├── QueryEngine.py
│ ├── Tool.py
│ ├── __init__.py
│ ├── agent_context.py
│ ├── agent_context_usage.py
│ ├── agent_memory.py
│ ├── agent_prompting.py
│ ├── agent_runtime.py
│ ├── agent_session.py
│ ├── agent_slash_commands.py
│ ├── agent_tools.py
│ ├── agent_types.py
│ ├── bootstrap_graph.py
│ ├── command_graph.py
│ ├── commands.py
│ ├── context.py
│ ├── costHook.py
│ ├── cost_tracker.py
│ ├── deferred_init.py
│ ├── dialogLaunchers.py
│ ├── direct_modes.py
│ ├── dotenv_loader.py
│ ├── execution_registry.py
│ ├── history.py
│ ├── ink.py
│ ├── interactiveHelpers.py
│ ├── main.py
│ ├── models.py
│ ├── openai_compat.py
│ ├── parity_audit.py
│ ├── permissions.py
│ ├── port_manifest.py
│ ├── prefetch.py
│ ├── projectOnboardingState.py
│ ├── query.py
│ ├── query_engine.py
│ ├── remote_runtime.py
│ ├── replLauncher.py
│ ├── runtime.py
│ ├── session_store.py
│ ├── setup.py
│ ├── system_init.py
│ ├── task.py
│ ├── tasks.py
│ ├── tool_pool.py
│ ├── tools.py
│ ├── transcript.py
│ ├── web_server.py
│ └── gui/
│ ├── __main__.py
│ ├── server.py
│ └── static/
│ ├── index.html
│ ├── app.css
│ └── app.js
├── tests/
│ ├── test_agent_context.py
│ ├── test_agent_context_usage.py
│ └── test_agent_memory.py
├── pyproject.toml
└── README.md
Contributions are welcome! Please follow these steps:
- Fork the repository.
- Create a new branch (
git checkout -b feature/YourFeature). - Commit your changes (
git commit -m 'Add some feature'). - Push to the branch (
git push origin feature/YourFeature). - Open a pull request.
Please use the issue tracker to report bugs or request features.
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ by the aliii-codes team.
Built with 🐍 Python · Powered by 🐉 HarnessLab Team.