ashik-manjunath/claw-code

Purpose and Entry Points

This is a clean-room, dual-language rewrite workspace for an AI agent harness. The active Python surface primarily reports porting/parity metadata; the Rust workspace is the substantive CLI/runtime port. Python commands enter through src/main.py; the Rust interactive binary enters through rust/crates/claw-cli/src/main.rs and application wiring in rust/crates/claw-cli/src/app.rs.

Python Porting Workspace

Python models the intended system surface and renders inventories rather than providing full runtime equivalence. src/port_manifest.py assembles the workspace representation, src/models.py defines subsystem/module/backlog data, and src/query_engine.py produces summaries. CLI dispatch in src/main.py exposes manifest, subsystem, command/tool inventory, and parity-audit operations.

Rust CLI Interaction Layer

The Rust CLI owns interactive user control flow: argument parsing, initialization/bootstrap, input collection, and output rendering. Its boundary is a terminal REPL/application frontend over runtime and API crates. Key paths: rust/crates/claw-cli/src/main.rs, rust/crates/claw-cli/src/args.rs, rust/crates/claw-cli/src/render.rs.

Agent Runtime and Session Orchestration

The runtime crate is the central harness layer: it manages sessions and conversations, constructs prompts, compacts context, applies permissions/sandboxing, and coordinates tool-oriented execution. It is also the integration boundary for MCP, remote behavior, OAuth, SSE, filesystem operations, and usage tracking. Key paths: rust/crates/runtime/src/lib.rs, rust/crates/runtime/src/session.rs, rust/crates/runtime/src/mcp.rs.

Model Provider and Streaming Boundary

The API crate abstracts LLM providers behind shared client/types/error interfaces. It supports a native Claw provider and OpenAI-compatible endpoints, with streaming/SSE transport. Runtime/CLI should depend on this abstraction rather than provider-specific protocols. Key paths: rust/crates/api/src/client.rs, rust/crates/api/src/providers/openai_compat.rs, rust/crates/api/src/sse.rs.

Extensibility, Tools, and Commands

Tool definitions/execution, slash-command behavior, skills/config inspection, and plugins/hooks are separated into dedicated crates. Plugins can supply lifecycle hooks and bundled plugin packages; this is the primary extension boundary around the core runtime. Key paths: rust/crates/tools/src/lib.rs, rust/crates/commands/src/lib.rs, rust/crates/plugins/src/hooks.rs.

Editor and Server Integrations

The workspace includes an LSP client/manager for editor-facing integration, a compatibility harness for upstream-editor behavior, and a server crate described as HTTP/SSE-based. These are adapters around the core runtime rather than alternate runtimes. Key paths: rust/crates/lsp/src/manager.rs, rust/crates/compat-harness/src/lib.rs, rust/crates/server/src/lib.rs.

Build and External Dependencies

Rust is a Cargo workspace rooted at rust/Cargo.toml, with CI under rust/.github/workflows/ci.yml. Material external interfaces are LLM provider APIs (including OpenAI-compatible APIs), OAuth authentication, Server-Sent Events, MCP servers over stdio, shell/file operations, and LSP/editor clients. Python verification is limited to the porting workspace under tests/test_porting_workspace.py.