How to Contribute to the Open-SWE Project: A Complete Developer Guide

To contribute to the open-swe project, fork the repository, set up a local development environment using uv, understand the LangGraph-based architecture, and submit changes via pull request after running the test suite.

Open-SWE is an open-source framework maintained by LangChain AI that enables organizations to run internal coding agents. Whether you want to add new tools, extend middleware, or improve webhook handlers, this guide walks you through the exact steps to contribute to the open-swe project using the actual source files and development workflows from the langchain-ai/open-swe repository.

Setting Up Your Open-SWE Development Environment

Clone and Install Dependencies

Start by forking the repository and creating a local workspace. The project uses uv for dependency management and pyproject.toml to define all requirements:

git clone https://github.com/langchain-ai/open-swe.git && cd open-swe
uv venv && source .venv/bin/activate
uv sync --all-extras

The --all-extras flag installs test, lint, and integration dependencies. Verify your setup by running the test suite:

uv run pytest

You can also run specific test files, such as uv run pytest tests/test_github_issue_webhook.py, to validate webhook handling logic.

Configure Local Webhook Testing

To test Slack, Linear, or GitHub webhooks locally, you need a public tunnel. Install ngrok and expose the default LangGraph development port:

ngrok http 2024

Copy the generated public URL into your GitHub App or Slack app configuration. The INSTALLATION.md file contains detailed instructions for creating temporary apps and setting required environment variables like GITHUB_WEBHOOK_SECRET, SLACK_SIGNING_SECRET, and LINEAR_WEBHOOK_SECRET.

Launch the Development Server

Start the LangGraph server to expose the FastAPI application defined in agent/webapp.py:

uv run langgraph dev --no-browser

This command loads the agent harness, middleware stack, and webhook endpoints without automatically opening a browser window.

Understanding the Open-SWE Architecture

Core Components Overview

Open-SWE is built on LangGraph and Deep Agents. The architecture separates concerns into distinct layers:

• Agent Harness – Located in agent/webapp.py (lines 42-49), the create_deep_agent function assembles the LLM, tool list, and middleware stack.
• Sandbox – Defined in agent/utils/sandbox.py, this abstraction runs tasks in isolated cloud environments (Modal, Daytona, Runloop, or LangSmith) selected via DEFAULT_SANDBOX_TEMPLATE_* environment variables.
• Tools – Individual capabilities located in agent/tools/ (e.g., agent/tools/commit_and_open_pr.py, agent/tools/http_request.py) that the LLM can invoke.
• Middleware – Deterministic hooks in agent/middleware/ such as tool_error_handler.py and open_pr.py that execute before or after LLM calls.
• Invocation Surfaces – FastAPI endpoints in agent/webapp.py (/webhooks/slack, /webhooks/linear, /webhooks/github) that translate external events into LangGraph runs.
• State Persistence – Utilities in agent/utils/github_token.py and agent/utils/auth.py manage encrypted tokens and per-thread metadata.

Request Flow Through the System

When a webhook arrives, the system processes it through a standardized pipeline:

1. Webhook Reception – A Slack mention, Linear comment, or GitHub comment hits the appropriate /webhooks/* route in agent/webapp.py.
2. Signature Verification – Each route validates the request using environment-specific secrets (SLACK_SIGNING_SECRET, LINEAR_WEBHOOK_SECRET, GITHUB_WEBHOOK_SECRET).
3. Context Extraction – Helper utilities (agent/utils/slack.py, agent/utils/linear.py, agent/utils/github_comments.py) fetch full thread content, author emails, and AGENTS.md rules.
4. Thread Management – The system generates deterministic thread IDs (e.g., generate_thread_id_from_github_issue) and checks is_thread_active to avoid duplicate runs. If active, messages are queued via queue_message_for_thread.
5. Agent Execution – langgraph_client.runs.create spawns a LangGraph run with the assembled prompt, tool list, and metadata.
6. Middleware Processing – Hooks like open_pr_if_needed and tool_error_handler execute deterministically around LLM calls.
7. Token Persistence – GitHub tokens are encrypted and stored per-thread using persist_encrypted_github_token.

Understanding this flow helps you identify where to add features (new tools in agent/tools/) or fix bugs (webhook handling in agent/webapp.py).

Making Your First Contribution

Common Contribution Types

The langchain-ai/open-swe repository welcomes several categories of contributions:

• New Tools – Add capabilities in agent/tools/ and register them in agent/webapp.py (e.g., agent/tools/http_request.py).
• Middleware Extensions – Create deterministic hooks in agent/middleware/ for logging, validation, or error handling.
• Webhook Improvements – Enhance payload parsing or validation in agent/webapp.py routes like /webhooks/slack.
• Test Coverage – Add pytest cases in tests/ for new functionality or edge cases.
• Documentation – Update README.md, INSTALLATION.md, or CUSTOMIZATION.md with setup guides or architecture explanations.

Step-by-Step Example: Adding a New Tool

Here is a complete example of adding a list_branches tool that returns Git branches from the sandbox. This demonstrates the file structure and registration process used throughout the codebase.

Create the tool implementation in agent/tools/list_branches.py:

"""Tool that lists all Git branches in the sandbox repository."""
import subprocess
from typing import List

from langchain_core.tools import Tool

def _run_git_branches() -> List[str]:
    """Execute `git branch --format='%(refname:short)'` and return a list."""
    result = subprocess.run(
        ["git", "branch", "--format=%(refname:short)"],
        capture_output=True,
        text=True,
        check=False,
    )
    # Split on newlines, strip empties, and sort for deterministic output

    return sorted([line.strip() for line in result.stdout.splitlines() if line.strip()])

list_branches_tool = Tool(
    name="list_branches",
    description="Return a list of all Git branches in the current repository.",
    func=lambda _: "\n".join(_run_git_branches()),
)

Register the tool in agent/webapp.py. First, add the import at the top of the file, then append the tool to the list passed to create_deep_agent (around line 46):

# At the top of agent/webapp.py

from .tools.list_branches import list_branches_tool

# In the create_deep_agent call (around line 46)

tools=[http_request, fetch_url, commit_and_open_pr,
       linear_comment, slack_thread_reply,
       list_branches_tool]   # ← newly added tool

Testing and Linting Your Changes

Before submitting, validate your changes against the repository standards:

# Run the full test suite

uv run pytest

# Check specific functionality

uv run pytest tests/test_github_issue_webhook.py

# Lint and format checks

uv run ruff check .
uv run ruff format --check .

All tests must pass and code must conform to the project's style guidelines defined in pyproject.toml.

Submitting Changes to the Repository

Once your changes are tested and linted, use the following workflow to submit them:

1. Create a feature branch: git checkout -b feat/your-feature-name
2. Commit your changes: git commit -m "feat: description of change"
3. Open a Pull Request: Use the built-in commit_and_open_pr tool (defined in agent/tools/commit_and_open_pr.py) to create a draft PR automatically, or push to your fork and open a PR manually via GitHub.

The commit_and_open_pr tool handles branch creation, commit formatting, and PR description generation based on your changes.

Include a descriptive title referencing the primary keyword, a detailed description explaining the purpose, and links to any related issues. The GitHub Actions workflow defined in .github/workflows/ci.yml will automatically run the full test matrix on your PR.

Address any review feedback promptly. When reviewers tag @open-swe, the agent can respond automatically to clarify implementation details or push fixes.

Summary

• To contribute to the open-swe project, start by cloning the repository and setting up a Python environment using uv with all extras installed via pyproject.toml.
• Understand the architecture by studying the agent harness in agent/webapp.py, the tool implementations in agent/tools/, and the middleware stack in agent/middleware/.
• Add new functionality by creating tools in agent/tools/, registering them in agent/webapp.py, and writing corresponding tests in tests/.
• Validate changes by running uv run pytest for tests and uv run ruff check . for linting before submitting.
• Submit contributions using the commit_and_open_pr tool or manual PR creation, ensuring CI passes and review feedback is addressed.

Frequently Asked Questions

What programming languages and frameworks does Open-SWE use?

Open-SWE is built primarily in Python using LangGraph for orchestration and Deep Agents for the agent implementation. The web layer uses FastAPI (defined in agent/webapp.py), and the project uses uv for Python environment management. The frontend interactions are handled through webhooks from Slack, Linear, and GitHub.

Do I need access to cloud sandbox providers to contribute?

No, you can contribute to many parts of the codebase—including tools, middleware, and webhook handlers—without cloud sandbox access. The sandbox abstraction in agent/utils/sandbox.py supports multiple providers (Modal, Daytona, Runloop, LangSmith) via environment variables like DEFAULT_SANDBOX_TEMPLATE_*. For local development, you can mock sandbox interactions or use the LangSmith backend if you have API keys.

How do I test webhook handlers locally?

Use ngrok to create a public tunnel to your local development server. Run ngrok http 2024 (the default LangGraph port), then configure your GitHub App, Slack app, or Linear webhook to point to the ngrok URL. The webhook handlers in agent/webapp.py (routes /webhooks/slack, /webhooks/linear, /webhooks/github) will receive the payloads, and you can debug the full request flow including signature verification and context extraction.

What is the process for adding a new tool to the agent?

Create a new Python file in agent/tools/ implementing the tool logic, then register it in agent/webapp.py. For example, to add a list_branches tool, you would create agent/tools/list_branches.py using the langchain_core.tools.Tool class, import it in agent/webapp.py, and append it to the tools list passed to create_deep_agent. Always add corresponding tests in tests/ and run uv run pytest to ensure the new tool integrates correctly with the middleware stack.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}