# Claw Code Agent

> A Python reimplementation of the Claude Code agent architecture that runs with local open-source models via any OpenAI-compatible API, with zero external dependencies.

Claw Code Agent is a Python reimplementation of the Claude Code npm agent architecture, built by HarnessLab to run entirely with local open-source models via any OpenAI-compatible API server. The project is hosted on GitHub under the HarnessLab organization and is currently in alpha status, with active development tracked against the original npm source in a public parity checklist.

## What It Is

Claw Code Agent is a CLI-first agentic coding tool that replicates the full Claude Code agent flow — prompt assembly, context building, slash commands, tool calling, and session persistence — entirely in Python with zero external dependencies beyond the standard library. It targets developers who want a self-hosted, locally-controlled coding agent without relying on Anthropic's hosted service. The core runtime works with vLLM, Ollama, LiteLLM Proxy, or OpenRouter as the model backend, and recommends `Qwen3-Coder-30B-A3B-Instruct` as the primary model.

## Architecture and Runtime Surface

The project is organized around a modular Python runtime with clearly separated concerns:

- **Agent loop** (`agent_runtime.py`): Core iterative reasoning and tool-calling loop
- **Tool engine** (`agent_tools.py`): File read/write/edit, glob/grep search, shell execution, web fetch, and notebook editing
- **Plugin runtime** (`plugin_runtime.py`): Manifest-based plugins with hooks, aliases, virtual tools, and tool blocking
- **MCP runtime** (`mcp_runtime.py`): Local MCP manifest discovery and real stdio MCP transport
- **LSP runtime** (`lsp_runtime.py`): Local LSP-style code intelligence for definitions, references, hover, symbols, and diagnostics
- **Session store** (`session_store.py`): Resumable sessions with file-history journaling and snapshot IDs
- **Local web GUI** (`src/gui`): FastAPI + vanilla JS SPA launched via `python -m src.gui`

The permission model uses four tiers — read-only (default), write (`--allow-write`), shell (`--allow-shell`), and unsafe (`--unsafe`) — to keep the agent safe by default.

## Deployment Model

Claw Code Agent runs entirely locally. Users clone the repository, configure environment variables pointing to a local or remote OpenAI-compatible API endpoint, and invoke the agent via `python3 -m src.main`. The GUI launches a local FastAPI server on port 8765. No cloud account or API key is required when using a local vLLM or Ollama backend. For cloud access, OpenRouter is supported as an optional gateway to models from OpenAI, Anthropic, Google, and others.

Supported backends:
- **vLLM** (recommended, with `qwen3_xml` tool-call parser for Qwen3-Coder)
- **Ollama** (OpenAI-compatible API, tool-capable models required)
- **LiteLLM Proxy** (gateway to many providers)
- **OpenRouter** (cloud API gateway, no local model server required)

## Update: April 2026 Major Release

The April 2026 update is a large feature expansion. Notable additions include:

- **Interactive Chat Mode** (`agent-chat` command) with multi-turn REPL
- **Local Web GUI** with dark theme, sessions browser, slash command palette, tasks/plan/memory/history/worktree/skills/accounts/remote/MCP/plugins/ask/workflows/search/triggers/teams/diagnostics tabs
- **Plugin Runtime** with manifest-based hooks, tool aliases, virtual tools, and tool blocking
- **Nested Agent Delegation** with dependency-aware topological batching and agent manager lineage tracking
- **LSP Runtime** for local code intelligence
- **Tokenizer-Aware Context** with cached backends and heuristic fallback
- **Prompt Budget Preflight** with auto-compact/context collapse before backend failures
- **Streaming output** via `--stream` flag
- **Ollama, LiteLLM Proxy, and OpenRouter** backend support added alongside vLLM

The repository reports 484 stars and 207 forks as of the last recorded update (May 2026), with the last push on April 22, 2026.

## Parity and Current Status

The project tracks implementation status against the original npm Claude Code source in a public `PARITY_CHECKLIST.md`. Areas marked in-progress include full MCP parity beyond the current stdio transport, full slash-command parity, full interactive REPL/TUI behavior, voice and VIM modes, and editor/platform integrations. The project self-describes as alpha status.

## Features
- Full agentic coding loop with tool calling and iterative reasoning
- Interactive multi-turn chat mode via agent-chat command
- Local web GUI (FastAPI + vanilla JS SPA) with dark theme
- Zero external dependencies — pure Python standard library
- OpenAI-compatible backend support (vLLM, Ollama, LiteLLM Proxy, OpenRouter)
- Qwen3-Coder-30B-A3B-Instruct first-class support via vLLM
- Token-by-token streaming output with --stream flag
- Manifest-based plugin runtime with hooks, aliases, virtual tools, tool blocking
- Nested agent delegation with dependency-aware topological batching
- Custom agent profiles from ~/.claude/agents and ./.claude/agents
- Session persistence with file-history journaling and snapshot IDs
- LSP-style code intelligence (definitions, references, hover, symbols, diagnostics)
- Tokenizer-aware context accounting with cached backends
- Prompt budget preflight with auto-compact and context collapse
- Cost tracking and budget enforcement (token, cost, tool-call, model-call limits)
- Structured output / JSON schema response mode
- MCP runtime with local manifest discovery and real stdio MCP transport
- Search runtime with provider-backed web_search
- Tiered permission system (read-only, write, shell, unsafe)
- Background sessions with daemon-style wrapper
- Managed git worktree runtime with live cwd switching
- Notebook editing for .ipynb files
- Slash commands for context, config, account, search, MCP, remote, tasks, plan, hooks, and model control
- Context compaction with auto-snip, auto-compact, and reactive compaction

## Integrations
vLLM, Ollama, LiteLLM Proxy, OpenRouter, Qwen3-Coder, FastAPI, Uvicorn, MCP (Model Context Protocol), SearXNG, Brave Search, Tavily, Jupyter Notebooks, Git worktrees

## Platforms
CLI, WEB, API

## Pricing
Open Source

## Version
alpha

## Links
- Website: https://github.com/HarnessLab/claw-code-agent
- Documentation: https://github.com/HarnessLab/claw-code-agent/blob/main/TESTING_GUIDE.md
- Repository: https://github.com/HarnessLab/claw-code-agent
- EveryDev.ai: https://www.everydev.ai/tools/claw-code-agent