# carlos-mb/agentsmith architecture

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

- Interactive diagram: https://gitdiagram.com/carlos-mb/agentsmith
- Repository: https://github.com/carlos-mb/agentsmith

## Overview

Agent Smith is an autonomous coding agent for MBPP exercises and SWE-bench repository issues. A CLI loads a task and invokes its benchmark adapter; the shared loop requests model output, extracts executable code, runs it in a persistent restricted worker, and feeds observations back until completion or limits. Worker tool calls are relayed through the agent to an MCP server. MBPP tools run candidate tests in Docker; SWE-bench tools inspect and edit a checkout, run its tests, and return a patch. README documents both adapters; sampled excerpts confirm shared-loop, provider, worker, MCP, and SWE tool behavior, but not every adapter call.

Main entry points: [`agent_smith/io.py`](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/io.py) (Task I/O), [`agent_smith/agent_loop.py`](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/agent_loop.py) (Thought loop), [`agent_mbpp.py`](https://github.com/carlos-mb/agentsmith/blob/master/agent_mbpp.py) (MBPP CLI), [`agent_swebench.py`](https://github.com/carlos-mb/agentsmith/blob/master/agent_swebench.py) (SWE CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Task entry"]
  node_mbpp_cli["MBPP CLI<br/>[agent_mbpp.py]"]
  node_swe_cli["SWE CLI<br/>[agent_swebench.py]"]
  node_task_io["Task I/O<br/>[io.py]"]
  node_models["Task models<br/>[models.py]"]
end

subgraph group_loop["Agent loop"]
  node_loop_core["Thought loop<br/>[agent_loop.py]"]
  node_provider["LLM provider<br/>[providers.py]"]
  node_extract["Code extraction<br/>[code_extraction.py]"]
end

subgraph group_execution["Execution tools"]
  node_worker_session["Worker session<br/>[sandbox_session.py]"]
  node_worker["Restricted worker<br/>[sandbox.py]"]
  node_mcp_client["MCP client<br/>[mcp_client.py]"]
end

subgraph group_benchmarks["Benchmark adapters"]
  node_mbpp_adapter["MBPP adapter<br/>[mbpp_agent.py]"]
  node_swe_adapter["SWE adapter<br/>[swebench_agent.py]"]
  node_mbpp_server["MBPP MCP tools<br/>[mcp_tools_mbpp.py]"]
  node_mbpp_tests["MBPP test runner<br/>[mbpp_tools.py]"]
  node_swe_server["SWE MCP tools"]
  node_swe_tools["SWE repository tools<br/>[swebench_tools.py]"]
  node_swe_environment["SWE container<br/>[swebench_agent.py]"]
end

node_user(("Task operator"))
node_model_service{{"LLM service"}}
node_docker{{"Docker"}}
node_checkout["Task checkout"]
node_solution["Solution output"]

node_user -->|"starts task"| node_mbpp_cli
node_user -->|"starts task"| node_swe_cli
node_mbpp_cli -->|"loads task"| node_task_io
node_swe_cli -->|"loads task"| node_task_io
node_task_io -->|"validates data"| node_models
node_mbpp_cli -->|"runs adapter"| node_mbpp_adapter
node_swe_cli -->|"runs adapter"| node_swe_adapter
node_mbpp_adapter -->|"starts loop"| node_loop_core
node_swe_adapter -->|"starts loop"| node_loop_core
node_loop_core -->|"requests completion"| node_provider
node_provider -->|"sends request"| node_model_service
node_loop_core -->|"extracts code"| node_extract
node_loop_core -->|"executes code"| node_worker_session
node_worker_session -->|"sends code"| node_worker
node_worker -->|"returns observation"| node_worker_session
node_worker_session -->|"dispatches tool call"| node_mcp_client
node_mcp_client -.->|"calls tools"| node_mbpp_server
node_mcp_client -.->|"calls tools"| node_swe_server
node_mbpp_server -->|"delegates tests"| node_mbpp_tests
node_mbpp_tests -->|"runs tests"| node_docker
node_swe_server -->|"delegates operations"| node_swe_tools
node_swe_tools -->|"reads and edits"| node_checkout
node_swe_tools -.->|"runs container commands"| node_docker
node_swe_adapter -->|"starts container"| node_swe_environment
node_swe_environment -->|"manages container"| node_docker
node_mbpp_cli -->|"writes result"| node_task_io
node_swe_cli -->|"writes result"| node_task_io
node_task_io -->|"serializes output"| node_solution

click node_mbpp_cli "https://github.com/carlos-mb/agentsmith/blob/master/agent_mbpp.py"
click node_swe_cli "https://github.com/carlos-mb/agentsmith/blob/master/agent_swebench.py"
click node_task_io "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/io.py"
click node_models "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/models.py"
click node_mbpp_adapter "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/mbpp_agent.py"
click node_swe_adapter "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/swebench_agent.py"
click node_loop_core "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/agent_loop.py"
click node_provider "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/providers.py"
click node_extract "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/code_extraction.py"
click node_worker_session "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/sandbox_session.py"
click node_worker "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/sandbox.py"
click node_mcp_client "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/mcp_client.py"
click node_mbpp_server "https://github.com/carlos-mb/agentsmith/blob/master/mcp_tools_mbpp.py"
click node_mbpp_tests "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/mbpp_tools.py"
click node_swe_server "https://github.com/carlos-mb/agentsmith/blob/master/mcp_tools_swebench.py"
click node_swe_tools "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/swebench_tools.py"
click node_swe_environment "https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/swebench_agent.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_task_io,node_models toneBlue
class node_loop_core,node_provider,node_extract toneAmber
class node_worker_session,node_worker,node_mcp_client toneMint
class node_mbpp_adapter,node_swe_adapter,node_mbpp_server,node_mbpp_tests,node_swe_server,node_swe_tools,node_swe_environment,node_user,node_checkout toneRose
class node_model_service,node_docker,node_solution toneIndigo
```

## Components

### Task entry

- [MBPP CLI](https://github.com/carlos-mb/agentsmith/blob/master/agent_mbpp.py): `agent_mbpp.py`
- [SWE CLI](https://github.com/carlos-mb/agentsmith/blob/master/agent_swebench.py): `agent_swebench.py`
- [Task I/O](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/io.py): `agent_smith/io.py`
- [Task models](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/models.py): `agent_smith/models.py`

### Agent loop

- [Thought loop](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/agent_loop.py): `agent_smith/agent_loop.py`
- [LLM provider](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/providers.py): `agent_smith/providers.py`
- [Code extraction](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/code_extraction.py): `agent_smith/code_extraction.py`

### Execution tools

- [Worker session](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/sandbox_session.py): `agent_smith/sandbox_session.py`
- [Restricted worker](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/sandbox.py): `agent_smith/sandbox.py`
- [MCP client](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/mcp_client.py): `agent_smith/mcp_client.py`

### Benchmark adapters

- [MBPP adapter](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/mbpp_agent.py): `agent_smith/mbpp_agent.py`
- [SWE adapter](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/swebench_agent.py): `agent_smith/swebench_agent.py`
- [MBPP MCP tools](https://github.com/carlos-mb/agentsmith/blob/master/mcp_tools_mbpp.py): `mcp_tools_mbpp.py`
- [MBPP test runner](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/mbpp_tools.py): `agent_smith/mbpp_tools.py`
- [SWE MCP tools](https://github.com/carlos-mb/agentsmith/blob/master/mcp_tools_swebench.py): `mcp_tools_swebench.py`
- [SWE repository tools](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/swebench_tools.py): `agent_smith/swebench_tools.py`
- [SWE container](https://github.com/carlos-mb/agentsmith/blob/master/agent_smith/swebench_agent.py): `agent_smith/swebench_agent.py`

### Other components

- **Task operator**
- **LLM service**
- **Docker**
- **Task checkout**
- **Solution output**

## Connections

- Task operator → MBPP CLI: starts task
- Task operator → SWE CLI: starts task
- MBPP CLI → Task I/O: loads task
- SWE CLI → Task I/O: loads task
- Task I/O → Task models: validates data
- MBPP CLI → MBPP adapter: runs adapter
- SWE CLI → SWE adapter: runs adapter
- MBPP adapter → Thought loop: starts loop
- SWE adapter → Thought loop: starts loop
- Thought loop → LLM provider: requests completion
- LLM provider → LLM service: sends request
- Thought loop → Code extraction: extracts code
- Thought loop → Worker session: executes code
- Worker session → Restricted worker: sends code
- Restricted worker → Worker session: returns observation
- Worker session → MCP client: dispatches tool call
- MCP client → MBPP MCP tools: calls tools
- MCP client → SWE MCP tools: calls tools
- MBPP MCP tools → MBPP test runner: delegates tests
- MBPP test runner → Docker: runs tests
- SWE MCP tools → SWE repository tools: delegates operations
- SWE repository tools → Task checkout: reads and edits
- SWE repository tools → Docker: runs container commands
- SWE adapter → SWE container: starts container
- SWE container → Docker: manages container
- MBPP CLI → Task I/O: writes result
- SWE CLI → Task I/O: writes result
- Task I/O → Solution output: serializes output