# afloresc/opencode-lite architecture

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

- Interactive diagram: https://gitdiagram.com/afloresc/opencode-lite
- Repository: https://github.com/afloresc/opencode-lite

## Overview

#### Purpose and Entry Point

This is a Go CLI implementing an autonomous, project-scoped cognitive agent runtime. It accepts a goal, plans and grounds work into filesystem/code operations within `workspace/`, monitors execution, and adapts future behavior through persistent memory. Process startup is `cmd/cli/main.go`; configuration is centralized in `internal/config/config.go`.

#### Runtime Orchestration

`AgentRuntime` is the core control loop: it executes goals, invokes planning and tools, captures results, and feeds observations into monitoring and adaptive subsystems. Agent context and shared contracts define the boundaries among stages.

Paths: `internal/agent/runtime.go`, `internal/agent/context.go`, `internal/agent/interfaces.go`.

#### Goal Routing and Specialized Agents

A supervisor/classifier selects or biases execution toward specialized analysis, refactoring, or documentation agents. These agents expose a common interface and delegate actual execution back to the shared runtime, preserving one execution path while allowing goal-specific policy.

Paths: `internal/agent/supervisor.go`, `internal/agent/goal_classifier.go`, `internal/agent/analysis_agent.go`, `internal/agent/refactor_agent.go`, `internal/agent/docs_agent.go`.

#### Hybrid Planning and Step Expansion

The planner combines deterministic rules, LLM-derived reasoning, and planner memory to produce executable steps. Step expansion/mapping transforms broad plans into operations, filters historically failing work, and supports planner modes such as coarse, fine, aggressive, and conservative.

Paths: `internal/agent/planner.go`, `internal/agent/master_planner.go`, `internal/agent/planner_rules.go`, `internal/agent/step_expander.go`, `internal/agent/step_mapper.go`.

#### Tool Grounding and Execution Boundary

The contextual grounder maps abstract plan steps to registered concrete tools, using strict or flexible selection modes and project context. Tools are the safety boundary for workspace interaction: filesystem changes, search, patches/refactors, formatting, analysis, and sandbox command dispatch all reside behind the tool package.

Paths: `internal/agent/tool_grounder.go`, `internal/agent/tool_grounder_contextual.go`, `internal/tools/registry.go`, `internal/tools/filesystem.go`, `internal/tools/patches.go`, `internal/tools/run_command_dispatch.go`.

#### Feedback, Memory, and Self-Optimization

Execution monitoring detects repeats, consecutive failures, and stalled output. Metacognition evaluates those signals and provides confidence/advice; the strategy engine adjusts planner/grounder modes and tool or agent bias. Cognitive and planner memory persist project-specific outcomes, while AOC records longer-term optimization preferences.

Paths: `internal/agent/execution_monitor.go`, `internal/agent/metacognition.go`, `internal/agent/strategy_engine.go`, `internal/agent/cognitive_memory.go`, `internal/agent/planner_memory.go`, `internal/agent/aoc.go`.

#### LLM and Infrastructure Integration

The runtime has an LLM client/prompt boundary with an Ollama provider implementation, making local Ollama the identified model-service integration. Persistent cognitive state is stored under `.opencode/<projectID>/`; mutable target content is constrained to `workspace/`. The system runs as a Go binary and uses local command/file operations rather than a web service.

Paths: `internal/agent/llm_client.go`, `internal/agent/llm_prompt.go`, `internal/providers/ollama.go`, `internal/runtime/runtime.go`, `internal/runtime/system_prompt.go`.

Main entry points: [`internal/agent/runtime.go`](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/runtime.go) (Agent runtime), [`internal/agent/planner.go`](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/planner.go) (Hybrid planner), [`internal/agent/strategy_engine.go`](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/strategy_engine.go) (Strategy engine), [`internal/runtime/runtime.go`](https://github.com/afloresc/opencode-lite/blob/main/internal/runtime/runtime.go) (Runtime host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI &amp; Runtime"]
  node_cli["Go CLI entrypoint<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_runtime_host["Runtime host<br/>[runtime.go]"]
end

subgraph group_agent["Agent Control Loop"]
  node_agent_runtime{{"Agent runtime<br/>control loop<br/>[runtime.go]"}}
  node_agent_contracts["Agent context &amp; contracts<br/>shared contracts<br/>[interfaces.go]"]
  node_supervisor["Supervisor &amp; classifier<br/>goal routing<br/>[supervisor.go]"]
  node_specialists["Specialized agents<br/>agent policies<br/>[analysis_agent.go]"]
end

subgraph group_planning["Planning &amp; Grounding"]
  node_planner{{"Hybrid planner<br/>planning<br/>[planner.go]"}}
  node_step_expansion["Step expansion &amp; mapping<br/>plan transformation<br/>[step_expander.go]"]
  node_grounder{{"Contextual tool grounder<br/>tool selection"}}
end

subgraph group_adaptation["Feedback &amp; Adaptation"]
  node_monitor["Execution monitor<br/>feedback"]
  node_metacognition["Metacognition<br/>evaluation<br/>[metacognition.go]"]
  node_strategy{{"Strategy engine<br/>adaptation<br/>[strategy_engine.go]"}}
  node_memory[("Cognitive &amp; planner memory<br/>persistent memory")]
  node_aoc[("AOC preferences<br/>optimization memory<br/>[aoc.go]")]
end

subgraph group_integration["Execution &amp; Model"]
  node_tool_registry{{"Tool registry<br/>execution boundary<br/>[registry.go]"}}
  node_workspace_tools["Workspace &amp; command tools<br/>local operations<br/>[filesystem.go]"]
  node_llm_client["LLM client &amp; prompts<br/>model boundary<br/>[llm_client.go]"]
  node_ollama["Ollama provider<br/>local model provider<br/>[ollama.go]"]
end

node_cli -->|"starts"| node_runtime_host
node_config -->|"configures"| node_runtime_host
node_runtime_host -->|"hosts"| node_agent_runtime
node_agent_contracts -->|"defines context"| node_agent_runtime
node_agent_runtime -->|"routes goal"| node_supervisor
node_supervisor -->|"selects policy"| node_specialists
node_specialists -->|"delegates execution"| node_agent_runtime
node_agent_runtime -->|"requests plan"| node_planner
node_planner -->|"produces steps"| node_step_expansion
node_step_expansion -->|"maps operations"| node_grounder
node_grounder -->|"selects tools"| node_tool_registry
node_tool_registry -->|"dispatches"| node_workspace_tools
node_workspace_tools -->|"returns results"| node_agent_runtime
node_agent_runtime -->|"emits execution signals"| node_monitor
node_monitor -->|"reports signals"| node_metacognition
node_metacognition -->|"advice &amp; confidence"| node_strategy
node_strategy -.->|"adjusts modes"| node_planner
node_strategy -.->|"adjusts selection"| node_grounder
node_agent_runtime -->|"records outcomes"| node_memory
node_memory -.->|"supplies history"| node_planner
node_aoc -.->|"optimization preferences"| node_strategy
node_planner -->|"requests reasoning"| node_llm_client
node_llm_client -->|"uses"| node_ollama

click node_cli "https://github.com/afloresc/opencode-lite/blob/main/cmd/cli/main.go"
click node_config "https://github.com/afloresc/opencode-lite/blob/main/internal/config/config.go"
click node_runtime_host "https://github.com/afloresc/opencode-lite/blob/main/internal/runtime/runtime.go"
click node_agent_runtime "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/runtime.go"
click node_agent_contracts "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/interfaces.go"
click node_supervisor "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/supervisor.go"
click node_specialists "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/analysis_agent.go"
click node_planner "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/planner.go"
click node_step_expansion "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/step_expander.go"
click node_grounder "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/tool_grounder_contextual.go"
click node_monitor "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/execution_monitor.go"
click node_metacognition "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/metacognition.go"
click node_strategy "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/strategy_engine.go"
click node_memory "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/cognitive_memory.go"
click node_aoc "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/aoc.go"
click node_tool_registry "https://github.com/afloresc/opencode-lite/blob/main/internal/tools/registry.go"
click node_workspace_tools "https://github.com/afloresc/opencode-lite/blob/main/internal/tools/filesystem.go"
click node_llm_client "https://github.com/afloresc/opencode-lite/blob/main/internal/agent/llm_client.go"
click node_ollama "https://github.com/afloresc/opencode-lite/blob/main/internal/providers/ollama.go"

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,node_config,node_runtime_host toneBlue
class node_agent_runtime,node_agent_contracts,node_supervisor,node_specialists toneAmber
class node_planner,node_step_expansion,node_grounder toneMint
class node_monitor,node_metacognition,node_strategy,node_memory,node_aoc toneRose
class node_tool_registry,node_workspace_tools,node_llm_client,node_ollama toneIndigo
```

## Components

### CLI & Runtime

- [Go CLI entrypoint](https://github.com/afloresc/opencode-lite/blob/main/cmd/cli/main.go): CLI · `cmd/cli/main.go`
- [Configuration](https://github.com/afloresc/opencode-lite/blob/main/internal/config/config.go): config · `internal/config/config.go`
- [Runtime host](https://github.com/afloresc/opencode-lite/blob/main/internal/runtime/runtime.go): runtime · `internal/runtime/runtime.go`

### Agent Control Loop

- [Agent runtime](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/runtime.go): control loop · Executes goals and coordinates planning, tools, and feedback. · `internal/agent/runtime.go`
- [Agent context & contracts](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/interfaces.go): shared contracts · `internal/agent/interfaces.go`
- [Supervisor & classifier](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/supervisor.go): goal routing · `internal/agent/supervisor.go`
- [Specialized agents](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/analysis_agent.go): agent policies · Analysis, refactor, and documentation policies share the execution path. · `internal/agent/analysis_agent.go`

### Planning & Grounding

- [Hybrid planner](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/planner.go): planning · Combines rules, LLM reasoning, and planner memory. · `internal/agent/planner.go`
- [Step expansion & mapping](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/step_expander.go): plan transformation · Converts broad plans to operations and filters failing work. · `internal/agent/step_expander.go`
- [Contextual tool grounder](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/tool_grounder_contextual.go): tool selection · Maps plan operations to concrete tools under selection modes. · `internal/agent/tool_grounder_contextual.go`

### Feedback & Adaptation

- [Execution monitor](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/execution_monitor.go): feedback · Detects repeats, failures, and stalled output. · `internal/agent/execution_monitor.go`
- [Metacognition](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/metacognition.go): evaluation · `internal/agent/metacognition.go`
- [Strategy engine](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/strategy_engine.go): adaptation · Adjusts planner, grounder, tool, and agent bias. · `internal/agent/strategy_engine.go`
- [Cognitive & planner memory](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/cognitive_memory.go): persistent memory · Stores project outcomes and planning history. · `internal/agent/cognitive_memory.go`
- [AOC preferences](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/aoc.go): optimization memory · Records longer-term optimization preferences. · `internal/agent/aoc.go`

### Execution & Model

- [Tool registry](https://github.com/afloresc/opencode-lite/blob/main/internal/tools/registry.go): execution boundary · Registered tools constrain workspace interaction. · `internal/tools/registry.go`
- [Workspace & command tools](https://github.com/afloresc/opencode-lite/blob/main/internal/tools/filesystem.go): local operations · Filesystem, patching, and sandbox command dispatch. · `internal/tools/filesystem.go`
- [LLM client & prompts](https://github.com/afloresc/opencode-lite/blob/main/internal/agent/llm_client.go): model boundary · `internal/agent/llm_client.go`
- [Ollama provider](https://github.com/afloresc/opencode-lite/blob/main/internal/providers/ollama.go): local model provider · `internal/providers/ollama.go`

## Connections

- Go CLI entrypoint → Runtime host: starts
- Configuration → Runtime host: configures
- Runtime host → Agent runtime: hosts
- Agent context & contracts → Agent runtime: defines context
- Agent runtime → Supervisor & classifier: routes goal
- Supervisor & classifier → Specialized agents: selects policy
- Specialized agents → Agent runtime: delegates execution
- Agent runtime → Hybrid planner: requests plan
- Hybrid planner → Step expansion & mapping: produces steps
- Step expansion & mapping → Contextual tool grounder: maps operations
- Contextual tool grounder → Tool registry: selects tools
- Tool registry → Workspace & command tools: dispatches
- Workspace & command tools → Agent runtime: returns results
- Agent runtime → Execution monitor: emits execution signals
- Execution monitor → Metacognition: reports signals
- Metacognition → Strategy engine: advice & confidence
- Strategy engine → Hybrid planner: adjusts modes
- Strategy engine → Contextual tool grounder: adjusts selection
- Agent runtime → Cognitive & planner memory: records outcomes
- Cognitive & planner memory → Hybrid planner: supplies history
- AOC preferences → Strategy engine: optimization preferences
- Hybrid planner → LLM client & prompts: requests reasoning
- LLM client & prompts → Ollama provider: uses