# princeton-nlp/swe-agent architecture

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

- Interactive diagram: https://gitdiagram.com/princeton-nlp/swe-agent
- Repository: https://github.com/princeton-nlp/swe-agent

## Overview

#### Purpose and entry points
SWE-agent is a Python CLI framework that lets an LLM solve repository tasks through shell-backed tools: issue fixing, benchmarking, custom coding tasks, and legacy CTF workflows. The package entry point is `sweagent/__main__.py`; run orchestration is centered in `sweagent/run/run.py`, with single-instance, batch, replay, and shell modes in `sweagent/run/run_single.py`, `sweagent/run/run_batch.py`, and `sweagent/run/run_replay.py`.

#### Configuration-driven assembly
A YAML configuration selects the model, agent behavior, environment, prompts, tools, and run settings. Shared loading/serialization logic is in `sweagent/utils/config.py`; canonical and scenario-specific configurations live in `config/default.yaml`, `config/benchmarks/`, and `config/sweagent_0_7/`. This is the principal extension boundary: new experiments should compose configuration and existing abstractions rather than alter orchestration.

#### Agent control loop
The agent layer converts a problem and accumulated trajectory into model calls, parses model actions, executes them, and iterates until submission/termination. Core implementations and extension points are `sweagent/agent/agents.py`, `sweagent/agent/action_sampler.py`, and `sweagent/agent/models.py`. History reduction and multimodal/problem input handling sit at `sweagent/agent/history_processors.py` and `sweagent/agent/problem_statement.py`; hooks expose status/lifecycle observation under `sweagent/agent/hooks/`.

#### Model-provider boundary
`sweagent/agent/models.py` isolates LLM invocation and model configuration from the agent loop. It supports the README’s “language model of choice” model while preserving a common action-sampling interface. Credentials and runtime environment values are expected externally (for example `.env.example`), rather than embedded in task configs.

#### Sandboxed repository environment
The environment layer owns the target checkout and command-execution boundary: `sweagent/environment/repo.py` represents repository setup/state, while `sweagent/environment/swe_env.py` provides the agent-facing execution environment. Environment hooks in `sweagent/environment/hooks/` report lifecycle/status. This boundary is where host/container isolation, repository mutation, installation, and test execution are controlled.

#### Tool protocol and executable bundles
Tool definitions are assembled from configured bundles, command metadata, and parsers in `sweagent/tools/bundle.py`, `sweagent/tools/commands.py`, and `sweagent/tools/parsing.py`. The actual agent-visible commands are external executable assets under `tools/`, such as `tools/search/`, `tools/windowed_edit_replace/`, and `tools/submit/`. This cleanly separates Python orchestration from shell/tool implementation and permits specialized capabilities including browser and image tools.

#### Runs, artifacts, and downstream integration
Run modules create trajectories and prediction/patch artifacts, support batch execution, replay, merging, comparison, and statistics. Key paths are `sweagent/run/common.py`, `sweagent/run/batch_instances.py`, and `sweagent/run/hooks/`. Run hooks can apply patches, invoke SWE-bench evaluation, or open GitHub pull requests via `sweagent/run/hooks/apply_patch.py`, `sweagent/run/hooks/swe_bench_evaluate.py`, and `sweagent/run/hooks/open_pr.py`; GitHub-specific utilities are in `sweagent/utils/github.py`.

#### Inspection and operational surfaces
A local trajectory inspector is provided by `sweagent/inspector/server.py` and its static UI in `sweagent/inspector/index.html`. The project runs on Python, uses shell commands and potentially containerized target environments, calls external LLM providers, integrates with GitHub, and optionally evaluates against SWE-bench. Documentation is built with MkDocs (`mkdocs.yml`), but it is separate from agent runtime architecture.

Main entry points: [`sweagent/agent/agents.py`](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/agent/agents.py) (Agent loop), [`sweagent/run/run_single.py`](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/run/run_single.py) (Run modes), [`sweagent/utils/config.py`](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/utils/config.py) (Config loader), [`sweagent/run/run.py`](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/run/run.py) (Run orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Configuration"]
  node_config_loader["Config loader<br/>Python config<br/>[config.py]"]
  node_default_config["Default config<br/>YAML config<br/>[default.yaml]"]
  node_scenario_configs["Scenario configs<br/>YAML configs"]
end

subgraph group_agent["Agent Runtime"]
  node_agent_loop["Agent loop<br/>Python agent<br/>[agents.py]"]
  node_action_sampler["Action sampler<br/>Python protocol<br/>[action_sampler.py]"]
  node_model_provider["Model provider boundary<br/>Python adapter<br/>[models.py]"]
  node_history_input["History &amp; problem input<br/>Python processing"]
  node_agent_hooks["Agent hooks<br/>Lifecycle hooks"]
end

subgraph group_execution["Execution"]
  node_run["Run orchestrator<br/>Python orchestration<br/>[run.py]"]
  node_run_modes["Run modes<br/>Python commands<br/>[run_single.py]"]
  node_repo_state["Repository state<br/>Python environment<br/>[repo.py]"]
  node_sandbox_env["Sandbox environment<br/>Python execution boundary<br/>[swe_env.py]"]
  node_tool_protocol["Tool protocol<br/>Python tool assembly<br/>[bundle.py]"]
  node_tool_assets["Executable tool bundles<br/>Shell tools"]
end

subgraph group_integration["Outputs &amp; Integrations"]
  node_run_artifacts["Run artifacts<br/>Trajectories &amp; patches<br/>[common.py]"]
  node_run_hooks["Run hooks<br/>Integration hooks"]
  node_inspector["Trajectory inspector<br/>Local web server<br/>[server.py]"]
end

node_cli["CLI entry point<br/>Python entry<br/>[__main__.py]"]
node_external_llm{{"External LLM providers<br/>External service"}}
node_github{{"GitHub<br/>External service"}}
node_swe_bench{{"SWE-bench evaluation<br/>External evaluator"}}

node_cli -->|"starts"| node_run
node_run -->|"dispatches"| node_run_modes
node_run -->|"loads"| node_config_loader
node_config_loader -->|"reads"| node_default_config
node_config_loader -->|"composes"| node_scenario_configs
node_run_modes -->|"executes"| node_agent_loop
node_run_modes -->|"creates"| node_repo_state
node_agent_loop -->|"uses"| node_history_input
node_agent_loop -->|"samples actions"| node_action_sampler
node_action_sampler -->|"requests completion"| node_model_provider
node_model_provider -->|"invokes"| node_external_llm
node_agent_loop -->|"executes actions"| node_sandbox_env
node_sandbox_env -->|"mutates checkout"| node_repo_state
node_sandbox_env -->|"exposes"| node_tool_protocol
node_tool_protocol -->|"runs"| node_tool_assets
node_agent_loop -.->|"emits lifecycle"| node_agent_hooks
node_run_modes -->|"writes"| node_run_artifacts
node_run_artifacts -->|"inspected by"| node_inspector
node_run_artifacts -.->|"triggers"| node_run_hooks
node_run_hooks -->|"opens PRs"| node_github
node_run_hooks -->|"evaluates"| node_swe_bench

click node_cli "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/__main__.py"
click node_run "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/run/run.py"
click node_run_modes "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/run/run_single.py"
click node_config_loader "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/utils/config.py"
click node_default_config "https://github.com/princeton-nlp/swe-agent/blob/main/config/default.yaml"
click node_agent_loop "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/agent/agents.py"
click node_action_sampler "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/agent/action_sampler.py"
click node_model_provider "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/agent/models.py"
click node_history_input "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/agent/history_processors.py"
click node_repo_state "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/environment/repo.py"
click node_sandbox_env "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/environment/swe_env.py"
click node_tool_protocol "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/tools/bundle.py"
click node_run_artifacts "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/run/common.py"
click node_inspector "https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/inspector/server.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_config_loader,node_default_config,node_scenario_configs toneBlue
class node_agent_loop,node_action_sampler,node_model_provider,node_history_input,node_agent_hooks toneAmber
class node_run,node_run_modes,node_repo_state,node_sandbox_env,node_tool_protocol,node_tool_assets toneMint
class node_run_artifacts,node_run_hooks,node_inspector toneRose
class node_cli,node_external_llm,node_github,node_swe_bench toneNeutral
```

## Components

### Configuration

YAML composition selects runtime components.

- [Config loader](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/utils/config.py): Python config · Loads and serializes composed runtime configuration. · `sweagent/utils/config.py`
- [Default config](https://github.com/princeton-nlp/swe-agent/blob/main/config/default.yaml): YAML config · `config/default.yaml`
- **Scenario configs**: YAML configs · Benchmark and version-specific experiment configurations.

### Agent Runtime

LLM-driven control loop and action protocol.

- [Agent loop](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/agent/agents.py): Python agent · Iterates model actions against problem state and trajectory. · `sweagent/agent/agents.py`
- [Action sampler](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/agent/action_sampler.py): Python protocol · Parses and samples model actions through the common interface. · `sweagent/agent/action_sampler.py`
- [Model provider boundary](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/agent/models.py): Python adapter · Isolates LLM invocation and model configuration. · `sweagent/agent/models.py`
- [History & problem input](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/agent/history_processors.py): Python processing · Reduces history and handles problem or multimodal input. · `sweagent/agent/history_processors.py`
- **Agent hooks**: Lifecycle hooks

### Execution

Sandboxed repository mutation and run management.

- [Run orchestrator](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/run/run.py): Python orchestration · Assembles configured runs and dispatches execution modes. · `sweagent/run/run.py`
- [Run modes](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/run/run_single.py): Python commands · Single, batch, replay, and shell workflows. · `sweagent/run/run_single.py`
- [Repository state](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/environment/repo.py): Python environment · Owns target checkout setup and state. · `sweagent/environment/repo.py`
- [Sandbox environment](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/environment/swe_env.py): Python execution boundary · Runs agent-facing commands with controlled isolation. · `sweagent/environment/swe_env.py`
- [Tool protocol](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/tools/bundle.py): Python tool assembly · Builds configured bundles, command metadata, and parsers. · `sweagent/tools/bundle.py`
- **Executable tool bundles**: Shell tools · Agent-visible command implementations such as search, edit, and submit.

### Outputs & Integrations

Artifacts, inspection, and optional downstream actions.

- [Run artifacts](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/run/common.py): Trajectories & patches · Creates predictions and patch outputs for runs. · `sweagent/run/common.py`
- **Run hooks**: Integration hooks · Applies patches, evaluates SWE-bench, or opens pull requests.
- [Trajectory inspector](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/inspector/server.py): Local web server · Serves the local trajectory inspection interface. · `sweagent/inspector/server.py`

### Other components

- [CLI entry point](https://github.com/princeton-nlp/swe-agent/blob/main/sweagent/__main__.py): Python entry · `sweagent/__main__.py`
- **External LLM providers**: External service · Credentials and runtime values are supplied outside task configs.
- **GitHub**: External service · Optional patch and pull-request destination.
- **SWE-bench evaluation**: External evaluator

## Connections

- CLI entry point → Run orchestrator: starts
- Run orchestrator → Run modes: dispatches
- Run orchestrator → Config loader: loads
- Config loader → Default config: reads
- Config loader → Scenario configs: composes
- Run modes → Agent loop: executes
- Run modes → Repository state: creates
- Agent loop → History & problem input: uses
- Agent loop → Action sampler: samples actions
- Action sampler → Model provider boundary: requests completion
- Model provider boundary → External LLM providers: invokes
- Agent loop → Sandbox environment: executes actions
- Sandbox environment → Repository state: mutates checkout
- Sandbox environment → Tool protocol: exposes
- Tool protocol → Executable tool bundles: runs
- Agent loop → Agent hooks: emits lifecycle
- Run modes → Run artifacts: writes
- Run artifacts → Trajectory inspector: inspected by
- Run artifacts → Run hooks: triggers
- Run hooks → GitHub: opens PRs
- Run hooks → SWE-bench evaluation: evaluates