# satyamkumarcs/ai-banana-harness architecture

> Architecture diagram of the GitHub repository satyamkumarcs/ai-banana-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/satyamkumarcs/ai-banana-harness
- Repository: https://github.com/satyamkumarcs/ai-banana-harness

## Overview

Banana Harness is a local-first coding-agent application with both an interactive terminal UI and a headless runner. A user selects a provider and workspace, submits a GitHub issue or task, and the harness streams model output while routing tool requests through permission checks to workspace operations or MCP servers. Turns can involve approvals, subagents, checkpoints, and compaction; session and event state is persisted for later listing and resumption. The graph follows the documented capabilities and sampled entry points; unsampled subsystem wiring is omitted where it cannot be verified.

Main entry points: [`crates/harness-core/src/harness.rs`](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/harness.rs) (Turn Orchestrator), [`crates/harness-tui/src/lib.rs`](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-tui/src/lib.rs) (Terminal UI), [`crates/banana-harness/src/main.rs`](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/banana-harness/src/main.rs) (CLI Runner), [`crates/harness-core/src/tools.rs`](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/tools.rs) (Tool Routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI Runner<br/>[main.rs]"]
  node_tui["Terminal UI<br/>[lib.rs]"]
  node_appstate["UI State<br/>[app.rs]"]
end

subgraph group_engine["Agent Runtime"]
  node_harness["Turn Orchestrator<br/>[harness.rs]"]
  node_events["Event Types<br/>[event.rs]"]
  node_instructions["Instructions And Skills<br/>[instructions.rs]"]
  node_skills["Skill Loading<br/>[skills.rs]"]
  node_compaction["History Compaction<br/>[compaction.rs]"]
  node_checkpoint["Turn Checkpoints<br/>[checkpoint.rs]"]
  node_safety["Safety Limits<br/>[safety.rs]"]
  node_routing["Tool Routing<br/>[tools.rs]"]
end

subgraph group_workspace["Workspace Tools"]
  node_hosttools["Host Tools<br/>[lib.rs]"]
  node_guardrails["Permission Engine<br/>[guardrail.rs]"]
  node_workspacefiles["Local Workspace"]
end

subgraph group_integrations["Model And MCP"]
  node_llm["Streaming Provider Client<br/>[lib.rs]"]
  node_mcp["MCP Client<br/>[lib.rs]"]
  node_oauth["Remote MCP OAuth<br/>[oauth.rs]"]
end

subgraph group_state["Configuration And State"]
  node_config["Config Loader<br/>[config.rs]"]
  node_store[("Session Store<br/>[lib.rs]")]
end

node_user(("Operator"))
node_provider{{"DeepSeek Or Qwen"}}
node_mcpservers{{"MCP Servers"}}
node_terminal(("Terminal"))

node_user -->|"submits task"| node_tui
node_user -.->|"runs task"| node_cli
node_tui -->|"updates state"| node_appstate
node_tui -->|"starts turns"| node_harness
node_cli -->|"starts turns"| node_harness
node_tui -->|"loads settings"| node_config
node_cli -->|"loads settings"| node_config
node_harness -->|"uses settings"| node_config
node_harness -->|"persists sessions"| node_store
node_harness -->|"requests completions"| node_llm
node_llm -->|"streams API"| node_provider
node_provider -->|"returns stream"| node_llm
node_harness -->|"routes tool calls"| node_routing
node_routing -->|"dispatches host calls"| node_hosttools
node_hosttools -->|"checks permissions"| node_guardrails
node_hosttools -->|"reads and modifies"| node_workspacefiles
node_routing -->|"dispatches MCP calls"| node_mcp
node_mcp -->|"lists and calls tools"| node_mcpservers
node_mcp -.->|"connects with OAuth"| node_oauth
node_oauth -.->|"authorizes requests"| node_mcpservers
node_harness -->|"assembles guidance"| node_instructions
node_instructions -->|"loads skills"| node_skills
node_harness -->|"compacts history"| node_compaction
node_harness -->|"manages checkpoints"| node_checkpoint
node_harness -->|"enforces limits"| node_safety
node_harness -->|"emits events"| node_events
node_events -->|"updates transcript"| node_appstate
node_appstate -->|"renders UI"| node_terminal
node_harness -->|"stores turn events"| node_store
node_store -->|"loads session history"| node_harness

click node_cli "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/banana-harness/src/main.rs"
click node_tui "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-tui/src/lib.rs"
click node_appstate "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-tui/src/app.rs"
click node_harness "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/harness.rs"
click node_events "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/event.rs"
click node_instructions "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/instructions.rs"
click node_skills "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/skills.rs"
click node_compaction "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/compaction.rs"
click node_checkpoint "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/checkpoint.rs"
click node_safety "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/safety.rs"
click node_routing "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/tools.rs"
click node_hosttools "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-tools/src/lib.rs"
click node_guardrails "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-tools/src/guardrail.rs"
click node_llm "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-llm/src/lib.rs"
click node_mcp "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-mcp/src/lib.rs"
click node_oauth "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-mcp/src/oauth.rs"
click node_config "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/config.rs"
click node_store "https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-store/src/lib.rs"

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_tui,node_appstate toneBlue
class node_harness,node_events,node_instructions,node_skills,node_compaction,node_checkpoint,node_safety,node_routing toneAmber
class node_hosttools,node_guardrails,node_workspacefiles,node_mcpservers toneMint
class node_llm,node_mcp,node_oauth toneRose
class node_config,node_store,node_user,node_provider,node_terminal toneIndigo
```

## Components

### User Interfaces

- [CLI Runner](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/banana-harness/src/main.rs): `crates/banana-harness/src/main.rs`
- [Terminal UI](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-tui/src/lib.rs): `crates/harness-tui/src/lib.rs`
- [UI State](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-tui/src/app.rs): `crates/harness-tui/src/app.rs`

### Agent Runtime

- [Turn Orchestrator](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/harness.rs): `crates/harness-core/src/harness.rs`
- [Event Types](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/event.rs): `crates/harness-core/src/event.rs`
- [Instructions And Skills](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/instructions.rs): `crates/harness-core/src/instructions.rs`
- [Skill Loading](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/skills.rs): `crates/harness-core/src/skills.rs`
- [History Compaction](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/compaction.rs): `crates/harness-core/src/compaction.rs`
- [Turn Checkpoints](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/checkpoint.rs): `crates/harness-core/src/checkpoint.rs`
- [Safety Limits](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/safety.rs): `crates/harness-core/src/safety.rs`
- [Tool Routing](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/tools.rs): `crates/harness-core/src/tools.rs`

### Workspace Tools

- [Host Tools](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-tools/src/lib.rs): `crates/harness-tools/src/lib.rs`
- [Permission Engine](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-tools/src/guardrail.rs): `crates/harness-tools/src/guardrail.rs`
- **Local Workspace**

### Model And MCP

- [Streaming Provider Client](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-llm/src/lib.rs): `crates/harness-llm/src/lib.rs`
- [MCP Client](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-mcp/src/lib.rs): `crates/harness-mcp/src/lib.rs`
- [Remote MCP OAuth](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-mcp/src/oauth.rs): `crates/harness-mcp/src/oauth.rs`

### Configuration And State

- [Config Loader](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-core/src/config.rs): `crates/harness-core/src/config.rs`
- [Session Store](https://github.com/satyamkumarcs/ai-banana-harness/blob/main/crates/harness-store/src/lib.rs): `crates/harness-store/src/lib.rs`

### Other components

- **Operator**
- **DeepSeek Or Qwen**
- **MCP Servers**
- **Terminal**

## Connections

- Operator → Terminal UI: submits task
- Operator → CLI Runner: runs task
- Terminal UI → UI State: updates state
- Terminal UI → Turn Orchestrator: starts turns
- CLI Runner → Turn Orchestrator: starts turns
- Terminal UI → Config Loader: loads settings
- CLI Runner → Config Loader: loads settings
- Turn Orchestrator → Config Loader: uses settings
- Turn Orchestrator → Session Store: persists sessions
- Turn Orchestrator → Streaming Provider Client: requests completions
- Streaming Provider Client → DeepSeek Or Qwen: streams API
- DeepSeek Or Qwen → Streaming Provider Client: returns stream
- Turn Orchestrator → Tool Routing: routes tool calls
- Tool Routing → Host Tools: dispatches host calls
- Host Tools → Permission Engine: checks permissions
- Host Tools → Local Workspace: reads and modifies
- Tool Routing → MCP Client: dispatches MCP calls
- MCP Client → MCP Servers: lists and calls tools
- MCP Client → Remote MCP OAuth: connects with OAuth
- Remote MCP OAuth → MCP Servers: authorizes requests
- Turn Orchestrator → Instructions And Skills: assembles guidance
- Instructions And Skills → Skill Loading: loads skills
- Turn Orchestrator → History Compaction: compacts history
- Turn Orchestrator → Turn Checkpoints: manages checkpoints
- Turn Orchestrator → Safety Limits: enforces limits
- Turn Orchestrator → Event Types: emits events
- Event Types → UI State: updates transcript
- UI State → Terminal: renders UI
- Turn Orchestrator → Session Store: stores turn events
- Session Store → Turn Orchestrator: loads session history