# helplessness/benchthread architecture

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

- Interactive diagram: https://gitdiagram.com/helplessness/benchthread
- Repository: https://github.com/helplessness/benchthread

## Overview

BenchThread is a self-hosted AI research workbench: a user starts a session, converses with an agent, and can extend that work with tools, remote jobs, verification, and saved research artifacts. The graph preserves the documented workflow and major capabilities, plus core runtime layers for sessions, agent execution, configuration, and plugins. Several feature modules were not sampled; their README-described roles are shown, but unverified implementation links are omitted or dashed.

Main entry points: [`tcode_agent/harness/engine.py`](https://github.com/helplessness/benchthread/blob/main/tcode_agent/harness/engine.py) (Turn Harness), [`tcode_agent/mcp/manager_auto.py`](https://github.com/helplessness/benchthread/blob/main/tcode_agent/mcp/manager_auto.py) (MCP Tools), [`tcode_agent/server/app.py`](https://github.com/helplessness/benchthread/blob/main/tcode_agent/server/app.py) (Server API), [`tcode_agent/agent/agents.py`](https://github.com/helplessness/benchthread/blob/main/tcode_agent/agent/agents.py) (Agent Setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interaction"]
  node_webui["Web Workbench<br/>[App.tsx]"]
  node_server["Server API<br/>[app.py]"]
end

subgraph group_runtime["Agent Runtime"]
  node_sessions[("Sessions<br/>[manager.py]")]
  node_agent["Agent Setup<br/>[agents.py]"]
  node_harness["Turn Harness<br/>[engine.py]"]
  node_config["Configuration<br/>[manager.py]"]
  node_plugins["Plugin Manager<br/>[manager.py]"]
end

subgraph group_execution["Tools and Execution"]
  node_mcp["MCP Tools<br/>[manager_auto.py]"]
  node_workspaces["Execution Workspaces<br/>[manager.py]"]
  node_asyncjobs["Async Jobs<br/>[jobs.py]"]
end

subgraph group_research["Research Workspace"]
  node_researchdata[("Research Records")]
  node_paperwiki["Paper Wiki"]
  node_workflow["Saved Workflows<br/>[manager.py]"]
  node_memory["Agent Memory<br/>[retriever.py]"]
end

subgraph group_results["Results and Continuation"]
  node_verification["Outcome Verification<br/>[outcome_guard.py]"]
  node_artifacts["Artifact Results<br/>[artifact_query.py]"]
  node_presentation["Interactive Results<br/>[canvas.py]"]
end

node_researcher(("Researcher"))
node_model(("Model Service"))

node_researcher -->|"starts research"| node_webui
node_webui -.->|"sends requests"| node_server
node_server -->|"manages sessions"| node_sessions
node_server -->|"selects agents"| node_agent
node_agent -->|"loads settings"| node_config
node_agent -.->|"runs turns"| node_harness
node_harness -.->|"requests completion"| node_model
node_harness -.->|"invokes tools"| node_mcp
node_plugins -.->|"configures integrations"| node_mcp
node_harness -->|"checks outcomes"| node_verification
node_researcher -->|"connects tools"| node_mcp
node_researcher -->|"submits long tasks"| node_asyncjobs
node_asyncjobs -.->|"dispatches remotely"| node_mcp
node_researcher -->|"chooses workspace"| node_workspaces
node_harness -.->|"queries artifacts"| node_artifacts
node_researcher -->|"reviews deliverables"| node_artifacts
node_researcher -->|"reviews visuals"| node_presentation
node_researcher -->|"organizes research"| node_researchdata
node_researcher -->|"reviews literature"| node_paperwiki
node_researcher -->|"saves repeated steps"| node_workflow
node_harness -.->|"uses context"| node_memory
node_sessions -.->|"retains research context"| node_researchdata

click node_webui "https://github.com/helplessness/benchthread/blob/main/web/src/App.tsx"
click node_server "https://github.com/helplessness/benchthread/blob/main/tcode_agent/server/app.py"
click node_sessions "https://github.com/helplessness/benchthread/blob/main/tcode_agent/session/manager.py"
click node_agent "https://github.com/helplessness/benchthread/blob/main/tcode_agent/agent/agents.py"
click node_harness "https://github.com/helplessness/benchthread/blob/main/tcode_agent/harness/engine.py"
click node_config "https://github.com/helplessness/benchthread/blob/main/tcode_agent/config/manager.py"
click node_plugins "https://github.com/helplessness/benchthread/blob/main/tcode_agent/plugins/manager.py"
click node_mcp "https://github.com/helplessness/benchthread/blob/main/tcode_agent/mcp/manager_auto.py"
click node_workspaces "https://github.com/helplessness/benchthread/blob/main/tcode_agent/workspace/manager.py"
click node_asyncjobs "https://github.com/helplessness/benchthread/blob/main/tcode_agent/runtime/jobs.py"
click node_verification "https://github.com/helplessness/benchthread/blob/main/tcode_agent/guard/outcome_guard.py"
click node_artifacts "https://github.com/helplessness/benchthread/blob/main/tcode_agent/tools/builtin/artifact_query.py"
click node_presentation "https://github.com/helplessness/benchthread/blob/main/tcode_agent/presentation/canvas.py"
click node_researchdata "https://github.com/helplessness/benchthread/tree/main/tcode_agent/research"
click node_paperwiki "https://github.com/helplessness/benchthread/tree/main/plugins/paper_research_workflow/wiki"
click node_workflow "https://github.com/helplessness/benchthread/blob/main/tcode_agent/workflow/manager.py"
click node_memory "https://github.com/helplessness/benchthread/blob/main/tcode_agent/memory/retriever.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_webui,node_server toneBlue
class node_sessions,node_agent,node_harness,node_config,node_plugins toneAmber
class node_mcp,node_workspaces,node_asyncjobs toneMint
class node_researchdata,node_paperwiki,node_workflow,node_memory toneRose
class node_verification,node_artifacts,node_presentation,node_researcher,node_model toneIndigo
```

## Components

### User Interaction

- [Web Workbench](https://github.com/helplessness/benchthread/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Server API](https://github.com/helplessness/benchthread/blob/main/tcode_agent/server/app.py): `tcode_agent/server/app.py`

### Agent Runtime

- [Sessions](https://github.com/helplessness/benchthread/blob/main/tcode_agent/session/manager.py): `tcode_agent/session/manager.py`
- [Agent Setup](https://github.com/helplessness/benchthread/blob/main/tcode_agent/agent/agents.py): `tcode_agent/agent/agents.py`
- [Turn Harness](https://github.com/helplessness/benchthread/blob/main/tcode_agent/harness/engine.py): `tcode_agent/harness/engine.py`
- [Configuration](https://github.com/helplessness/benchthread/blob/main/tcode_agent/config/manager.py): `tcode_agent/config/manager.py`
- [Plugin Manager](https://github.com/helplessness/benchthread/blob/main/tcode_agent/plugins/manager.py): `tcode_agent/plugins/manager.py`

### Tools and Execution

- [MCP Tools](https://github.com/helplessness/benchthread/blob/main/tcode_agent/mcp/manager_auto.py): `tcode_agent/mcp/manager_auto.py`
- [Execution Workspaces](https://github.com/helplessness/benchthread/blob/main/tcode_agent/workspace/manager.py): `tcode_agent/workspace/manager.py`
- [Async Jobs](https://github.com/helplessness/benchthread/blob/main/tcode_agent/runtime/jobs.py): `tcode_agent/runtime/jobs.py`

### Research Workspace

- [Research Records](https://github.com/helplessness/benchthread/tree/main/tcode_agent/research): `tcode_agent/research`
- [Paper Wiki](https://github.com/helplessness/benchthread/tree/main/plugins/paper_research_workflow/wiki): `plugins/paper_research_workflow/wiki`
- [Saved Workflows](https://github.com/helplessness/benchthread/blob/main/tcode_agent/workflow/manager.py): `tcode_agent/workflow/manager.py`
- [Agent Memory](https://github.com/helplessness/benchthread/blob/main/tcode_agent/memory/retriever.py): `tcode_agent/memory/retriever.py`

### Results and Continuation

- [Outcome Verification](https://github.com/helplessness/benchthread/blob/main/tcode_agent/guard/outcome_guard.py): `tcode_agent/guard/outcome_guard.py`
- [Artifact Results](https://github.com/helplessness/benchthread/blob/main/tcode_agent/tools/builtin/artifact_query.py): `tcode_agent/tools/builtin/artifact_query.py`
- [Interactive Results](https://github.com/helplessness/benchthread/blob/main/tcode_agent/presentation/canvas.py): `tcode_agent/presentation/canvas.py`

### Other components

- **Researcher**
- **Model Service**

## Connections

- Researcher → Web Workbench: starts research
- Web Workbench → Server API: sends requests
- Server API → Sessions: manages sessions (evidence: `tcode_agent/server/app.py`)
- Server API → Agent Setup: selects agents (evidence: `tcode_agent/server/app.py`)
- Agent Setup → Configuration: loads settings (evidence: `tcode_agent/agent/agents.py`)
- Agent Setup → Turn Harness: runs turns
- Turn Harness → Model Service: requests completion
- Turn Harness → MCP Tools: invokes tools
- Plugin Manager → MCP Tools: configures integrations (evidence: `tcode_agent/plugins/manager.py`)
- Turn Harness → Outcome Verification: checks outcomes (evidence: `tcode_agent/harness/engine.py`)
- Researcher → MCP Tools: connects tools
- Researcher → Async Jobs: submits long tasks
- Async Jobs → MCP Tools: dispatches remotely
- Researcher → Execution Workspaces: chooses workspace
- Turn Harness → Artifact Results: queries artifacts
- Researcher → Artifact Results: reviews deliverables
- Researcher → Interactive Results: reviews visuals
- Researcher → Research Records: organizes research
- Researcher → Paper Wiki: reviews literature
- Researcher → Saved Workflows: saves repeated steps
- Turn Harness → Agent Memory: uses context
- Sessions → Research Records: retains research context (evidence: `tcode_agent/session/manager.py`)