# aidenbarrett/local-code-agent architecture

> Architecture diagram of the GitHub repository aidenbarrett/local-code-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aidenbarrett/local-code-agent
- Repository: https://github.com/aidenbarrett/local-code-agent

## Overview

Local Code Agent is a local-first coding worker: the model proposes work, while deterministic controllers own admission, permissions, execution, verification, durable state, and verdicts. The principal flow starts in the Session Hub, passes through durable task admission and the task controller/orchestrator, uses bounded repository tools, then independently verifies and records the result. Separate branches provide model/runtime serving and durable watch jobs. The README documents product-level links; sampled excerpts and the source index support only some internal calls, so unsampled relationships are omitted or shown as documented.

Main entry points: [`internal/local_agent/agent/orchestrator.py`](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/orchestrator.py) (Agent orchestrator), [`internal/local_agent/session/task_controller.py`](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/task_controller.py) (Task controller), [`internal/local_agent/llm/client.py`](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/llm/client.py) (LLM client), [`internal/local_agent/session/durable_task_controller.py`](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/durable_task_controller.py) (Durable task executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Session interface"]
  node_hub["Session Hub"]
  node_conversation["Conversation gateway"]
end

subgraph group_control["Deterministic control"]
  node_admission["Task admission<br/>[task_admission.py]"]
  node_durable_executor["Durable task executor"]
  node_task_controller["Task controller<br/>[task_controller.py]"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_agent_context["Agent context<br/>[context.py]"]
  node_agent_policy["Agent policy<br/>[policy.py]"]
  node_agent_skills["Agent skills<br/>[skills.py]"]
  node_agent_state["Agent state<br/>[state.py]"]
  node_configuration["Configuration<br/>[config.py]"]
  node_outcomes["Task outcomes<br/>[contracts.py]"]
end

subgraph group_execution["Tools and verification"]
  node_tool_registry["Tool registry<br/>[__init__.py]"]
  node_tool_primitives["Tool primitives<br/>[tool_primitives.py]"]
  node_process_runner["Process runner<br/>[process_runner.py]"]
  node_verification["Independent verification<br/>[verification.py]"]
  node_proof_binding["Proof binding<br/>[proof_binding.py]"]
end

subgraph group_state["Durable state"]
  node_session_service["Durable session service"]
  node_session_store[("Session store<br/>[session_store.py]")]
  node_provenance["Run provenance<br/>[provenance.py]"]
  node_watch_service["Watch lifecycle<br/>[service.py]"]
  node_watch_runner["Fixed watch runner"]
  node_watch_store[("Watch stores<br/>[job_store.py]")]
end

subgraph group_models["Model and runtime"]
  node_llm_client["LLM client<br/>[client.py]"]
  node_model_tiers["Model tiers<br/>[model_tiers.py]"]
  node_model_protocol["Model protocol<br/>[protocol.py]"]
  node_endpoint["Inference endpoint<br/>[main.cpp]"]
end

node_engineer(("Engineer"))
node_external_model(("OpenAI-compatible model endpoint"))

node_engineer -->|"submits request"| node_hub
node_hub -.->|"handles conversation"| node_conversation
node_conversation -.->|"admits task"| node_admission
node_admission -.->|"authorizes execution"| node_durable_executor
node_durable_executor -->|"invokes controller"| node_task_controller
node_task_controller -->|"runs worker"| node_orchestrator
node_orchestrator -->|"gathers context"| node_agent_context
node_orchestrator -->|"applies policy"| node_agent_policy
node_orchestrator -->|"activates skill"| node_agent_skills
node_orchestrator -->|"updates state"| node_agent_state
node_orchestrator -->|"dispatches tools"| node_tool_registry
node_tool_registry -->|"builds registry"| node_tool_primitives
node_task_controller -->|"verifies run"| node_verification
node_task_controller -->|"binds proof"| node_proof_binding
node_task_controller -->|"projects outcome"| node_outcomes
node_durable_executor -->|"captures identity"| node_provenance
node_session_service -->|"commits events"| node_session_store
node_watch_service -->|"reads and writes"| node_watch_store
node_watch_service -->|"creates runner"| node_watch_runner
node_orchestrator -->|"requests inference"| node_llm_client
node_llm_client -->|"uses protocol"| node_model_protocol
node_model_tiers -->|"selects client"| node_llm_client
node_llm_client -->|"sends chat request"| node_external_model
node_external_model -.->|"may be served by"| node_endpoint
node_tool_registry -.->|"exposes execution tools"| node_process_runner

click node_hub "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/textual_live_app.py"
click node_conversation "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/conversation_gateway.py"
click node_admission "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/task_admission.py"
click node_durable_executor "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/durable_task_controller.py"
click node_task_controller "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/task_controller.py"
click node_orchestrator "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/orchestrator.py"
click node_agent_context "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/context.py"
click node_agent_policy "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/policy.py"
click node_agent_skills "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/skills.py"
click node_agent_state "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/state.py"
click node_configuration "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/config.py"
click node_tool_registry "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/tools/__init__.py"
click node_tool_primitives "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/tools/tool_primitives.py"
click node_process_runner "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/tools/process_runner.py"
click node_verification "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/verification.py"
click node_proof_binding "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/proof_binding.py"
click node_outcomes "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/contracts.py"
click node_session_service "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/session_event_service.py"
click node_session_store "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/session_store.py"
click node_provenance "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/provenance.py"
click node_watch_service "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/watch/service.py"
click node_watch_runner "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/watch/fixed_watch_runner.py"
click node_watch_store "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/watch/job_store.py"
click node_llm_client "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/llm/client.py"
click node_model_tiers "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/llm/model_tiers.py"
click node_model_protocol "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/llm/protocol.py"
click node_endpoint "https://github.com/aidenbarrett/local-code-agent/blob/main/internal/native_endpoint/src/main.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hub,node_conversation toneBlue
class node_admission,node_durable_executor,node_task_controller,node_orchestrator,node_agent_context,node_agent_policy,node_agent_skills,node_agent_state,node_configuration,node_outcomes toneAmber
class node_tool_registry,node_tool_primitives,node_process_runner,node_verification,node_proof_binding toneMint
class node_session_service,node_session_store,node_provenance,node_watch_service,node_watch_runner,node_watch_store toneRose
class node_llm_client,node_model_tiers,node_model_protocol,node_endpoint,node_engineer,node_external_model toneIndigo
```

## Components

### Session interface

- [Session Hub](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/textual_live_app.py): `internal/local_agent/session/textual_live_app.py`
- [Conversation gateway](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/conversation_gateway.py): `internal/local_agent/session/conversation_gateway.py`

### Deterministic control

- [Task admission](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/task_admission.py): `internal/local_agent/session/task_admission.py`
- [Durable task executor](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/durable_task_controller.py): `internal/local_agent/session/durable_task_controller.py`
- [Task controller](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/task_controller.py): `internal/local_agent/session/task_controller.py`
- [Agent orchestrator](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/orchestrator.py): `internal/local_agent/agent/orchestrator.py`
- [Agent context](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/context.py): `internal/local_agent/agent/context.py`
- [Agent policy](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/policy.py): `internal/local_agent/agent/policy.py`
- [Agent skills](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/skills.py): `internal/local_agent/agent/skills.py`
- [Agent state](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/agent/state.py): `internal/local_agent/agent/state.py`
- [Configuration](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/config.py): `internal/local_agent/config.py`
- [Task outcomes](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/contracts.py): `internal/local_agent/session/contracts.py`

### Tools and verification

- [Tool registry](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/tools/__init__.py): `internal/local_agent/tools/__init__.py`
- [Tool primitives](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/tools/tool_primitives.py): `internal/local_agent/tools/tool_primitives.py`
- [Process runner](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/tools/process_runner.py): `internal/local_agent/tools/process_runner.py`
- [Independent verification](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/verification.py): `internal/local_agent/verification.py`
- [Proof binding](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/proof_binding.py): `internal/local_agent/session/proof_binding.py`

### Durable state

- [Durable session service](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/session_event_service.py): `internal/local_agent/session/session_event_service.py`
- [Session store](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/session/session_store.py): `internal/local_agent/session/session_store.py`
- [Run provenance](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/provenance.py): `internal/local_agent/provenance.py`
- [Watch lifecycle](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/watch/service.py): `internal/local_agent/watch/service.py`
- [Fixed watch runner](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/watch/fixed_watch_runner.py): `internal/local_agent/watch/fixed_watch_runner.py`
- [Watch stores](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/watch/job_store.py): `internal/local_agent/watch/job_store.py`

### Model and runtime

- [LLM client](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/llm/client.py): `internal/local_agent/llm/client.py`
- [Model tiers](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/llm/model_tiers.py): `internal/local_agent/llm/model_tiers.py`
- [Model protocol](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/local_agent/llm/protocol.py): `internal/local_agent/llm/protocol.py`
- [Inference endpoint](https://github.com/aidenbarrett/local-code-agent/blob/main/internal/native_endpoint/src/main.cpp): `internal/native_endpoint/src/main.cpp`

### Other components

- **Engineer**
- **OpenAI-compatible model endpoint**

## Connections

- Engineer → Session Hub: submits request (evidence: `README.md`)
- Session Hub → Conversation gateway: handles conversation
- Conversation gateway → Task admission: admits task
- Task admission → Durable task executor: authorizes execution
- Durable task executor → Task controller: invokes controller (evidence: `internal/local_agent/session/durable_task_controller.py`)
- Task controller → Agent orchestrator: runs worker (evidence: `internal/local_agent/session/task_controller.py`)
- Agent orchestrator → Agent context: gathers context (evidence: `internal/local_agent/agent/orchestrator.py`)
- Agent orchestrator → Agent policy: applies policy (evidence: `internal/local_agent/agent/orchestrator.py`)
- Agent orchestrator → Agent skills: activates skill (evidence: `internal/local_agent/agent/orchestrator.py`)
- Agent orchestrator → Agent state: updates state (evidence: `internal/local_agent/agent/orchestrator.py`)
- Agent orchestrator → Tool registry: dispatches tools (evidence: `internal/local_agent/agent/orchestrator.py`)
- Tool registry → Tool primitives: builds registry (evidence: `internal/local_agent/tools/__init__.py`)
- Task controller → Independent verification: verifies run (evidence: `internal/local_agent/session/task_controller.py`)
- Task controller → Proof binding: binds proof (evidence: `internal/local_agent/session/task_controller.py`)
- Task controller → Task outcomes: projects outcome (evidence: `internal/local_agent/session/task_controller.py`)
- Durable task executor → Run provenance: captures identity (evidence: `internal/local_agent/session/durable_task_controller.py`)
- Durable session service → Session store: commits events (evidence: `internal/local_agent/session/session_event_service.py`)
- Watch lifecycle → Watch stores: reads and writes (evidence: `internal/local_agent/watch/service.py`)
- Watch lifecycle → Fixed watch runner: creates runner (evidence: `internal/local_agent/watch/service.py`)
- Agent orchestrator → LLM client: requests inference (evidence: `internal/local_agent/agent/orchestrator.py`)
- LLM client → Model protocol: uses protocol (evidence: `internal/local_agent/llm/client.py`)
- Model tiers → LLM client: selects client (evidence: `internal/local_agent/llm/model_tiers.py`)
- LLM client → OpenAI-compatible model endpoint: sends chat request (evidence: `README.md`)
- OpenAI-compatible model endpoint → Inference endpoint: may be served by
- Tool registry → Process runner: exposes execution tools