# naitchi/agent-smith architecture

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

- Interactive diagram: https://gitdiagram.com/naitchi/agent-smith
- Repository: https://github.com/naitchi/agent-smith

## Overview

Agent Smith solves MBPP coding exercises and SWE-bench repository issues through a Thought–Code–Observation loop. A benchmark CLI loads and validates a task, configures an LLM and sandbox, then the loop alternates model completions with sandbox execution until it has a solution; the CLI writes the result. The sandbox dynamically discovers MCP tools and proxies calls to the selected benchmark server. SWE-bench tools operate on a persistent Docker-backed repository, while MBPP tools provide the exercise-solving environment. The README documents both benchmark paths; unsampled implementation details are represented only where their roles and wiring are explicit.

Main entry points: [`agent/__init__.py`](https://github.com/naitchi/agent-smith/blob/main/agent/__init__.py) (CLI and task helpers), [`llm/provider.py`](https://github.com/naitchi/agent-smith/blob/main/llm/provider.py) (LLM provider), [`agent/agent_mbpp/__main__.py`](https://github.com/naitchi/agent-smith/blob/main/agent/agent_mbpp/__main__.py) (MBPP CLI), [`agent/agent_swebench/__main__.py`](https://github.com/naitchi/agent-smith/blob/main/agent/agent_swebench/__main__.py) (SWE-bench CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent and benchmarks"]
  node_mbpp_cli["MBPP CLI<br/>[__main__.py]"]
  node_swe_cli["SWE-bench CLI<br/>[__main__.py]"]
  node_shared_cli["CLI and task helpers<br/>[__init__.py]"]
  node_mbpp_input["MBPP task schema<br/>[mbpp_task_Input.py]"]
  node_swe_input["SWE-bench task schema"]
  node_agent_loop["Thought-code loop<br/>[agent_loop.py]"]
  node_solution["Solution output schema<br/>[solution_output.py]"]
end

subgraph group_model["Model access"]
  node_llm_registry["Provider registry<br/>[registry.py]"]
  node_llm_provider["LLM provider<br/>[provider.py]"]
  node_llm_rotator["Key rotation<br/>[rotator.py]"]
end

subgraph group_sandbox["Sandbox and MCP"]
  node_sandbox["Sandbox runtime<br/>[core.py]"]
  node_namespace["Persistent namespace<br/>[namespace.py]"]
  node_security["Execution security<br/>[security.py]"]
  node_mcp_bridge["MCP tool bridge<br/>[mcp_bridge.py]"]
  node_sync_client["Synchronous MCP client<br/>[mcp_sync_client.py]"]
  node_mcp_client["Async MCP client<br/>[mcp_client.py]"]
end

subgraph group_execution["Benchmark execution"]
  node_mbpp_server["MBPP tool server<br/>[mcp_tools_mbpp.py]"]
  node_swe_server["SWE-bench tool server"]
  node_docker_manager["Task repository container<br/>[docker_manager.py]"]
end

node_user(("Benchmark operator"))
node_llm_service(("LLM endpoint"))
node_docker["Docker engine"]
node_task_repo[("Task repository")]
node_result_file["Solution JSON file"]

node_user -->|"runs task"| node_mbpp_cli
node_user -->|"runs issue"| node_swe_cli
node_mbpp_cli -->|"uses helpers"| node_shared_cli
node_swe_cli -->|"uses helpers"| node_shared_cli
node_shared_cli -->|"validates task"| node_mbpp_input
node_shared_cli -->|"validates task"| node_swe_input
node_mbpp_cli -->|"runs loop"| node_agent_loop
node_swe_cli -->|"runs loop"| node_agent_loop
node_shared_cli -->|"configures model"| node_llm_registry
node_llm_registry -->|"creates provider"| node_llm_provider
node_llm_provider -->|"rotates keys"| node_llm_rotator
node_llm_provider -->|"sends completion"| node_llm_service
node_llm_service -->|"returns completion"| node_llm_provider
node_agent_loop -->|"requests completion"| node_llm_provider
node_agent_loop -->|"executes code"| node_sandbox
node_sandbox -->|"runs code"| node_namespace
node_sandbox -->|"enforces limits"| node_security
node_sandbox -->|"bridges tool calls"| node_mcp_bridge
node_mcp_bridge -->|"dispatches requests"| node_sync_client
node_sync_client -->|"drives async calls"| node_mcp_client
node_mcp_client -->|"connects MCP"| node_mbpp_server
node_mcp_client -->|"connects MCP"| node_swe_server
node_swe_server -->|"runs repository tools"| node_docker_manager
node_docker_manager -->|"manages container"| node_docker
node_docker -->|"hosts task checkout"| node_task_repo
node_mbpp_cli -->|"builds result"| node_solution
node_swe_cli -->|"builds result"| node_solution
node_shared_cli -->|"writes JSON"| node_result_file

click node_mbpp_cli "https://github.com/naitchi/agent-smith/blob/main/agent/agent_mbpp/__main__.py"
click node_swe_cli "https://github.com/naitchi/agent-smith/blob/main/agent/agent_swebench/__main__.py"
click node_shared_cli "https://github.com/naitchi/agent-smith/blob/main/agent/__init__.py"
click node_mbpp_input "https://github.com/naitchi/agent-smith/blob/main/schemas/mbpp_task_Input.py"
click node_swe_input "https://github.com/naitchi/agent-smith/blob/main/schemas/swe_bench_task_input.py"
click node_agent_loop "https://github.com/naitchi/agent-smith/blob/main/src/agent_loop.py"
click node_solution "https://github.com/naitchi/agent-smith/blob/main/schemas/solution_output.py"
click node_llm_registry "https://github.com/naitchi/agent-smith/blob/main/llm/registry.py"
click node_llm_provider "https://github.com/naitchi/agent-smith/blob/main/llm/provider.py"
click node_llm_rotator "https://github.com/naitchi/agent-smith/blob/main/llm/rotator.py"
click node_sandbox "https://github.com/naitchi/agent-smith/blob/main/src/sandbox/core.py"
click node_namespace "https://github.com/naitchi/agent-smith/blob/main/src/sandbox/namespace.py"
click node_security "https://github.com/naitchi/agent-smith/blob/main/src/sandbox/security.py"
click node_mcp_bridge "https://github.com/naitchi/agent-smith/blob/main/src/sandbox/mcp_bridge.py"
click node_sync_client "https://github.com/naitchi/agent-smith/blob/main/src/mcp_sync_client.py"
click node_mcp_client "https://github.com/naitchi/agent-smith/blob/main/src/mcp_client.py"
click node_mbpp_server "https://github.com/naitchi/agent-smith/blob/main/mcp_tools_mbpp.py"
click node_swe_server "https://github.com/naitchi/agent-smith/blob/main/mcp_tools_swebench.py"
click node_docker_manager "https://github.com/naitchi/agent-smith/blob/main/src/docker_manager.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_mbpp_cli,node_swe_cli,node_shared_cli,node_mbpp_input,node_swe_input,node_agent_loop,node_solution toneBlue
class node_llm_registry,node_llm_provider,node_llm_rotator,node_task_repo toneAmber
class node_sandbox,node_namespace,node_security,node_mcp_bridge,node_sync_client,node_mcp_client toneMint
class node_mbpp_server,node_swe_server,node_docker_manager toneRose
class node_user,node_llm_service,node_docker,node_result_file toneIndigo
```

## Components

### Agent and benchmarks

- [MBPP CLI](https://github.com/naitchi/agent-smith/blob/main/agent/agent_mbpp/__main__.py): `agent/agent_mbpp/__main__.py`
- [SWE-bench CLI](https://github.com/naitchi/agent-smith/blob/main/agent/agent_swebench/__main__.py): `agent/agent_swebench/__main__.py`
- [CLI and task helpers](https://github.com/naitchi/agent-smith/blob/main/agent/__init__.py): `agent/__init__.py`
- [MBPP task schema](https://github.com/naitchi/agent-smith/blob/main/schemas/mbpp_task_Input.py): `schemas/mbpp_task_Input.py`
- [SWE-bench task schema](https://github.com/naitchi/agent-smith/blob/main/schemas/swe_bench_task_input.py): `schemas/swe_bench_task_input.py`
- [Thought-code loop](https://github.com/naitchi/agent-smith/blob/main/src/agent_loop.py): `src/agent_loop.py`
- [Solution output schema](https://github.com/naitchi/agent-smith/blob/main/schemas/solution_output.py): `schemas/solution_output.py`

### Model access

- [Provider registry](https://github.com/naitchi/agent-smith/blob/main/llm/registry.py): `llm/registry.py`
- [LLM provider](https://github.com/naitchi/agent-smith/blob/main/llm/provider.py): `llm/provider.py`
- [Key rotation](https://github.com/naitchi/agent-smith/blob/main/llm/rotator.py): `llm/rotator.py`

### Sandbox and MCP

- [Sandbox runtime](https://github.com/naitchi/agent-smith/blob/main/src/sandbox/core.py): `src/sandbox/core.py`
- [Persistent namespace](https://github.com/naitchi/agent-smith/blob/main/src/sandbox/namespace.py): `src/sandbox/namespace.py`
- [Execution security](https://github.com/naitchi/agent-smith/blob/main/src/sandbox/security.py): `src/sandbox/security.py`
- [MCP tool bridge](https://github.com/naitchi/agent-smith/blob/main/src/sandbox/mcp_bridge.py): `src/sandbox/mcp_bridge.py`
- [Synchronous MCP client](https://github.com/naitchi/agent-smith/blob/main/src/mcp_sync_client.py): `src/mcp_sync_client.py`
- [Async MCP client](https://github.com/naitchi/agent-smith/blob/main/src/mcp_client.py): `src/mcp_client.py`

### Benchmark execution

- [MBPP tool server](https://github.com/naitchi/agent-smith/blob/main/mcp_tools_mbpp.py): `mcp_tools_mbpp.py`
- [SWE-bench tool server](https://github.com/naitchi/agent-smith/blob/main/mcp_tools_swebench.py): `mcp_tools_swebench.py`
- [Task repository container](https://github.com/naitchi/agent-smith/blob/main/src/docker_manager.py): `src/docker_manager.py`

### Other components

- **Benchmark operator**
- **LLM endpoint**
- **Docker engine**
- **Task repository**
- **Solution JSON file**

## Connections

- Benchmark operator → MBPP CLI: runs task
- Benchmark operator → SWE-bench CLI: runs issue
- MBPP CLI → CLI and task helpers: uses helpers
- SWE-bench CLI → CLI and task helpers: uses helpers
- CLI and task helpers → MBPP task schema: validates task
- CLI and task helpers → SWE-bench task schema: validates task
- MBPP CLI → Thought-code loop: runs loop
- SWE-bench CLI → Thought-code loop: runs loop
- CLI and task helpers → Provider registry: configures model
- Provider registry → LLM provider: creates provider
- LLM provider → Key rotation: rotates keys
- LLM provider → LLM endpoint: sends completion
- LLM endpoint → LLM provider: returns completion
- Thought-code loop → LLM provider: requests completion
- Thought-code loop → Sandbox runtime: executes code
- Sandbox runtime → Persistent namespace: runs code
- Sandbox runtime → Execution security: enforces limits
- Sandbox runtime → MCP tool bridge: bridges tool calls
- MCP tool bridge → Synchronous MCP client: dispatches requests
- Synchronous MCP client → Async MCP client: drives async calls
- Async MCP client → MBPP tool server: connects MCP
- Async MCP client → SWE-bench tool server: connects MCP
- SWE-bench tool server → Task repository container: runs repository tools
- Task repository container → Docker engine: manages container
- Docker engine → Task repository: hosts task checkout
- MBPP CLI → Solution output schema: builds result
- SWE-bench CLI → Solution output schema: builds result
- CLI and task helpers → Solution JSON file: writes JSON