Command line basics
Command line basics
This tutorial walks you through running SWE-agent from the command line.
- Please read our hello world tutorial before proceeding.
- This tutorial focuses on using SWE-agent as a tool to solve individual issues. Benchmarking SWE-agent is covered separately. Finally, we have a different tutorial for using SWE-agent for coding challenges.
A few examples
Before we start with a more structured explanation of the command line options, here are a few examples that you might find immediately useful:
python run.py \
--agent.model.name=gpt4 \
--agent.model.per_instance_cost_limit=2.00 \
--env.repo.github_url=https://github.com/SWE-agent/test-repo \
--problem_statement.github_url=https://github.com/SWE-agent/test-repo/issues/1
python run.py \
...
--env.repo.github_url=https://github.com/SWE-agent/test-repo \
--problem_statement.text="Hey, can you fix all the bugs?"
git clone https://github.com/SWE-agent/test-repo.git
python run.py \
--agent.model.name=claude-3.5 \
--env.repo.path=test-repo \
--problem_statement.path=test-repo/problem_statements/1.md \
--env.deployment.image=python:3.12
- Make sure to add anthropic keys (or keys for your model provider) to the environment for this one!
--env.deployment.imagepoints to the dockerhub image of the same name
For the next example, we will use a cloud-based execution environment instead of using local docker containers.
For this, you first need to set up a modal account, install the necessary extra dependencies pip install 'swe-rex[modal]', then run:
python run.py \
...
--env.deployment.type=modal \
--env.deployment.image=python:3.12
All options
Run python run.py --help to see all available options for run.py. This tutorial will only cover a subset of options.
Configuration files
All configuration options can be specified either in one or more .yaml files, or as command line arguments. For example, our first command can be written as
python run.py --config my_run.yaml
agent:
model:
name: gpt4
per_instance_cost_limit: 2.00
env:
repo:
github_url: https://github.com/SWE-agent/test-repo
problem_statement:
github_url: https://github.com/SWE-agent/test-repo/issues/1
But we can also split it up into multiple files and additional command line options:
python run.py --config agent.yaml --config env.yaml \
--problem_statement.text="Hey, can you fix all the bugs?"
agent:
model:
name: gpt4
per_instance_cost_limit: 2.00
env:
repo:
github_url: https://github.com/SWE-agent/test-repo
The default config file is config/anthropic_filemap.yaml. Let's take a look at it:
Example: default config anthropic_filemap.yaml
# This template is heavily inspired by anthropic's computer use demo
agent:
templates:
system_template: |-
You are a helpful assistant that can interact with a computer to solve tasks.
instance_template: |-
<uploaded_files>
{{working_dir}}
</uploaded_files>
I've uploaded a python code repository in the directory {{working_dir}}. Consider the following PR description:
<pr_description>
{{problem_statement}}
</pr_description>
Can you help me implement the necessary changes to the repository so that the requirements specified in the <pr_description> are met?
I've already taken care of all changes to any of the test files described in the <pr_description>. This means you DON'T have to modify the testing logic or any of the tests in any way!
Your task is to make the minimal changes to non-tests files in the {{working_dir}} directory to ensure the <pr_description> is satisfied.
Follow these steps to resolve the issue:
1. As a first step, it might be a good idea to find and read code relevant to the <pr_description>
2. Create a script to reproduce the error and execute it with `python <filename.py>` using the bash tool, to confirm the error
3. Edit the sourcecode of the repo to resolve the issue
4. Rerun your reproduce script and confirm that the error is fixed!
5. Think about edgecases and make sure your fix handles them as well
Your thinking should be thorough and so it's fine if it's very long.
next_step_template: |-
OBSERVATION:
{{observation}}
next_step_no_output_template: |-
Your command ran successfully and did not produce any output.
tools:
bundles:
- path: tools/registry
- path: tools/edit_anthropic
- path: tools/review_on_submit_m
registry_variables:
USE_FILEMAP: 'true'
SUBMIT_REVIEW_MESSAGES:
- |
Thank you for your work on this issue. Please carefully follow the steps below to help review your changes.
1. If you made any changes to your code after running the reproduction script, please run the reproduction script again.
If the reproduction script is failing, please revisit your changes and make sure they are correct.
If you have already removed your reproduction script, please ignore this step.
2. Remove your reproduction script (if you haven't done so already).
3. If you have modified any TEST files, please revert them to the state they had before you started fixing the issue.
You can do this with `git checkout -- /path/to/test/file.py`. Use below <diff> to find the files you need to revert.
4. Run the submit command again to confirm.
Here is a list of all of your changes:
<diff>
{{diff}}
</diff>
enable_bash_tool: true
parse_function:
type: function_calling
history_processors:
- type: cache_control
last_n_messages: 2
As you can see, this is where all the templates are defined!
This file is also loaded when no other --config options are specified.
So to make sure that we get the default templates in the above examples with --config, we should have added
--config config/anthropic_filemap.yaml
in addition to all the other --config options for the two examples above.
Problem statements and union types
Operating in batch mode: Running on SWE-bench and other benchmark sets
If you want to run SWE-agent in batch mode on SWE-bench or another whole evaluation set, see batch mode. This tutorial focuses on using SWE-agent on individual issues.
We've already seen a few examples of how to specify the problem to solve, namely
--problem_statement.data_path /path/to/problem.md
--problem_statement.repo_path /path/to/repo
--problem_statement.text="..."
Each of these types of problems can have specific configuration options.
To understand how this works, we'll need to understand union types.
Running sweagent run builds up a configuration object that essentially looks like this:
agent: AgentConfig
env: EnvironmentConfig
problem_statement: TextProblemStatement | GithubIssue | FileProblemStatement # (1)!
- This is a union type, meaning that the problem statement can be one of the three types.
Each of these configuration objects has its own set of options:
So how do we know which configuration object to initialize?
It's simple: Each of these types has a different set of required options (e.g., github_url is required for GithubIssue, but not for TextProblemStatement).
SWE-agent will automatically select the correct configuration object based on the command line options you provide.
However, you can also explicitly specify the type of problem statement you want to use by adding a --problem_statement.type option.
Union type errors
If you ever ran a SWE-agent command and got a very long error message about various configuration options not working, it is because for union types.
If everything works correctly, we try to initialize every option until we find the one that works based on your inputs (for example stopping at TextProblemStatement if you provided a --problem_statement.text).
However, if none of them work, we throw an error which then tells you why we cannot initialize any of the types (so it will tell you that github_url is required for GithubIssue, even though you might not even have tried to work on a GitHub issue).
Example union type errors
This is the output of running
sweagent run --problem_statement.path="test" --problem_statement.github_url="asdf"
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Validation error │
│ │
│ The following errors are raised by Pydantic, trying to instantiate the configuration based on │
│ the merged configuration dictionary (see above). │
│ │
│ Every new indented block corresponds to a different error from Pydantic. │
│ The first line of each block is the attribute that failed validation, the following lines are the error messages. │
│ │
│ If you see many lines of errors, there are probably different ways to instantiate the same object (a union type). │
│ For example, there are different deployments with different options each. Pydantic is then trying │
│ one after the other and reporting the failures for each of them. │
│ │
│ 8 validation errors for RunSingleConfig │
│ agent.model │
│ Field required }, input_type=dict] │
│ For further information visit https://errors.pydantic.dev/2.9/v/missing │
│ problem_statement.TextProblemStatement.text │
│ Field required │
│ For further information visit https://errors.pydantic.dev/2.9/v/missing │
│ problem_statement.TextProblemStatement.path │
│ Extra inputs are not permitted │
│ For further information visit https://errors.pydantic.dev/2.9/v/extra_forbidden │
│ problem_statement.TextProblemStatement.github_url │
│ Extra inputs are not permitted │
│ For further information visit https://errors.pydantic.dev/2.9/v/extra_forbidden │
│ problem_statement.GithubIssue.path │
│ Extra inputs are not permitted │
│ For further information visit https://errors.pydantic.dev/2.9/v/extra_forbidden │
│ problem_statement.EmptyProblemStatement.path │
│ Extra inputs are not permitted │
│ For further information visit https://errors.pydantic.dev/2.9/v/extra_forbidden │
│ problem_statement.EmptyProblemStatement.github_url │
│ Extra inputs are not permitted │
│ For further information visit https://errors.pydantic.dev/2.9/v/extra_forbidden │
│ problem_statement.FileProblemStatement.github_url │
│ Extra inputs are not permitted │
│ For further information visit https://errors.pydantic.dev/2.9/v/extra_forbidden │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
If you want to read more about how this works, check out the pydantic docs.
Specifying the repository
The repository can be specified in a few different ways:
--env.repo.github_url=https://github.com/SWE-agent/test-repo
--env.repo.path=/path/to/repo
Again, those are union types. See here for all the options:
GithubRepoConfig: Pull a repository from GitHub.LocalRepoConfig: Copies a repository from your local filesystem to the docker container.PreExistingRepoConfig: If you want to use a repository that already exists on the docker container.
Configuring the environment
We mainly recommend you to build a docker image with all the dependencies you need and then use that with --env.deployment.image.
In addition, you can also execute additional commands before starting the agent with env.post_startup_commands, which takes a list of commands, e.g.,
sweagent run \
--agent.model.name=claude-3-7-sonnet-latest \
--env.post_startup_commands='["pip install flake8"]' \
...
Note the list syntax that is passed as a string using single ticks '. This is particularly important for zsh where [, ] have special meaning.
Here's an example of a custom docker environment (it's also available in the repo as docker/tiny_test.Dockerfile):
FROM python:3.11.10-bullseye # (1)!
ARG DEBIAN_FRONTEND=noninteractive # (2)!
ENV TZ=Etc/UTC # (3)!
WORKDIR /
# SWE-ReX will always attempt to install its server into your docker container
# however, this takes a couple of seconds. If we already provide it in the image,
# this is much faster.
RUN pip install pipx
RUN pipx install swe-rex # (4)!
RUN pipx ensurepath # (5)!
RUN pip install flake8 # (6)!
SHELL ["/bin/bash", "-c"]
# This is where pipx installs things
ENV PATH="$PATH:/root/.local/bin/" # (7)!
Click on the icon in the right margin of the code snippet to see more information about the lines.
- This is the base image.
- This is to avoid any interactive prompts from the package manager.
- Again, this avoids interactive prompts
- SWE-ReX is our execution backend. We start a small server within the container, which receives commands from the agent and executes them.
- This ensures that the path where pipx installs things is in the
$PATHvariable. - This is to install flake8, which is used by some of our edit tools.
- Unfortunately, step 5 sometimes still doesn't properly add the SWE-ReX server to the
$PATHvariable. So we do it here again.
Taking actions
- You can use
--actions.apply_patch_locallyto have SWE-agent apply successful solution attempts to local files. - Alternatively, when running on a GitHub issue, you can have the agent automatically open a PR if the issue has been solved by supplying the
--actions.open_prflag. Please use this feature responsibly (on your own repositories or after careful consideration).
All action options
See RunSingleActionConfig for all action options.
Alternatively, you can always retrieve the patch that was generated by SWE-agent. Watch out for the following message in the log:
╭──────────────────────────── 🎉 Submission successful 🎉 ────────────────────────────╮
│ SWE-agent has produced a patch that it believes will solve the issue you submitted! │
│ Use the code snippet below to inspect or apply it! │
╰─────────────────────────────────────────────────────────────────────────────────────╯
And follow the instructions below it:
# The patch has been saved to your local filesystem at:
PATCH_FILE_PATH='/Users/.../patches/05917d.patch'
# Inspect it:
cat "${PATCH_FILE_PATH}"
# Apply it to a local repository:
cd <your local repo root>
git apply "${PATCH_FILE_PATH}"
-
Something broken? Report bug
-
Something unclear? Ask question
