# yad4o/local-code-agent architecture

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

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

## Overview

local-code-agent is a local coding-agent harness: a user supplies a strictly validated plan, and the harness coordinates model-generated tests and implementation, test execution, bounded retries, rollback, and per-step commits. The README documents CLI operations, Ollama and OpenAI backends, resource checks, loop protection, and run transcripts. All runtime components point to agent.py, the sole substantial source file in the tree; its implementation was not excerpted, so relationships below rely on README statements rather than source inspection.

Main entry points: [`agent.py`](https://github.com/yad4o/local-code-agent/blob/main/agent.py) (Step orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["CLI<br/>[agent.py]"]
end

subgraph group_workflow["Plan execution"]
  node_plan["Plan validation<br/>[agent.py]"]
  node_orchestrator["Step orchestrator<br/>[agent.py]"]
  node_testgen["Test generation<br/>[agent.py]"]
  node_implementation["Implementation generation<br/>[agent.py]"]
  node_test_runner["Test runner<br/>[agent.py]"]
  node_retry["Retry and repair<br/>[agent.py]"]
  node_rollback["Step rollback<br/>[agent.py]"]
  node_git["Step commits<br/>[agent.py]"]
  node_workspace["Workspace<br/>[agent.py]"]
end

subgraph group_model["Model interaction"]
  node_prompt["Prompt assembly<br/>[agent.py]"]
  node_backend["Model backend<br/>[agent.py]"]
  node_reply_parser["Reply parsing<br/>[agent.py]"]
end

subgraph group_safety["Safety and records"]
  node_loop_guard["Loop guard<br/>[agent.py]"]
  node_resource_check["Resource checks<br/>[agent.py]"]
  node_transcript["Run transcript<br/>[agent.py]"]
  node_run_log["Run log and replies<br/>[agent.py]"]
end

node_user(("Developer"))
node_ollama["Ollama"]
node_openai["OpenAI backend"]

node_user -->|"invokes"| node_cli
node_cli -->|"validates"| node_plan
node_cli -->|"checks resources"| node_resource_check
node_cli -->|"starts run"| node_orchestrator
node_orchestrator -->|"works in"| node_workspace
node_orchestrator -->|"requests tests"| node_testgen
node_orchestrator -->|"requests code"| node_implementation
node_testgen -->|"uses prompts"| node_prompt
node_implementation -->|"uses prompts"| node_prompt
node_prompt -->|"sends request"| node_backend
node_backend -->|"calls"| node_ollama
node_backend -.->|"supports"| node_openai
node_backend -->|"returns reply"| node_reply_parser
node_backend -->|"streams through"| node_loop_guard
node_orchestrator -->|"runs tests"| node_test_runner
node_test_runner -->|"reports failures"| node_retry
node_retry -->|"retries step"| node_orchestrator
node_orchestrator -->|"rolls back failure"| node_rollback
node_orchestrator -->|"commits green step"| node_git
node_orchestrator -->|"appends exchanges"| node_transcript
node_orchestrator -->|"records run"| node_run_log

click node_cli "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_plan "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_orchestrator "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_testgen "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_implementation "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_test_runner "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_retry "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_rollback "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_git "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_workspace "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_prompt "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_backend "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_reply_parser "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_loop_guard "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_resource_check "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_transcript "https://github.com/yad4o/local-code-agent/blob/main/agent.py"
click node_run_log "https://github.com/yad4o/local-code-agent/blob/main/agent.py"

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_cli toneBlue
class node_plan,node_orchestrator,node_testgen,node_implementation,node_test_runner,node_retry,node_rollback,node_git,node_workspace toneAmber
class node_prompt,node_backend,node_reply_parser toneMint
class node_loop_guard,node_resource_check,node_transcript,node_run_log toneRose
class node_user,node_ollama,node_openai toneIndigo
```

## Components

### User interface

- [CLI](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`

### Plan execution

- [Plan validation](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Step orchestrator](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Test generation](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Implementation generation](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Test runner](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Retry and repair](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Step rollback](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Step commits](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Workspace](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`

### Model interaction

- [Prompt assembly](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Model backend](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Reply parsing](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`

### Safety and records

- [Loop guard](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Resource checks](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Run transcript](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`
- [Run log and replies](https://github.com/yad4o/local-code-agent/blob/main/agent.py): `agent.py`

### Other components

- **Developer**
- **Ollama**
- **OpenAI backend**

## Connections

- Developer → CLI: invokes (evidence: `README.md`)
- CLI → Plan validation: validates (evidence: `README.md`)
- CLI → Resource checks: checks resources (evidence: `README.md`)
- CLI → Step orchestrator: starts run (evidence: `README.md`)
- Step orchestrator → Workspace: works in (evidence: `README.md`)
- Step orchestrator → Test generation: requests tests (evidence: `README.md`)
- Step orchestrator → Implementation generation: requests code (evidence: `README.md`)
- Test generation → Prompt assembly: uses prompts (evidence: `README.md`)
- Implementation generation → Prompt assembly: uses prompts (evidence: `README.md`)
- Prompt assembly → Model backend: sends request (evidence: `README.md`)
- Model backend → Ollama: calls (evidence: `README.md`)
- Model backend → OpenAI backend: supports (evidence: `README.md`)
- Model backend → Reply parsing: returns reply (evidence: `README.md`)
- Model backend → Loop guard: streams through (evidence: `README.md`)
- Step orchestrator → Test runner: runs tests (evidence: `README.md`)
- Test runner → Retry and repair: reports failures (evidence: `README.md`)
- Retry and repair → Step orchestrator: retries step (evidence: `README.md`)
- Step orchestrator → Step rollback: rolls back failure (evidence: `README.md`)
- Step orchestrator → Step commits: commits green step (evidence: `README.md`)
- Step orchestrator → Run transcript: appends exchanges (evidence: `README.md`)
- Step orchestrator → Run log and replies: records run (evidence: `README.md`)
