# havish-coder/agent-harness architecture

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

- Interactive diagram: https://gitdiagram.com/havish-coder/agent-harness
- Repository: https://github.com/havish-coder/agent-harness

## Overview

Agent Harness is a terminal coding agent: a user submits a task, the session assembles workspace context and a provider-backed agent, the agent requests tools to inspect or change files and run commands, and the terminal streams results while requesting approval for changes. The map also includes provider selection/retries, settings and cost tracking, and the principal tool and UI layers. Relationships come from the excerpts, SOURCE INDEX references, or README; unsampled internals are not assumed to call one another.

Main entry points: [`harness/session.py`](https://github.com/havish-coder/agent-harness/blob/main/harness/session.py) (Session), [`harness/cli.py`](https://github.com/havish-coder/agent-harness/blob/main/harness/cli.py) (CLI Entry), [`harness/workspace.py`](https://github.com/havish-coder/agent-harness/blob/main/harness/workspace.py) (Workspace State), [`harness/providers/base.py`](https://github.com/havish-coder/agent-harness/blob/main/harness/providers/base.py) (Provider Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_cli["CLI Entry<br/>[cli.py]"]
  node_settings["Settings<br/>[config.py]"]
  node_commands["Slash Commands<br/>[commands.py]"]
  node_mentions["File Mentions<br/>[mentions.py]"]
  node_session["Session<br/>[session.py]"]
end

subgraph group_agent["Agent Runtime"]
  node_agent["Agent Loop<br/>[agent.py]"]
  node_messages["Message Model<br/>[messages.py]"]
  node_usage["Usage Tracking<br/>[usage.py]"]
end

subgraph group_providers["Model Providers"]
  node_provider_factory["Provider Factory<br/>[factory.py]"]
  node_retry["Retry and Fallback<br/>[retry.py]"]
  node_provider_base["Provider Interface<br/>[base.py]"]
  node_ollama["Ollama Adapter<br/>[ollama.py]"]
  node_anthropic["Anthropic Adapter<br/>[anthropic.py]"]
  node_openai["OpenAI-Compatible Adapter<br/>[openai_compat.py]"]
end

subgraph group_tools["Workspace Tools"]
  node_workspace["Workspace State<br/>[workspace.py]"]
  node_tool_base["Tool Schema and Safety<br/>[base.py]"]
  node_registry["Tool Registry<br/>[registry.py]"]
  node_fs_tools["File Listing and Reading<br/>[fs.py]"]
  node_search_tools["Glob and Grep<br/>[search.py]"]
  node_edit_tools["File Editing<br/>[edit.py]"]
  node_shell_tools["Shell Commands<br/>[shell.py]"]
end

subgraph group_terminal["Terminal Interface"]
  node_terminal_ui["Terminal UI<br/>[plain.py]"]
  node_rich_ui["Rich Terminal UI<br/>[rich_ui.py]"]
  node_prompt_input["Prompt Input<br/>[prompt.py]"]
end

node_user(("User"))
node_model_services{{"Model Services"}}

node_user -->|"submits task"| node_cli
node_cli -->|"loads settings"| node_settings
node_cli -->|"opens workspace"| node_workspace
node_cli -->|"creates session"| node_session
node_cli -->|"dispatches commands"| node_commands
node_cli -->|"selects interface"| node_terminal_ui
node_cli -->|"reads prompts"| node_prompt_input
node_commands -->|"updates settings"| node_settings
node_mentions -->|"resolves paths"| node_workspace
node_mentions -->|"uses file tools"| node_fs_tools
node_session -->|"creates provider"| node_provider_factory
node_session -->|"wraps provider"| node_retry
node_session -->|"configures agent"| node_agent
node_session -->|"builds workspace snapshot"| node_fs_tools
node_session -->|"tracks workspace"| node_workspace
node_session -->|"tracks costs"| node_usage
node_session -->|"forwards events"| node_terminal_ui
node_agent -->|"requests replies"| node_provider_base
node_agent -->|"dispatches tool calls"| node_registry
node_agent -->|"maintains conversation"| node_messages
node_agent -->|"emits events"| node_terminal_ui
node_provider_factory -->|"selects adapter"| node_ollama
node_provider_factory -->|"selects adapter"| node_anthropic
node_provider_factory -->|"selects adapter"| node_openai
node_ollama -->|"implements interface"| node_provider_base
node_anthropic -->|"implements interface"| node_provider_base
node_openai -->|"implements interface"| node_provider_base
node_provider_base -->|"uses message types"| node_messages
node_ollama -->|"calls model API"| node_model_services
node_anthropic -->|"calls model API"| node_model_services
node_openai -->|"calls model API"| node_model_services
node_retry -->|"wraps provider"| node_provider_base
node_registry -->|"registers tools"| node_tool_base
node_fs_tools -->|"defines tools"| node_tool_base
node_fs_tools -->|"reads and tracks files"| node_workspace
node_search_tools -->|"defines tools"| node_tool_base
node_search_tools -->|"searches workspace"| node_workspace
node_edit_tools -->|"defines tools"| node_tool_base
node_edit_tools -->|"checks read state"| node_workspace
node_shell_tools -->|"defines tools"| node_tool_base
node_shell_tools -->|"uses workspace"| node_workspace
node_rich_ui -->|"extends rendering"| node_terminal_ui
node_terminal_ui -.->|"shows responses"| node_user

click node_cli "https://github.com/havish-coder/agent-harness/blob/main/harness/cli.py"
click node_settings "https://github.com/havish-coder/agent-harness/blob/main/harness/config.py"
click node_commands "https://github.com/havish-coder/agent-harness/blob/main/harness/commands.py"
click node_mentions "https://github.com/havish-coder/agent-harness/blob/main/harness/mentions.py"
click node_session "https://github.com/havish-coder/agent-harness/blob/main/harness/session.py"
click node_workspace "https://github.com/havish-coder/agent-harness/blob/main/harness/workspace.py"
click node_agent "https://github.com/havish-coder/agent-harness/blob/main/harness/agent.py"
click node_messages "https://github.com/havish-coder/agent-harness/blob/main/harness/messages.py"
click node_usage "https://github.com/havish-coder/agent-harness/blob/main/harness/usage.py"
click node_provider_factory "https://github.com/havish-coder/agent-harness/blob/main/harness/providers/factory.py"
click node_retry "https://github.com/havish-coder/agent-harness/blob/main/harness/providers/retry.py"
click node_provider_base "https://github.com/havish-coder/agent-harness/blob/main/harness/providers/base.py"
click node_ollama "https://github.com/havish-coder/agent-harness/blob/main/harness/providers/ollama.py"
click node_anthropic "https://github.com/havish-coder/agent-harness/blob/main/harness/providers/anthropic.py"
click node_openai "https://github.com/havish-coder/agent-harness/blob/main/harness/providers/openai_compat.py"
click node_tool_base "https://github.com/havish-coder/agent-harness/blob/main/harness/tools/base.py"
click node_registry "https://github.com/havish-coder/agent-harness/blob/main/harness/tools/registry.py"
click node_fs_tools "https://github.com/havish-coder/agent-harness/blob/main/harness/tools/fs.py"
click node_search_tools "https://github.com/havish-coder/agent-harness/blob/main/harness/tools/search.py"
click node_edit_tools "https://github.com/havish-coder/agent-harness/blob/main/harness/tools/edit.py"
click node_shell_tools "https://github.com/havish-coder/agent-harness/blob/main/harness/tools/shell.py"
click node_terminal_ui "https://github.com/havish-coder/agent-harness/blob/main/harness/tui/plain.py"
click node_rich_ui "https://github.com/havish-coder/agent-harness/blob/main/harness/tui/rich_ui.py"
click node_prompt_input "https://github.com/havish-coder/agent-harness/blob/main/harness/tui/prompt.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,node_settings,node_commands,node_mentions,node_session,node_user toneBlue
class node_agent,node_messages,node_usage toneAmber
class node_provider_factory,node_retry,node_provider_base,node_ollama,node_anthropic,node_openai toneMint
class node_workspace,node_tool_base,node_registry,node_fs_tools,node_search_tools,node_edit_tools,node_shell_tools toneRose
class node_terminal_ui,node_rich_ui,node_prompt_input,node_model_services toneIndigo
```

## Components

### Application

- [CLI Entry](https://github.com/havish-coder/agent-harness/blob/main/harness/cli.py): `harness/cli.py`
- [Settings](https://github.com/havish-coder/agent-harness/blob/main/harness/config.py): `harness/config.py`
- [Slash Commands](https://github.com/havish-coder/agent-harness/blob/main/harness/commands.py): `harness/commands.py`
- [File Mentions](https://github.com/havish-coder/agent-harness/blob/main/harness/mentions.py): `harness/mentions.py`
- [Session](https://github.com/havish-coder/agent-harness/blob/main/harness/session.py): `harness/session.py`

### Agent Runtime

- [Agent Loop](https://github.com/havish-coder/agent-harness/blob/main/harness/agent.py): `harness/agent.py`
- [Message Model](https://github.com/havish-coder/agent-harness/blob/main/harness/messages.py): `harness/messages.py`
- [Usage Tracking](https://github.com/havish-coder/agent-harness/blob/main/harness/usage.py): `harness/usage.py`

### Model Providers

- [Provider Factory](https://github.com/havish-coder/agent-harness/blob/main/harness/providers/factory.py): `harness/providers/factory.py`
- [Retry and Fallback](https://github.com/havish-coder/agent-harness/blob/main/harness/providers/retry.py): `harness/providers/retry.py`
- [Provider Interface](https://github.com/havish-coder/agent-harness/blob/main/harness/providers/base.py): `harness/providers/base.py`
- [Ollama Adapter](https://github.com/havish-coder/agent-harness/blob/main/harness/providers/ollama.py): `harness/providers/ollama.py`
- [Anthropic Adapter](https://github.com/havish-coder/agent-harness/blob/main/harness/providers/anthropic.py): `harness/providers/anthropic.py`
- [OpenAI-Compatible Adapter](https://github.com/havish-coder/agent-harness/blob/main/harness/providers/openai_compat.py): `harness/providers/openai_compat.py`

### Workspace Tools

- [Workspace State](https://github.com/havish-coder/agent-harness/blob/main/harness/workspace.py): `harness/workspace.py`
- [Tool Schema and Safety](https://github.com/havish-coder/agent-harness/blob/main/harness/tools/base.py): `harness/tools/base.py`
- [Tool Registry](https://github.com/havish-coder/agent-harness/blob/main/harness/tools/registry.py): `harness/tools/registry.py`
- [File Listing and Reading](https://github.com/havish-coder/agent-harness/blob/main/harness/tools/fs.py): `harness/tools/fs.py`
- [Glob and Grep](https://github.com/havish-coder/agent-harness/blob/main/harness/tools/search.py): `harness/tools/search.py`
- [File Editing](https://github.com/havish-coder/agent-harness/blob/main/harness/tools/edit.py): `harness/tools/edit.py`
- [Shell Commands](https://github.com/havish-coder/agent-harness/blob/main/harness/tools/shell.py): `harness/tools/shell.py`

### Terminal Interface

- [Terminal UI](https://github.com/havish-coder/agent-harness/blob/main/harness/tui/plain.py): `harness/tui/plain.py`
- [Rich Terminal UI](https://github.com/havish-coder/agent-harness/blob/main/harness/tui/rich_ui.py): `harness/tui/rich_ui.py`
- [Prompt Input](https://github.com/havish-coder/agent-harness/blob/main/harness/tui/prompt.py): `harness/tui/prompt.py`

### Other components

- **User**
- **Model Services**

## Connections

- User → CLI Entry: submits task
- CLI Entry → Settings: loads settings (evidence: `harness/cli.py`)
- CLI Entry → Workspace State: opens workspace (evidence: `harness/cli.py`)
- CLI Entry → Session: creates session (evidence: `harness/cli.py`)
- CLI Entry → Slash Commands: dispatches commands (evidence: `harness/cli.py`)
- CLI Entry → Terminal UI: selects interface (evidence: `harness/cli.py`)
- CLI Entry → Prompt Input: reads prompts (evidence: `harness/cli.py`)
- Slash Commands → Settings: updates settings (evidence: `harness/commands.py`)
- File Mentions → Workspace State: resolves paths (evidence: `harness/mentions.py`)
- File Mentions → File Listing and Reading: uses file tools (evidence: `harness/mentions.py`)
- Session → Provider Factory: creates provider (evidence: `harness/session.py`)
- Session → Retry and Fallback: wraps provider (evidence: `harness/session.py`)
- Session → Agent Loop: configures agent (evidence: `harness/session.py`)
- Session → File Listing and Reading: builds workspace snapshot (evidence: `harness/session.py`)
- Session → Workspace State: tracks workspace (evidence: `harness/session.py`)
- Session → Usage Tracking: tracks costs (evidence: `harness/session.py`)
- Session → Terminal UI: forwards events (evidence: `harness/session.py`)
- Agent Loop → Provider Interface: requests replies (evidence: `harness/agent.py`)
- Agent Loop → Tool Registry: dispatches tool calls (evidence: `harness/agent.py`)
- Agent Loop → Message Model: maintains conversation (evidence: `harness/agent.py`)
- Agent Loop → Terminal UI: emits events
- Provider Factory → Ollama Adapter: selects adapter (evidence: `harness/providers/factory.py`)
- Provider Factory → Anthropic Adapter: selects adapter (evidence: `harness/providers/factory.py`)
- Provider Factory → OpenAI-Compatible Adapter: selects adapter (evidence: `harness/providers/factory.py`)
- Ollama Adapter → Provider Interface: implements interface (evidence: `harness/providers/ollama.py`)
- Anthropic Adapter → Provider Interface: implements interface (evidence: `harness/providers/anthropic.py`)
- OpenAI-Compatible Adapter → Provider Interface: implements interface (evidence: `harness/providers/openai_compat.py`)
- Provider Interface → Message Model: uses message types (evidence: `harness/providers/base.py`)
- Ollama Adapter → Model Services: calls model API (evidence: `harness/providers/ollama.py`)
- Anthropic Adapter → Model Services: calls model API (evidence: `harness/providers/anthropic.py`)
- OpenAI-Compatible Adapter → Model Services: calls model API (evidence: `harness/providers/openai_compat.py`)
- Retry and Fallback → Provider Interface: wraps provider (evidence: `harness/providers/retry.py`)
- Tool Registry → Tool Schema and Safety: registers tools (evidence: `harness/tools/registry.py`)
- File Listing and Reading → Tool Schema and Safety: defines tools (evidence: `harness/tools/fs.py`)
- File Listing and Reading → Workspace State: reads and tracks files (evidence: `harness/tools/fs.py`)
- Glob and Grep → Tool Schema and Safety: defines tools (evidence: `harness/tools/search.py`)
- Glob and Grep → Workspace State: searches workspace (evidence: `harness/tools/search.py`)
- File Editing → Tool Schema and Safety: defines tools (evidence: `harness/tools/edit.py`)
- File Editing → Workspace State: checks read state (evidence: `harness/tools/edit.py`)
- Shell Commands → Tool Schema and Safety: defines tools (evidence: `harness/tools/shell.py`)
- Shell Commands → Workspace State: uses workspace (evidence: `harness/tools/shell.py`)
- Rich Terminal UI → Terminal UI: extends rendering (evidence: `harness/tui/rich_ui.py`)
- Terminal UI → User: shows responses
