claw-code

Claw Code is an open-source Rust implementation of the claw CLI agent harness — a purpose-built runtime for autonomous AI coding agents that wraps Claude and OpenAI-compatible APIs with everything needed to operate reliably in automated pipelines. Unlike a simple chat wrapper, it treats clawability (machine-operability without human terminal interaction) as a first-class design constraint.

The project’s architecture separates the concern of provider communication (the api crate), conversation lifecycle (the runtime crate), tool execution (the tools crate), and plugin/hook management (the plugins crate) into a Cargo workspace. This layering means each subsystem can evolve independently and be tested in isolation, while the claw binary in rusty-claude-cli wires them together into a coherent CLI experience.

Claw Code ships features that matter specifically to agentic, automated workflows: automatic session compaction when context windows fill, a structured permission model with four tiered access modes, pre/post-tool hooks that can intercept or override tool calls, MCP (Model Context Protocol) server management with lifecycle hardening, and JSON-mode output across all diagnostic verbs for machine-readable health checks. A companion claw-rag-service crate adds a SQLite-backed embedding index with optional Qdrant integration for retrieval-augmented generation workflows.

The repository is itself an artifact of agent-managed development — described by its authors as a ‘museum exhibit’ run by autonomous claws. This gives Claw Code a unique self-referential quality: the harness is built by the same kind of agents it is designed to power, providing a live demonstration of autonomous coding coordination at scale.

What You Get

• A compiled claw binary built from a structured Rust workspace with separate crates for API communication, conversation runtime, tool execution, and plugin management
• Persistent session storage with automatic compaction when context windows approach token limits, preserving the most recent messages verbatim
• Four-tier permission model (ReadOnly, WorkspaceWrite, DangerFullAccess, Prompt) with hook-based override support for fine-grained tool access control
• Full MCP (Model Context Protocol) server integration with lifecycle hardening, stdio transport, and tool bridging for external tool providers
• Pre- and post-tool-use hooks that execute shell commands before or after any tool call, enabling audit logging, access control, and workflow automation
• A built-in claw-rag-service crate providing a SQLite-backed embedding index with optional Qdrant vector store support for RAG workflows
• JSON-mode output for every diagnostic command (doctor, status, version, sandbox) enabling machine-readable health checks in CI pipelines
• Multi-provider support covering Anthropic (native), OpenAI, xAI, and any OpenAI-compatible API endpoint via configurable base URLs

Common Use Cases

• Running autonomous coding agents that operate without human terminal supervision in CI/CD or Discord-triggered workflows
• Building agent-driven code review, refactoring, or test generation pipelines that need reliable session persistence and context management
• Integrating Claude into local development environments with granular permission controls over which file system paths and tools agents can access
• Connecting external tooling via MCP servers to extend the agent’s capabilities with database access, web search, or custom APIs
• Self-hosting a coding assistant backend that routes to local OpenAI-compatible models (Ollama, LM Studio) without relying on cloud subscriptions
• Implementing structured agent evaluation harnesses using the mock Anthropic service and parity test fixtures included in the workspace

Under The Hood

Architecture Claw Code organizes its Rust workspace into eleven crates with clear boundary responsibilities: rusty-claude-cli is the thin binary entry point that wires runtime, api, commands, plugins, and tools together; runtime owns the conversation lifecycle through ConversationRuntime, session persistence via JSONL rotation, compaction logic in compact.rs, permission enforcement in permissions.rs, hook dispatch in hooks.rs, and MCP lifecycle management in mcp_lifecycle_hardened.rs; api abstracts over Anthropic’s native messages protocol and OpenAI-compatible chat completions through a Provider trait with concrete implementations in providers/anthropic.rs and providers/openai_compat.rs; tools exposes the canonical tool registry and enforces path-scope restrictions; plugins manages hook registration and test isolation. The architecture follows a layered, dependency-injected pattern where ConversationRuntime depends on trait objects (ApiClient, PermissionPrompter, HookProgressReporter) rather than concrete types, enabling the extensive mock infrastructure used in integration tests.

Tech Stack The canonical runtime is pure Rust on the 2021 edition, compiled with Cargo as a workspace. The rusty-claude-cli binary uses Tokio with rt-multi-thread for async I/O, rustyline for readline-style REPL input, crossterm for terminal control, syntect for syntax-highlighted output rendering, and pulldown-cmark for Markdown streaming. Provider communication uses reqwest with rustls-tls for TLS without OpenSSL. Session files are JSONL with size-based rotation (256 KB threshold, three rotated files). The claw-rag-service crate adds an axum HTTP server, rusqlite with bundled SQLite, blake3 for content hashing, and optional qdrant-client behind a feature flag. The companion Python workspace under src/ provides audit helpers and reference fixtures but is not the primary runtime surface.

Code Quality The workspace enforces unsafe_code = "forbid" at the workspace level and enables Clippy all warnings, with selective allows for known-acceptable patterns. Tests are comprehensive: rusty-claude-cli has six integration test files covering compaction panic recovery, output format contracts, mock parity harness, resume slash commands, CLI flags, and compact output; runtime has a conformance test suite for the G004 events contract; api has four integration test files for OpenAI compat, client behavior, proxy, and provider client; tools tests path-scope enforcement; plugins has a test isolation module. Error handling uses typed RuntimeError and ApiError variants rather than stringly-typed errors. The codebase carries several workspace-level #[allow(dead_code, unused_imports)] suppressions in the main binary indicating active porting work from the Python reference implementation, which limits the current quality ceiling.

What Makes It Unique Claw Code’s defining technical contribution is its explicit design for machine operability over human convenience — the project calls this ‘clawability.’ Every diagnostic command emits structured JSON, session state transitions are encoded as typed events (not log lines), the permission system allows hook-level overrides that agent workflows can inject programmatically, and the MCP lifecycle hardening exposes startup, handshake, and degraded-mode failures as distinct classified states rather than opaque errors. The repository is itself developed by autonomous agents using the clawhip event router and Gajae-Code harness, making it a living demonstration of the agent coordination patterns it enables. The included claw-rag-service with optional Qdrant backend and the mock Anthropic service for offline parity testing are uncommon inclusions in CLI AI agent tooling.

Self-Hosting

Licensing Model MIT licensed — all features available in self-hosted deployments with no restrictions or license keys required.

Self-Hosting Restrictions None. The full workspace including RAG service, MCP integration, plugin hooks, and multi-provider support is available without any license gating.

License Key Required No. Claw Code requires an API key for the upstream AI provider (Anthropic, OpenAI, or compatible), but this is a provider credential — not a Claw Code license requirement.