Skip to content
Get packs

Guide · Open source

How to use SWE-agent: setup, first run and what to know

Updated · written with AI from the project's own documentation and checked against our catalogue data

SWE-agent is an open-source Python project that takes a GitHub issue and lets a language model you pick use tools to try to fix it in a real repository. This guide is for developers, researchers and students who want to experiment with that workflow. By the end you will know what you need before installing, how to get the source, what the project is configured with, and when another tool is a better choice.

SWE-agentSWE-agent/SWE-agent · ★ 20.7k · MIT

Quick start

  1. 1Decide if SWE-agent fits. Read the README warning that mini-SWE-agent is now the recommended tool. Continue only if you are doing research or want to experiment.
  2. 2Prepare Git and Python. Install Git and Python. The README excerpt does not state the Python version, so confirm it in the docs.
  3. 3Get access to a language model. Arrange API access to a model such as GPT-4o or Claude Sonnet 4, since the README assumes you bring your own.
  4. 4Clone the repository. Run git clone https://github.com/SWE-agent/SWE-agent.git to download the source.
  5. 5Build from the installation guide. Follow the source installation guide at swe-agent.com to build the project.
  6. 6Run the hello world example. Follow the command line hello world guide to run your first issue fix.
  7. 7Edit the YAML config. Adjust the single YAML configuration file to change model and agent settings.

Check whether SWE-agent is the right tool for you

Before you install anything, read the project's own warning. The README says most current development has moved to mini-SWE-agent, which has superseded SWE-agent and which the maintainers recommend instead going forward. The same note says mini-SWE-agent matches SWE-agent's performance while being much simpler.

SWE-agent is framed as research code. It suits people studying autonomous coding agents or running SWE-bench experiments, students learning how agent-computer interfaces work, and developers who want to try an LLM on issues in their own repositories. It is not a polished finished product.

  • Good fit: research, SWE-bench experiments, learning how agents work, hands-on experiments
  • Poor fit: teams wanting the recommended tool, anyone needing a finished product, anyone without access to a language model API

What you need before you start

The README assumes you bring your own language model. It names GPT-4o and Claude Sonnet 4 as examples of models you can use, so you need access to a model through an API. The excerpt does not state a Python version, so check the installation documentation for the version you need.

You also need Git to clone the repository and Python to run it. The README links to a Codespaces option for trying it in a browser, which avoids local setup.

  • Git
  • Python (the required version is not stated in the README excerpt; check the docs)
  • Access to a language model you can pay for or use via API

Install SWE-agent from source

SWE-agent is installed by cloning the repository and building it from source. The README gives the clone command below. The full build steps are in the project's installation guide at swe-agent.com, which this tutorial does not reproduce.

If you do not want to set anything up locally, the README links to a GitHub Codespaces button for running it in the browser.

  • Open the installation guide at swe-agent.com/latest/installation/source/ for build steps
  • Use Codespaces if you prefer to try it without a local install
git clone https://github.com/SWE-agent/SWE-agent.git

Run your first issue fix

The project's documentation includes a 'Hello world from the command line' page, which the README links to. Follow that page for the exact command to run an issue fix, since the README excerpt does not include it.

SWE-agent is configured through a single YAML file. Its README describes this as fully documented, so you can change the model and agent behaviour in one place rather than editing code. Use the documentation to find the configuration file and its options.

  • Start with the hello world guide at swe-agent.com/latest/usage/hello_world/
  • Keep your model choice and settings in the YAML configuration file

Use SWE-agent for other tasks

The README describes two other modes. EnIGMA is a mode for offensive cybersecurity capture-the-flag challenges. The README says it reached state-of-the-art results on several cybersecurity benchmarks, and it asks users to run SWE-agent 0.7 while EnIGMA is updated for version 1.0. The README also mentions custom tasks through a coding challenges guide.

For benchmarking on SWE-bench, the README links to a batch mode guide.

  • Cybersecurity CTF challenges: EnIGMA mode, using SWE-agent 0.7 per the README
  • Custom coding tasks: see the coding challenges guide
  • Benchmark runs: see the batch mode guide on SWE-bench

Know the licence and the alternatives

SWE-agent is licensed under MIT, as the README states. Check the LICENSE file in the repository for the full text. The project accepts issues and pull requests, and asks for discussion in issues before large code changes.

If mini-SWE-agent is not what you need, the README lists related projects. Comparable tools to consider are OpenHands, Aider and SWE-ReX, which the README links to as part of the wider SWE-agent family.

  • Licence: MIT
  • Comparable projects: mini-SWE-agent, OpenHands, Aider, SWE-ReX

What people use it for

  • Attempting automated fixes for GitHub issues in your own repository, to see how a model handles them
  • Running SWE-bench experiments as part of autonomous coding research
  • Solving offensive cybersecurity capture-the-flag challenges with the EnIGMA mode
  • Studying how agent-computer interfaces work by reading and modifying a small, hackable codebase

Frequently asked questions

Is SWE-agent free to use?

SWE-agent is licensed under the MIT licence, according to its README. The README assumes you supply your own language model, so you should expect to pay for or access a model separately.

What are the requirements for SWE-agent?

You need Git to clone the repository and Python to run it. The README excerpt does not state a Python version, so check the installation docs. You also need access to a language model, since the README assumes you bring your own.

How do I install SWE-agent?

Clone the repository with git clone https://github.com/SWE-agent/SWE-agent.git, then follow the source installation guide at swe-agent.com to build it. The README does not include the full build steps.

Should I use SWE-agent or mini-SWE-agent?

The README says most development has moved to mini-SWE-agent, which has superseded SWE-agent and is recommended instead. It also says mini-SWE-agent matches SWE-agent's performance while being much simpler.

Which alternatives are similar to SWE-agent?

The README lists mini-SWE-agent, OpenHands, Aider and SWE-ReX as comparable projects. Choose based on whether you need a research sandbox, a more finished tool or a simpler agent.

Can SWE-agent be used for cybersecurity?

Yes, through the EnIGMA mode for offensive cybersecurity capture-the-flag challenges. The README asks users to run SWE-agent 0.7 while EnIGMA is updated for version 1.0.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

SWE-agent suits researchers, students and developers who want a hackable, research-grade agent and can supply their own language model. If you need a recommended, finished tool, the project itself points you to mini-SWE-agent, and OpenHands or Aider are other options to compare.

Install options & downloads