# waylliam1988/codey architecture

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

- Interactive diagram: https://gitdiagram.com/waylliam1988/codey
- Repository: https://github.com/waylliam1988/codey
- Video tour (about a minute): https://gitdiagram.com/waylliam1988/codey/video

## Overview

Codey is a local-first AI coding and research workspace. A user submits work through the local UI or CLI; the application coordinates a task run, connects a browser-based or local model, and mediates project actions through tools and policies. Coding runs can verify changes and provide completion evidence; research runs plan searches, inspect sources, and assess evidence; review and local memory are additional capabilities. The graph reflects README-described flows and relationships visible in the supplied excerpts or SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`codey/operations/task_run.py`](https://github.com/waylliam1988/codey/blob/master/codey/operations/task_run.py) (Task run loop), [`codey/app/server.py`](https://github.com/waylliam1988/codey/blob/master/codey/app/server.py) (Local UI server), [`codey/providers/catalog.py`](https://github.com/waylliam1988/codey/blob/master/codey/providers/catalog.py) (Provider catalog), [`codey/research/pipeline.py`](https://github.com/waylliam1988/codey/blob/master/codey/research/pipeline.py) (Research pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_ui["Local UI server<br/>[server.py]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_task["Task orchestration"]
  node_submit["Task submission<br/>[task_submit.py]"]
  node_taskflow["Task run loop<br/>[task_run.py]"]
  node_taskstate["Task state contract<br/>[task_state.py]"]
end

subgraph group_execution["Model and workspace execution"]
  node_providers["Provider catalog<br/>[catalog.py]"]
  node_browserworker["Browser provider worker<br/>[worker.py]"]
  node_browser["Browser automation<br/>[browser.py]"]
  node_localmodel["Local model adapter<br/>[local_openai.py]"]
  node_toolruntime["Tool runtime<br/>[runtime.py]"]
  node_workspace["Project workspace context<br/>[setup_context.py]"]
end

subgraph group_assurance["Verification and review"]
  node_completion["Completion proof<br/>[engine.py]"]
  node_verification["Verification policy"]
  node_review["Review service<br/>[review_service.py]"]
end

subgraph group_research["Research"]
  node_researchflow["Research pipeline<br/>[pipeline.py]"]
  node_queryplanner["Query planner<br/>[query_planner.py]"]
  node_evidence["Evidence runtime"]
  node_researchtrust["Source trust<br/>[source_trust.py]"]
end

subgraph group_state["Local state and memory"]
  node_ghost[("Ghost memory and work queue<br/>[work_queue.py]")]
  node_knowledge[("Knowledge index<br/>[index.py]")]
  node_store[("Local store<br/>[local_store.py]")]
  node_sessionlog[("Session log<br/>[session_log.py]")]
end

node_user(("User"))

node_user -->|"uses"| node_ui
node_user -->|"uses"| node_cli
node_ui -->|"submits runs"| node_submit
node_cli -.->|"submits tasks"| node_submit
node_submit -.->|"starts run"| node_taskflow
node_taskflow -->|"coordinates through"| node_taskstate
node_taskflow -.->|"selects provider"| node_providers
node_providers -->|"connects browser provider"| node_browserworker
node_browserworker -->|"runs automation"| node_browser
node_providers -.->|"supports local model"| node_localmodel
node_taskflow -.->|"executes tools"| node_toolruntime
node_toolruntime -.->|"accesses project"| node_workspace
node_workspace -->|"informs checks"| node_verification
node_verification -->|"supplies checks"| node_completion
node_taskflow -.->|"can request review"| node_review
node_taskflow -->|"runs research tasks"| node_researchflow
node_researchflow -->|"plans follow-up"| node_queryplanner
node_researchflow -->|"checks evidence"| node_evidence
node_evidence -->|"uses source trust"| node_researchtrust
node_taskflow -.->|"supports local memory"| node_ghost
node_taskstate -->|"coordinates knowledge store"| node_knowledge
node_ui -->|"uses local state"| node_store
node_sessionlog -->|"persists locally"| node_store

click node_ui "https://github.com/waylliam1988/codey/blob/master/codey/app/server.py"
click node_cli "https://github.com/waylliam1988/codey/blob/master/codey/app/cli.py"
click node_submit "https://github.com/waylliam1988/codey/blob/master/codey/app/task_submit.py"
click node_taskflow "https://github.com/waylliam1988/codey/blob/master/codey/operations/task_run.py"
click node_taskstate "https://github.com/waylliam1988/codey/blob/master/codey/operations/task_state.py"
click node_providers "https://github.com/waylliam1988/codey/blob/master/codey/providers/catalog.py"
click node_browserworker "https://github.com/waylliam1988/codey/blob/master/codey/providers/worker.py"
click node_browser "https://github.com/waylliam1988/codey/blob/master/codey/automation/browser.py"
click node_localmodel "https://github.com/waylliam1988/codey/blob/master/codey/providers/local_openai.py"
click node_toolruntime "https://github.com/waylliam1988/codey/blob/master/codey/toolchain/runtime.py"
click node_workspace "https://github.com/waylliam1988/codey/blob/master/codey/workspace/setup_context.py"
click node_completion "https://github.com/waylliam1988/codey/blob/master/codey/completion/engine.py"
click node_verification "https://github.com/waylliam1988/codey/blob/master/codey/completion/verification_policy.py"
click node_review "https://github.com/waylliam1988/codey/blob/master/codey/app/review_service.py"
click node_researchflow "https://github.com/waylliam1988/codey/blob/master/codey/research/pipeline.py"
click node_queryplanner "https://github.com/waylliam1988/codey/blob/master/codey/research/query_planner.py"
click node_evidence "https://github.com/waylliam1988/codey/blob/master/codey/research/evidence_runtime.py"
click node_researchtrust "https://github.com/waylliam1988/codey/blob/master/codey/research/source_trust.py"
click node_ghost "https://github.com/waylliam1988/codey/blob/master/codey/ghost/work_queue.py"
click node_knowledge "https://github.com/waylliam1988/codey/blob/master/codey/knowledge/index.py"
click node_store "https://github.com/waylliam1988/codey/blob/master/codey/storage/local_store.py"
click node_sessionlog "https://github.com/waylliam1988/codey/blob/master/codey/runtime/log/session_log.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_ui,node_cli,node_user toneBlue
class node_submit,node_taskflow,node_taskstate toneAmber
class node_providers,node_browserworker,node_browser,node_localmodel,node_toolruntime,node_workspace toneMint
class node_completion,node_verification,node_review toneRose
class node_researchflow,node_queryplanner,node_evidence,node_researchtrust toneIndigo
class node_ghost,node_knowledge,node_store,node_sessionlog toneTeal
```

## Components

### User entry

- [Local UI server](https://github.com/waylliam1988/codey/blob/master/codey/app/server.py): `codey/app/server.py`
- [CLI](https://github.com/waylliam1988/codey/blob/master/codey/app/cli.py): `codey/app/cli.py`

### Task orchestration

- [Task submission](https://github.com/waylliam1988/codey/blob/master/codey/app/task_submit.py): `codey/app/task_submit.py`
- [Task run loop](https://github.com/waylliam1988/codey/blob/master/codey/operations/task_run.py): `codey/operations/task_run.py`
- [Task state contract](https://github.com/waylliam1988/codey/blob/master/codey/operations/task_state.py): `codey/operations/task_state.py`

### Model and workspace execution

- [Provider catalog](https://github.com/waylliam1988/codey/blob/master/codey/providers/catalog.py): `codey/providers/catalog.py`
- [Browser provider worker](https://github.com/waylliam1988/codey/blob/master/codey/providers/worker.py): `codey/providers/worker.py`
- [Browser automation](https://github.com/waylliam1988/codey/blob/master/codey/automation/browser.py): `codey/automation/browser.py`
- [Local model adapter](https://github.com/waylliam1988/codey/blob/master/codey/providers/local_openai.py): `codey/providers/local_openai.py`
- [Tool runtime](https://github.com/waylliam1988/codey/blob/master/codey/toolchain/runtime.py): `codey/toolchain/runtime.py`
- [Project workspace context](https://github.com/waylliam1988/codey/blob/master/codey/workspace/setup_context.py): `codey/workspace/setup_context.py`

### Verification and review

- [Completion proof](https://github.com/waylliam1988/codey/blob/master/codey/completion/engine.py): `codey/completion/engine.py`
- [Verification policy](https://github.com/waylliam1988/codey/blob/master/codey/completion/verification_policy.py): `codey/completion/verification_policy.py`
- [Review service](https://github.com/waylliam1988/codey/blob/master/codey/app/review_service.py): `codey/app/review_service.py`

### Research

- [Research pipeline](https://github.com/waylliam1988/codey/blob/master/codey/research/pipeline.py): `codey/research/pipeline.py`
- [Query planner](https://github.com/waylliam1988/codey/blob/master/codey/research/query_planner.py): `codey/research/query_planner.py`
- [Evidence runtime](https://github.com/waylliam1988/codey/blob/master/codey/research/evidence_runtime.py): `codey/research/evidence_runtime.py`
- [Source trust](https://github.com/waylliam1988/codey/blob/master/codey/research/source_trust.py): `codey/research/source_trust.py`

### Local state and memory

- [Ghost memory and work queue](https://github.com/waylliam1988/codey/blob/master/codey/ghost/work_queue.py): `codey/ghost/work_queue.py`
- [Knowledge index](https://github.com/waylliam1988/codey/blob/master/codey/knowledge/index.py): `codey/knowledge/index.py`
- [Local store](https://github.com/waylliam1988/codey/blob/master/codey/storage/local_store.py): `codey/storage/local_store.py`
- [Session log](https://github.com/waylliam1988/codey/blob/master/codey/runtime/log/session_log.py): `codey/runtime/log/session_log.py`

### Other components

- **User**

## Connections

- User → Local UI server: uses (evidence: `README.md`)
- User → CLI: uses (evidence: `README.md`)
- Local UI server → Task submission: submits runs (evidence: `codey/app/server.py`)
- CLI → Task submission: submits tasks
- Task submission → Task run loop: starts run
- Task run loop → Task state contract: coordinates through (evidence: `codey/operations/task_state.py`)
- Task run loop → Provider catalog: selects provider
- Provider catalog → Browser provider worker: connects browser provider (evidence: `codey/providers/worker.py`)
- Browser provider worker → Browser automation: runs automation (evidence: `codey/providers/worker.py`)
- Provider catalog → Local model adapter: supports local model
- Task run loop → Tool runtime: executes tools
- Tool runtime → Project workspace context: accesses project
- Project workspace context → Verification policy: informs checks (evidence: `codey/workspace/setup_context.py`)
- Verification policy → Completion proof: supplies checks (evidence: `codey/completion/engine.py`)
- Task run loop → Review service: can request review
- Task run loop → Research pipeline: runs research tasks (evidence: `README.md`)
- Research pipeline → Query planner: plans follow-up (evidence: `codey/research/pipeline.py`)
- Research pipeline → Evidence runtime: checks evidence (evidence: `codey/research/pipeline.py`)
- Evidence runtime → Source trust: uses source trust (evidence: `codey/research/pipeline.py`)
- Task run loop → Ghost memory and work queue: supports local memory
- Task state contract → Knowledge index: coordinates knowledge store (evidence: `codey/operations/task_state.py`)
- Local UI server → Local store: uses local state (evidence: `codey/app/server.py`)
- Session log → Local store: persists locally (evidence: `codey/runtime/log/session_log.py`)
