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

> Contribute to the open-swe project by forking the repo, setting up your dev environment, understanding LangGraph, and submitting pull requests. Start contributing today!

- Repository: [LangChain/open-swe](https://github.com/langchain-ai/open-swe)
- Tags: how-to-guide
- Published: 2026-03-19

---

**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`](https://github.com/langchain-ai/open-swe/blob/main/pyproject.toml) to define all requirements:

```bash
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:

```bash
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:

```bash
ngrok http 2024

```

Copy the generated public URL into your GitHub App or Slack app configuration. The [`INSTALLATION.md`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/agent/webapp.py):

```bash
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`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/agent/tools/commit_and_open_pr.py), [`agent/tools/http_request.py`](https://github.com/langchain-ai/open-swe/blob/main/agent/tools/http_request.py)) that the LLM can invoke.
- **Middleware** – Deterministic hooks in `agent/middleware/` such as [`tool_error_handler.py`](https://github.com/langchain-ai/open-swe/blob/main/tool_error_handler.py) and [`open_pr.py`](https://github.com/langchain-ai/open-swe/blob/main/open_pr.py) that execute before or after LLM calls.
- **Invocation Surfaces** – FastAPI endpoints in [`agent/webapp.py`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/agent/utils/github_token.py) and [`agent/utils/auth.py`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/agent/utils/slack.py), [`agent/utils/linear.py`](https://github.com/langchain-ai/open-swe/blob/main/agent/utils/linear.py), [`agent/utils/github_comments.py`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/agent/webapp.py) (e.g., [`agent/tools/http_request.py`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/agent/webapp.py) routes like `/webhooks/slack`.
- **Test Coverage** – Add pytest cases in `tests/` for new functionality or edge cases.
- **Documentation** – Update [`README.md`](https://github.com/langchain-ai/open-swe/blob/main/README.md), [`INSTALLATION.md`](https://github.com/langchain-ai/open-swe/blob/main/INSTALLATION.md), or [`CUSTOMIZATION.md`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/agent/tools/list_branches.py):

```python
"""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`](https://github.com/langchain-ai/open-swe/blob/main/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):

```python

# 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:

```bash

# 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`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/.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`](https://github.com/langchain-ai/open-swe/blob/main/pyproject.toml).
- **Understand the architecture** by studying the agent harness in [`agent/webapp.py`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/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`](https://github.com/langchain-ai/open-swe/blob/main/agent/webapp.py). For example, to add a `list_branches` tool, you would create [`agent/tools/list_branches.py`](https://github.com/langchain-ai/open-swe/blob/main/agent/tools/list_branches.py) using the `langchain_core.tools.Tool` class, import it in [`agent/webapp.py`](https://github.com/langchain-ai/open-swe/blob/main/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.