claw-code-agent: a Python rewrite of the Claude Code agent loop

The premise is a local model and a language you can read

The readme describes the project as a Python reimplementation of the Claude Code agent architecture with local models, full control and zero dependencies, and the repository description says it plainly: Claw Code, no Rust, no TypeScript, only Python, easy to work with, fast to iterate.

The local model part is the point rather than a detail. The badges name a vLLM backend and a Qwen3-Coder model, and the feature list adds Ollama support that works out of the box with Ollama's OpenAI compatible API, LiteLLM Proxy support to route through any provider, and OpenRouter support as a cloud API gateway for accessing OpenAI, Anthropic and Google models through one endpoint.

So the agent loop is not tied to one vendor's API. The model is behind a compatibility boundary, and a local vLLM server running an open weights coding model is treated as a first class target rather than a fallback.

The language choice follows from that. The original architecture is implemented in Rust in places, and this project is explicitly the version where the same ideas are in Python, which is the point at which you can read the loop, print state out of it, and change it without fighting a borrow checker. The classifiers back that up: Programming Language :: Python :: 3, and Python 3.10 through 3.12.

The package installs two entry points, which tells you the project has two surfaces.

[project.scripts]
claw-code-agent = "src.main:main"
claw-code-gui = "src.gui.__main__:main"

One is the terminal agent and one is the graphical interface, and the readme describes the latter as a browser based chat UI launched with python -m src.gui, with a dark theme, a slash command palette, a session browser and a settings panel.

One inconsistency is worth naming at this point. The badge in the readme header says zero dependencies, and the repository description repeats zero external dependencies, but the package manifest lists three: fastapi, uvicorn and pydantic.

dependencies = [
  "fastapi>=0.110",
  "uvicorn>=0.27",
  "pydantic>=2.5",
]

That is a small thing, but for a project whose argument is that you can read and run the whole thing, the meaning of zero dependencies matters.

Budgets, limits and context management are the serious parts

The April 2026 update table in the readme is long, and most entries are of two kinds: plumbing for the agent loop, and controls around it. The controls are the more interesting half.

There is a cost and budget system. Token budgets, cost budgets, tool call limits, model call limits and session turn limits, all of which also appear in the GUI, where an advanced settings disclosure exposes every BudgetConfig field, with a blank input clearing a limit. That is a design decision: a local model run has a cost either way, and for an open weights model the cost is compute you are paying for in electricity, so putting a ceiling on it is the same discipline you would apply to an API key.

Then there is context management, which is where an agent loop actually fails. The feature list names auto-snip, auto-compact and reactive compaction on prompt too long errors, and a separate entry for tokenizer aware context with cached tokenizer backends and a heuristic fallback, used by the slash commands /context and /status. There is also prompt budget preflight, which validates prompt length before the backend fails, reports token budgets and auto-compacts or collapses the context first, and truncation continuation, which picks up automatically when a model response is cut off because the finish reason was length.

That last one addresses a failure mode specific to local models. A hosted endpoint will usually stream a complete answer, but a local server with a limited context window will stop mid-sentence, and an agent that treats that as the end of the turn will act on a truncated instruction. The readme also lists a file history replay feature that journals file edits with identifiers and produces replay summaries when a session resumes.

So the architecture is not just a loop. It is a loop with a memory budget, a cost ceiling, and a recovery path for a backend that truncates. The readme points to the /context and /status slash commands as the place to see what the agent thinks it is carrying.

The plugin, hook and policy runtimes are local by construction

Several entries in the update table describe mechanisms that read manifests from the local filesystem, and that pattern is consistent.

The plugin runtime is described as a full manifest based plugin system with hooks, tool aliases, virtual tools and tool blocking. The hook and policy runtime uses local .claw-policy.json and hook manifests, with trust reporting, a safe environment, tool blocking and budget overrides. The remote runtime is described as manifest backed local remote profiles with connect and disconnect state, and the search runtime is provider backed with local manifests and activation state.

The agent profiles entry is the clearest example. Custom agent profiles discover local markdown defined agents from ~/.claude/agents and ./.claude/agents, and they are used through the Agent tool. So the directory layout is deliberately the same as the tool it reimplements, which means a profile you have already written for the original works here.

There is also nested agent delegation, where subtasks are delegated to child agents with dependency aware topological batching, and an agent manager that tracks lineage, group membership and batch summaries for the nested agents. The readme describes a worktree runtime for managed git worktrees with mid session cwd switching, and a task and plan runtime with persistent local tasks and plans plus plan to task sync and dependency aware execution.

The GUI mirrors much of this locally. The tasks tab mutates through TaskRuntime so completing a task auto unblocks dependents the same way the slash command path does. The plan tab saves through PlanRuntime.update_plan and can sync to the task list. The memory tab browses and edits the discovered CLAUDE.md and .claude/rules/*.md files, with writes sandboxed to the workspace plus ~/.claude.

The word local keeps recurring, and it is doing real work. These are file formats, not a hosted service, so a policy file is something you can read, diff and put in your own repository. The cost is that every one of these runtimes is a thing you can misconfigure, and the readme gives no compatibility guarantees beyond the parity checklist.

Where the repository admits what it is still missing

Two files in the repository root are the most useful things in it, and neither is described in the readme.

The first is PARITY_CHECKLIST.md. Given the project is a reimplementation of someone else's architecture, the single most important document for an adopter is a list of what has been ported and what has not, and the project ships exactly that. The readme does not mention it, which is a small editorial failure in an otherwise unusually forthcoming readme.

The second is CLAUDE.md at the root, which in this ecosystem is the memory file the agent reads for project context. The readme's GUI description mentions the memory view discovering CLAUDE.md and .claude/rules/*.md files, so the project both consumes that convention and ships one.

TESTING_GUIDE.md is the third. For a project whose whole premise is behavioural equivalence with an existing tool, a documented testing approach matters more than usual, and its presence suggests the parity claims are checked rather than asserted.

The repository listing also shows src/ as the main package, a tests/ directory, a benchmarks/ directory, images/, harbor_adapter.py, install_dockor.sh and pyproject.toml. The install script's name is worth noting since it carries a typo, and its contents are not visible here, so the installation route beyond the two console scripts is not something the readme documents in detail. The project version in the manifest is 0.1.0 with the classification Development Status :: 3 - Alpha, and the readme badge agrees with alpha.

The last push was on 2026-06-22, which is over three months before the current date, and the repository has no GitHub releases. So the state is a project with a large, actively developed feature set in the readme, no tagged releases to point at, and a version number of 0.1.0. The April 2026 update table is the most recent dated statement of intent, and the repository has moved since then without a release.

Where claw-code-agent is the wrong tool

There are four cases where this is the wrong choice, and the deciding factor in most of them is the alpha status rather than the design.

The first is a production team that needs someone to call when it breaks. The package is marked alpha, there are no GitHub releases, the version is 0.1.0, and the last push was on 2026-06-22. The readme's own warning about the volume of new features cuts both ways: a large surface that is still moving is a large surface you will be reading source code for, not a service you will file a ticket against.

The second is a project whose model is not reachable through the supported backends. The list is vLLM, Ollama, LiteLLM Proxy and OpenRouter. If your model runs behind a different inference server, or you need a specific provider's tool calling or caching behaviour, you are outside the covered set, and the readme does not describe a generic OpenAI compatible fallback beyond Ollama's own API.

The third is a small task that a single prompt handles. There is a lot of machinery here for good reasons, but if you need the agent to edit one file and stop, running a full agent loop with budgets, plugins and a worktree runtime is more surface than the job requires.

The fourth is a team that cannot accept a from scratch reimplementation of a proprietary architecture. Whatever the licensing position of the original turns out to be, a clean room Python implementation carries its own maintenance cost, and a reimplementation will always lag the original in edge cases.

On the alternative, the difference in approach against the original tool is the substrate. Running the original agent means installing it, configuring it for a model provider, and accepting its implementation. Running this one means reading a Python codebase, pointing it at a local vLLM server with open weights, and owning the behaviour end to end. The trade is control and inspectability against stability and support, and the choice depends on whether you need the model to be local, which is a policy requirement in some environments and a preference in others.

The second alternative is to use a local model without an agent loop at all, driving it with a script you write. That is less capable and dramatically more predictable, and for a well defined task it is often the better answer.

The licence is worth checking before you build on it. The licence field on the repository is listed as unknown, and the readme badge says open source, so there is no clear statement of terms in the visible documentation. Read whatever licence file the repository carries before you deploy this, and treat the absence of a stated licence as a blocker rather than a formality.

Editorial conclusion

claw-code-agent suits a developer who wants to run a coding agent against a local model and read the whole implementation in Python, and it does not suit a team that needs a supported, stable tool today, since the project is marked alpha with no GitHub releases and the last push was on 2026-06-22. Before you build on it, check whether your model is reachable through the backends it supports, and read the PARITY_CHECKLIST.md file in the repository root, which is the most direct statement of how close the Python implementation is to the original.

Frequently asked questions

Official sources

1. HarnessLab/claw-code-agent on GitHub
2. Issues
3. README