In 2023 the founders of this project asked a question that sounds naive and turned out to be profound: if you put a language model inside a terminal, can it fix a real GitHub issue? The answer, published with the SWE-bench benchmark, was yes — with conditions. The decisive discovery was not the model but the interface. An agent that types raw bash commands flails; an agent given a purpose-built environment — a linter that responds with concise errors, a file viewer that shows a window instead of a whole file, a search tool that reports counts instead of dumping matches — succeeds dramatically more often. The team named this principle the agent-computer interface, and the argument generalizes: designing the environment is as important as designing the model. That idea reshaped how every later coding agent is built, which is why this codebase still matters even though its README now points to a leaner successor. As always in this series, what follows is an educational tour of published source code.

The architecture is a chain of runners, one agent class, and a containerized environment. Runners in sweagent/run/ load task instances from datasets or GitHub, build agents from a single YAML file, and drive them either one at a time or across a whole benchmark. The agent itself is a loop: format the problem statement, query the language model, parse the reply into an action, execute it in the container, observe the result, repeat until the model declares submission. Around that loop sit the support systems that make it survive contact with reality — provider wrappers with retry logic, history processors that compress a growing transcript, hooks that turn a finished run into a pull request, and a local web app for replaying trajectories step by step. MIT-licensed and installable with pip install sweagent, it remains one of the clearest full-stack references for what “coding agent” actually means in code.

SWE-agent at a glance: batch and single runners load instances and drive the agent, which queries LM APIs and samples actions, compacts history, and executes in the Dockerized SWEEnv mounted on the target repo, with tool bundles, YAML config, and the trajectory inspector around the loop.

Reading the overview from left to right:

• The batch runner drives the agent over a whole dataset with progress tracking.
• The single runner runs one agent against one repository.
• SWEAgent is the forward-query-parse-execute loop, eleven hundred lines.
• The LM API layer wraps every provider with retries and cost tracking.
• History processors compress the transcript before it drowns the context window.
• SWEEnv owns the Docker container where commands actually run.
• The tool layer installs bundles like windowed editing and search into the container.
• The inspector replays a recorded trajectory step by step in a browser.

Why You Need This

The first reason is the agent loop itself, because almost every coding agent since is a variation on it. agents.py implements what the authors call the ReLoop: a forward pass that renders the system template and current history, a model query through the LM API layer, parsing of the reply into an action, execution in the environment, and an observation appended to history — repeated until the model emits a submission. What makes the file worth reading is the failure handling layered on that skeleton: retry loops with exponential backoff for rate limits, cost and token accounting per run, a pluggable action sampler that can retry formatting when the model output does not parse, and an explicit trajectory format where every step is recorded with its thought, action, and observation. There is also a reviewer module that runs a second LM pass to judge whether an attempt is acceptable — an early, readable example of the judge pattern now common in agent evaluation.

The second reason is the environment, because the agent-computer interface thesis lives there. swe_env.py manages the full Docker lifecycle: start a container from a per-instance image, clone and check out the repository under repair through the repo wrapper, install the tool bundles as a zipped package, then execute commands and return observations. The bundles themselves are the interesting part — the windowed editing bundle defines view, edit, and search commands whose outputs are deliberately constrained, and the parser accepts function-call, XML, or backtick formats while routing malformed output to typed errors the agent can recover from. Every design decision here is a documented lesson in making a model more capable by changing what the terminal says back to it.

The third reason is the batch and evaluation machinery, which is what turned one agent run into reproducible science. The batch runner loads instances through the batch instance loaders — from local files, GitHub issues, or Hugging Face datasets — then runs agents in parallel with configurable hooks: apply the patch to the repository, open a pull request from a successful fix, or hand results to the SWE-bench evaluator. Completed runs become replayable artifacts — the replay runner re-executes a recorded trajectory deterministically, the demo converter renders one as a shareable page, and the inspector browses them step by step. The default prompt templates in the default config show exactly what the model is told, down to the demonstration transcript embedded in its system template.

The detail view: runners with instance loaders and batch hooks on the left, the agent core with its LM layer, samplers, history processors and reviewer in the middle, the Docker environment and tool bundles beneath, and the output chain of patch formatting, PR hooks, replays and inspection on the right.

The detail view shows how far the abstractions stretch. On the runner side, run/common.py holds the CLI plumbing both modes share, while the problem statement module normalizes whatever the task is — issue text, a plain string, or a file — into one interface the agent template can render. In the agent core, the shell agent shows a prompt-free variant that lives entirely inside one interactive shell session, a useful contrast with the templated default. Tool definitions flow from YAML through the command documentation parser into the model’s system template, so the tool belt a model sees is fully declarative. Even the analysis side is wired in: merge predictions combines outputs from parallel runs and quick stats summarizes pass rates without leaving the repo.

From Install to a Fixed Bug

The quickstart is one pip command and one environment variable. pip install sweagent, export OPENAI_API_KEY or your provider’s key, then sweagent run --config config/default.yaml --problem_statement.github_url <issue url> — the tool starts a container, clones the repository, and lets the agent work the issue, streaming each thought, action, and observation to the terminal. Batch evaluation takes the same shape: point sweagent run-batch at a dataset, add --apply_patch or --open_pr hooks, and collect trajectories plus patches. One caution: the maintainers state plainly that SWE-agent is made for research, and that the mini-swe-agent project has superseded it for production use. Read this repo to understand the interface principle and the full loop; use its successor when you need something leaner. The templates, the parsing errors, and the history processors remain the most-copied ideas in the codebase — they taught an entire field how to shape a terminal for a model.

Honest limits: the codebase assumes Docker everywhere, so Windows users go through WSL, and container startup dominates startup time for small experiments. The default models configuration is OpenAI-centric, with other providers requiring per-provider setup. Cost control is real but manual — a run that loops on a hard instance can burn a meaningful budget, and the counters are per-run rather than per-batch ceilings. The README itself cautions that this project is research-oriented, with the mini-swe-agent line recommended for production, and parts of the tooling — notably some hook and bundle combinations — are documented mostly by their source rather than by guides. None of that diminishes its teaching value; it just means this is a laboratory instrument, not an appliance.

Enjoyed this post? Never miss out on future posts by following us