youngyangyang04/kamaclaude

Purpose and deployment shape

KamaClaude is a local, daemon-backed coding-agent runtime: clients submit goals, while the Core executes multi-step LLM/tool workflows and exposes execution as durable and live event streams. Python entry points separate the daemon, CLI, and TUI:

• src/kama_claude/core/__main__.py

• src/kama_claude/cli/__main__.py

• src/kama_claude/tui/__main__.py

Client–daemon protocol boundary

CLI commands and the TUI are IPC clients rather than agent hosts. The daemon exposes typed commands/events over socket transport; the wire contract is JSON-RPC 2.0 over NDJSON. This permits multiple clients, ongoing task execution after a client exits, and future alternate front ends.

• src/kama_claude/cli/main.py

• src/kama_claude/core/transport/socket_server.py

• src/kama_claude/core/bus/envelope.py

• WIRE_PROTOCOL.md

Core application and run orchestration

The Core application assembles runtime services and dispatches incoming commands. A runner creates/continues runs, coordinates session state, and invokes the agent loop. The loop implements the ReAct-like cycle: construct context, call an LLM, execute requested tools, feed results back, and stop on a final response or failure.

• src/kama_claude/core/app.py

• src/kama_claude/core/runner.py

• src/kama_claude/core/loop.py

• src/kama_claude/core/runs.py

LLM, tools, and safety gate

The LLM provider layer isolates model integrations behind common request/response types. Tool calls are resolved through a registry and invocation boundary; local filesystem/shell and task-management tools are built in. Permission management is a hard control boundary before sensitive execution, supporting policy, storage, approval, error classification, and retry-oriented handling.

• src/kama_claude/core/llm/provider.py

• src/kama_claude/core/tools/registry.py

• src/kama_claude/core/tools/invocation.py

• src/kama_claude/core/permissions/manager.py

Events, persistence, and observability

Execution is externalized through an event bus. Events serve both real-time subscribers—via IPC broadcasting—and persistent run records; trace providers/writers capture cross-layer timelines for IPC, event, and LLM diagnosis/replay. The TUI consumes this observable execution state rather than directly driving internals.

• src/kama_claude/core/events/bus.py

• src/kama_claude/core/events/writer.py

• src/kama_claude/core/transport/ipc_broadcaster.py

• src/kama_claude/core/trace/writer.py

Stateful context lifecycle

Sessions preserve multi-turn interaction using models, management, and storage. Context construction combines thread/history and notes/memory; budget and compactor stages govern long-running conversations by detecting pressure, trimming tool results, and compacting context rather than blindly growing prompts.

• src/kama_claude/core/session/manager.py

• src/kama_claude/core/context.py

• src/kama_claude/core/compact/compactor.py

• src/kama_claude/core/memory/loader.py

Extensibility and agent composition

Built-in agent profiles and Markdown skills provide role/workflow instructions. Subagents expose delegated work through the tool system, while MCP client/server/tool modules integrate externally supplied tools into the same invocation, permission, event, and context pipeline.

• src/kama_claude/core/agents/loader.py

• src/kama_claude/core/skills/loader.py

• src/kama_claude/core/subagent/tool.py

• src/kama_claude/core/mcp/client.py