# dflippojr/agent-harness architecture

> Architecture diagram of the GitHub repository dflippojr/agent-harness, 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/dflippojr/agent-harness
- Repository: https://github.com/dflippojr/agent-harness

## Overview

Agent Harness is a self-hosted platform for running coding agents through a daemon, with browser, CLI, SDK, and app-API clients. The main workflow is: a client submits a task; the session manager coordinates the agent loop; policy gates tool calls; tools execute in a sandbox or remote runner; model and tool results return to the session, whose work is persisted for review. The graph also includes documented GPU/image scheduling, configuration, search, skills, and benchmarking capabilities. Several implementation links rely on README architecture statements because the corresponding source was not sampled.

Main entry points: [`harness/runner.py`](https://github.com/dflippojr/agent-harness/blob/main/harness/runner.py) (Agent Loop), [`harness/manager.py`](https://github.com/dflippojr/agent-harness/blob/main/harness/manager.py) (Session Manager), [`harness/api.py`](https://github.com/dflippojr/agent-harness/blob/main/harness/api.py) (REST APIs), [`harness/policy.py`](https://github.com/dflippojr/agent-harness/blob/main/harness/policy.py) (Approval Policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client Interfaces"]
  node_web["PWA<br/>[app.js]"]
  node_cli["CLI<br/>[cli.py]"]
  node_sdk["Python SDK<br/>[harness_client.py]"]
end

subgraph group_runtime["Agent Runtime"]
  node_rest["REST APIs<br/>[api.py]"]
  node_app_api["App API<br/>[apps.py]"]
  node_manager["Session Manager<br/>[manager.py]"]
  node_agent_loop["Agent Loop<br/>[runner.py]"]
  node_policy["Approval Policy<br/>[policy.py]"]
end

subgraph group_execution["Execution and Models"]
  node_fileops["Workspace File Tools<br/>[fileops.py]"]
  node_sandbox["Docker Sandbox<br/>[sandbox.py]"]
  node_remote_runner["Remote Runner<br/>[remote.py]"]
  node_mac_runner["Mac Runner<br/>[harness_runner.py]"]
  node_hosted_backends["Hosted CLI Backends<br/>[cli_backends.py]"]
  node_gpu["GPU Scheduler<br/>[scheduler.py]"]
  node_llm["Local Model Interface<br/>[llm.py]"]
  node_images["Image Generation<br/>[images.py]"]
end

subgraph group_platform["Platform Services"]
  node_database[("SQLite State<br/>[db.py]")]
  node_search["Session Search<br/>[search.py]"]
  node_projects["Projects and Branches<br/>[projects.py]"]
  node_settings["Settings Service"]
  node_config["Configuration<br/>[config.py]"]
  node_skills["Agent Skills<br/>[skills.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_bakeoff["Agent Benchmarks<br/>[tasks.py]"]
end

node_owner(("Owner / User"))

node_owner -->|"uses"| node_web
node_owner -->|"uses"| node_cli
node_owner -->|"uses"| node_sdk
node_web -->|"requests"| node_rest
node_cli -->|"requests"| node_rest
node_sdk -->|"requests"| node_rest
node_rest -->|"dispatches"| node_manager
node_app_api -->|"drives sessions"| node_manager
node_manager -->|"coordinates"| node_agent_loop
node_agent_loop -->|"classifies calls"| node_policy
node_policy -->|"requests approval"| node_owner
node_agent_loop -->|"persists events"| node_database
node_agent_loop -->|"requests inference"| node_gpu
node_gpu -->|"schedules model"| node_llm
node_gpu -->|"schedules images"| node_images
node_agent_loop -->|"executes tools"| node_sandbox
node_agent_loop -->|"dispatches backend"| node_hosted_backends
node_policy -->|"authorizes execution"| node_sandbox
node_agent_loop -->|"dispatches remotely"| node_remote_runner
node_remote_runner -->|"runs worker"| node_mac_runner
node_sandbox -.->|"uses workspace tools"| node_fileops
node_manager -->|"prepares project"| node_projects
node_database -->|"indexes sessions"| node_search
node_settings -->|"applies configuration"| node_config
node_agent_loop -.->|"uses skills"| node_skills
node_owner -->|"evaluates agents"| node_bakeoff

click node_web "https://github.com/dflippojr/agent-harness/blob/main/harness/web/app.js"
click node_cli "https://github.com/dflippojr/agent-harness/blob/main/harness/cli.py"
click node_sdk "https://github.com/dflippojr/agent-harness/blob/main/sdk/harness_client.py"
click node_rest "https://github.com/dflippojr/agent-harness/blob/main/harness/api.py"
click node_app_api "https://github.com/dflippojr/agent-harness/blob/main/harness/apps.py"
click node_manager "https://github.com/dflippojr/agent-harness/blob/main/harness/manager.py"
click node_agent_loop "https://github.com/dflippojr/agent-harness/blob/main/harness/runner.py"
click node_policy "https://github.com/dflippojr/agent-harness/blob/main/harness/policy.py"
click node_database "https://github.com/dflippojr/agent-harness/blob/main/harness/db.py"
click node_search "https://github.com/dflippojr/agent-harness/blob/main/harness/search.py"
click node_projects "https://github.com/dflippojr/agent-harness/blob/main/harness/projects.py"
click node_fileops "https://github.com/dflippojr/agent-harness/blob/main/harness/fileops.py"
click node_sandbox "https://github.com/dflippojr/agent-harness/blob/main/harness/sandbox.py"
click node_remote_runner "https://github.com/dflippojr/agent-harness/blob/main/harness/remote.py"
click node_mac_runner "https://github.com/dflippojr/agent-harness/blob/main/macrunner/harness_runner.py"
click node_hosted_backends "https://github.com/dflippojr/agent-harness/blob/main/harness/cli_backends.py"
click node_gpu "https://github.com/dflippojr/agent-harness/blob/main/harness/scheduler.py"
click node_llm "https://github.com/dflippojr/agent-harness/blob/main/harness/llm.py"
click node_images "https://github.com/dflippojr/agent-harness/blob/main/harness/images.py"
click node_settings "https://github.com/dflippojr/agent-harness/blob/main/harness/settings_service.py"
click node_config "https://github.com/dflippojr/agent-harness/blob/main/harness/config.py"
click node_skills "https://github.com/dflippojr/agent-harness/blob/main/harness/skills.py"
click node_bakeoff "https://github.com/dflippojr/agent-harness/blob/main/bakeoff/tasks.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_web,node_cli,node_sdk,node_owner toneBlue
class node_rest,node_app_api,node_manager,node_agent_loop,node_policy toneAmber
class node_fileops,node_sandbox,node_remote_runner,node_mac_runner,node_hosted_backends,node_gpu,node_llm,node_images toneMint
class node_database,node_search,node_projects,node_settings,node_config,node_skills toneRose
class node_bakeoff toneIndigo
```

## Components

### Client Interfaces

- [PWA](https://github.com/dflippojr/agent-harness/blob/main/harness/web/app.js): `harness/web/app.js`
- [CLI](https://github.com/dflippojr/agent-harness/blob/main/harness/cli.py): `harness/cli.py`
- [Python SDK](https://github.com/dflippojr/agent-harness/blob/main/sdk/harness_client.py): `sdk/harness_client.py`

### Agent Runtime

- [REST APIs](https://github.com/dflippojr/agent-harness/blob/main/harness/api.py): `harness/api.py`
- [App API](https://github.com/dflippojr/agent-harness/blob/main/harness/apps.py): `harness/apps.py`
- [Session Manager](https://github.com/dflippojr/agent-harness/blob/main/harness/manager.py): `harness/manager.py`
- [Agent Loop](https://github.com/dflippojr/agent-harness/blob/main/harness/runner.py): `harness/runner.py`
- [Approval Policy](https://github.com/dflippojr/agent-harness/blob/main/harness/policy.py): `harness/policy.py`

### Execution and Models

- [Workspace File Tools](https://github.com/dflippojr/agent-harness/blob/main/harness/fileops.py): `harness/fileops.py`
- [Docker Sandbox](https://github.com/dflippojr/agent-harness/blob/main/harness/sandbox.py): `harness/sandbox.py`
- [Remote Runner](https://github.com/dflippojr/agent-harness/blob/main/harness/remote.py): `harness/remote.py`
- [Mac Runner](https://github.com/dflippojr/agent-harness/blob/main/macrunner/harness_runner.py): `macrunner/harness_runner.py`
- [Hosted CLI Backends](https://github.com/dflippojr/agent-harness/blob/main/harness/cli_backends.py): `harness/cli_backends.py`
- [GPU Scheduler](https://github.com/dflippojr/agent-harness/blob/main/harness/scheduler.py): `harness/scheduler.py`
- [Local Model Interface](https://github.com/dflippojr/agent-harness/blob/main/harness/llm.py): `harness/llm.py`
- [Image Generation](https://github.com/dflippojr/agent-harness/blob/main/harness/images.py): `harness/images.py`

### Platform Services

- [SQLite State](https://github.com/dflippojr/agent-harness/blob/main/harness/db.py): `harness/db.py`
- [Session Search](https://github.com/dflippojr/agent-harness/blob/main/harness/search.py): `harness/search.py`
- [Projects and Branches](https://github.com/dflippojr/agent-harness/blob/main/harness/projects.py): `harness/projects.py`
- [Settings Service](https://github.com/dflippojr/agent-harness/blob/main/harness/settings_service.py): `harness/settings_service.py`
- [Configuration](https://github.com/dflippojr/agent-harness/blob/main/harness/config.py): `harness/config.py`
- [Agent Skills](https://github.com/dflippojr/agent-harness/blob/main/harness/skills.py): `harness/skills.py`

### Evaluation

- [Agent Benchmarks](https://github.com/dflippojr/agent-harness/blob/main/bakeoff/tasks.py): `bakeoff/tasks.py`

### Other components

- **Owner / User**

## Connections

- Owner / User → PWA: uses (evidence: `README.md`)
- Owner / User → CLI: uses (evidence: `README.md`)
- Owner / User → Python SDK: uses (evidence: `README.md`)
- PWA → REST APIs: requests (evidence: `README.md`)
- CLI → REST APIs: requests (evidence: `README.md`)
- Python SDK → REST APIs: requests (evidence: `README.md`)
- REST APIs → Session Manager: dispatches (evidence: `harness/apps.py`)
- App API → Session Manager: drives sessions (evidence: `harness/apps.py`)
- Session Manager → Agent Loop: coordinates (evidence: `harness/manager.py`)
- Agent Loop → Approval Policy: classifies calls (evidence: `README.md`)
- Approval Policy → Owner / User: requests approval (evidence: `README.md`)
- Agent Loop → SQLite State: persists events (evidence: `README.md`)
- Agent Loop → GPU Scheduler: requests inference (evidence: `README.md`)
- GPU Scheduler → Local Model Interface: schedules model (evidence: `README.md`)
- GPU Scheduler → Image Generation: schedules images (evidence: `README.md`)
- Agent Loop → Docker Sandbox: executes tools (evidence: `README.md`)
- Agent Loop → Hosted CLI Backends: dispatches backend (evidence: `README.md`)
- Approval Policy → Docker Sandbox: authorizes execution (evidence: `README.md`)
- Agent Loop → Remote Runner: dispatches remotely (evidence: `README.md`)
- Remote Runner → Mac Runner: runs worker (evidence: `README.md`)
- Docker Sandbox → Workspace File Tools: uses workspace tools
- Session Manager → Projects and Branches: prepares project (evidence: `harness/manager.py`)
- SQLite State → Session Search: indexes sessions (evidence: `README.md`)
- Settings Service → Configuration: applies configuration (evidence: `harness/settings_service.py`)
- Agent Loop → Agent Skills: uses skills
- Owner / User → Agent Benchmarks: evaluates agents (evidence: `README.md`)
