From 5c493ea1c7f5f938689ad880dce1eac9770a26f9 Mon Sep 17 00:00:00 2001 From: Harrison Chase Date: Sat, 7 Mar 2026 13:24:10 -0800 Subject: [PATCH] cr --- README.md | 178 ++++++++++++++++++++++++++---------------------------- 1 file changed, 87 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 0f9d6e2c..4aa3b0b4 100644 --- a/README.md +++ b/README.md @@ -7,136 +7,132 @@
-

Open SWE - An Open-Source Asynchronous Coding Agent

+

Open SWE

+

The open-source framework for building your org's internal coding agent

-Open SWE is an open-source cloud-based asynchronous coding agent built with [LangGraph](https://docs.langchain.com/oss/javascript/langgraph/overview). It autonomously understands codebases, plans solutions, and executes code changes across entire repositoriesβ€”from initial planning to opening pull requests. +Elite engineering orgs like Stripe, Ramp, and Coinbase are building their own internal coding agents β€” Slackbots, CLIs, and web apps that meet engineers where they already work. These agents are connected to internal systems with the right context, permissioning, and safety boundaries to operate with minimal human oversight. -> -> **Note: you're required to set your own LLM API keys to use the demo.** +Open SWE is the open-source version of this pattern. Built on [LangGraph](https://langchain-ai.github.io/langgraph/) and [Deep Agents](https://github.com/langchain-ai/deepagents), it gives you the same architecture those companies built internally: cloud sandboxes, Slack and Linear invocation, subagent orchestration, and automatic PR creation β€” ready to customize for your own codebase and workflows. > [!NOTE] > πŸ’¬ Read the **announcement blog post [here](https://blog.langchain.com/introducing-open-swe-an-open-source-asynchronous-coding-agent/)** -# Features +--- -- πŸ”— **Trigger from Linear, Slack, or GitHub** β€” mention `@openswe` in a Linear comment, Slack thread, or GitHub PR comment to kick off a task -- πŸ‘€ **Instant acknowledgement** β€” reacts with πŸ‘€ the moment it picks up your message so you know it's on it -- πŸ’¬ **Message it while it's running** β€” send follow-up messages mid-task and it'll pick them up before its next step -- πŸ”€ **Run multiple tasks in parallel** β€” each task runs in its own isolated cloud sandbox, no queuing -- πŸ” **GitHub OAuth built-in** β€” authenticates with your GitHub account automatically, no token setup needed -- πŸš€ **Opens PRs automatically** β€” commits changes and opens a draft PR when done, linked back to your Linear ticket +## Architecture +Open SWE makes the same core architectural decisions as the best internal coding agents. Here's how it maps to the patterns described in [this overview](https://x.com/kishan_dahya/status/2028971339974099317) of Stripe's Minions, Ramp's Inspect, and Coinbase's Cloudbot: -## Installation +### 1. Agent Harness β€” Composed on Deep Agents -### Prerequisites +Rather than forking an existing agent or building from scratch, Open SWE **composes** on the [Deep Agents](https://github.com/langchain-ai/deepagents) framework β€” similar to how Ramp built on top of OpenCode. This gives you an upgrade path (pull in upstream improvements) while letting you customize the orchestration, tools, and middleware for your org. -- Python 3.11+ -- [uv](https://docs.astral.sh/uv/) package manager -- [LangGraph CLI](https://langchain-ai.github.io/langgraph/cloud/reference/cli/) -- [ngrok](https://ngrok.com/) (for exposing local webhooks) - -### 1. Clone the repo - -```bash -git clone https://github.com/langchain-ai/open-swe.git -cd open-swe/apps/agent +```python +create_deep_agent( + model="anthropic:claude-opus-4-6", + system_prompt=construct_system_prompt(repo_dir, ...), + tools=[http_request, fetch_url, commit_and_open_pr, linear_comment, slack_thread_reply], + backend=sandbox_backend, + middleware=[ToolErrorMiddleware(), check_message_queue_before_model, ...], +) ``` -### 2. Install dependencies +### 2. Sandbox β€” Isolated Cloud Environments -```bash -uv sync -``` +Every task runs in its own **isolated cloud sandbox** β€” a remote Linux environment with full shell access. The repo is cloned in, the agent gets full permissions, and the blast radius of any mistake is fully contained. No production access, no confirmation prompts. -### 3. Set up the Linear webhook +Open SWE supports multiple sandbox providers out of the box β€” [Modal](https://modal.com/), [Daytona](https://www.daytona.io/), [Runloop](https://www.runloop.ai/), and [LangSmith](https://smith.langchain.com/) β€” and you can plug in your own. See the [Customization Guide](CUSTOMIZATION.md#1-sandbox) for details. -In a terminal, start ngrok to get your public URL: +This follows the principle all three companies converge on: **isolate first, then give full permissions inside the boundary.** -```bash -ngrok http 2024 -# e.g. https://xxxx.ngrok.io +- Each thread gets a persistent sandbox (reused across follow-up messages) +- Sandboxes auto-recreate if they become unreachable +- Multiple tasks run in parallel β€” each in its own sandbox, no queuing -``` +### 3. Tools β€” Curated, Not Accumulated -Then in Linear: +Stripe's key insight: *tool curation matters more than tool quantity.* Open SWE follows this principle with a small, focused toolset: -1. Go to **Settings** β†’ **API** β†’ **Webhooks** β†’ **New webhook** -2. Fill in: - - **Label**: `open-swe` - - **URL**: `https://xxxx.ngrok.io/webhooks/linear` - - **Secret**: generate one with `openssl rand -hex 32` β€” copy it, you'll need it for `LINEAR_WEBHOOK_SECRET` -3. Under **Data change events**, enable **Comments** β†’ `Create` only -4. Click **Create webhook** +| Tool | Purpose | +|---|---| +| `execute` | Shell commands in the sandbox | +| `fetch_url` | Fetch web pages as markdown | +| `http_request` | API calls (GET, POST, etc.) | +| `commit_and_open_pr` | Git commit + open a GitHub draft PR | +| `linear_comment` | Post updates to Linear tickets | +| `slack_thread_reply` | Reply in Slack threads | -To get your `LINEAR_API_KEY` (set this under `LINEAR_API_KEY` in `.env`): +Plus the built-in Deep Agents tools: `read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`, `write_todos`, and `task` (subagent spawning). -1. Go to **Settings** β†’ **API** β†’ **Personal API keys** β†’ **New API key** -2. Name it `open-swe`, select **All access**, and copy the key +### 4. Context Engineering β€” AGENTS.md + Source Context -### 4. Set environment variables +Open SWE gathers context from two sources: -Create a `.env` file in `apps/agent/` with the following: +- **`AGENTS.md`** β€” If the repo contains an `AGENTS.md` file at the root, it's read from the sandbox and injected into the system prompt. This is your repo-level equivalent of Stripe's rule files: encoding conventions, testing requirements, and architectural decisions that every agent run should follow. +- **Source context** β€” The full Linear issue (title, description, comments) or Slack thread history is assembled and passed to the agent, so it starts with rich context rather than discovering everything through tool calls. -```bash -# LangSmith -LANGSMITH_API_KEY_PROD="" # Your LangSmith API key -LANGCHAIN_TRACING_V2="true" -LANGCHAIN_PROJECT="" +### 5. Orchestration β€” Subagents + Middleware -# LLM -ANTHROPIC_API_KEY="" # Anthropic API key (recommended default provider) +Open SWE's orchestration has two layers: -# GitHub App (Bot) -GITHUB_APP_ID="" # GitHub App ID -GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- -... ------END RSA PRIVATE KEY----- -" -GITHUB_APP_INSTALLATION_ID="" # GitHub App installation ID +**Subagents:** The Deep Agents framework natively supports spawning child agents via the `task` tool. The main agent can fan out independent subtasks to isolated subagents β€” each with its own middleware stack, todo list, and file operations. This is similar to Ramp's child sessions for parallel work. -# GitHub Webhook -# Generate with: openssl rand -hex 32 -GITHUB_WEBHOOK_SECRET="" +**Middleware:** Deterministic middleware hooks run around the agent loop: -# Linear -LINEAR_API_KEY="" # Linear API key (from step 3) -LINEAR_WEBHOOK_SECRET="" # Secret you set when creating the webhook (from step 3) +- **`check_message_queue_before_model`** β€” Injects follow-up messages (Linear comments or Slack messages that arrive mid-run) before the next model call. You can message the agent while it's working and it'll pick up your input at its next step. +- **`open_pr_if_needed`** β€” After-agent safety net that commits and opens a PR if the agent didn't do it itself. This is a lightweight version of Stripe's deterministic nodes β€” ensuring critical steps happen regardless of LLM behavior. +- **`ToolErrorMiddleware`** β€” Catches and handles tool errors gracefully. -# Slack (optional) -SLACK_BOT_TOKEN="" -SLACK_BOT_USER_ID="" -SLACK_BOT_USERNAME="" -SLACK_SIGNING_SECRET="" +### 6. Invocation β€” Slack, Linear, and GitHub -# Sandbox -DEFAULT_SANDBOX_TEMPLATE_NAME="" # LangSmith sandbox template name (uses default if not set) +All three companies in the article converge on **Slack as the primary invocation surface**. Open SWE does the same: -# Token encryption -# Generate with: openssl rand -base64 32 -TOKEN_ENCRYPTION_KEY="" -``` +- **Slack** β€” Mention the bot in any thread. Supports `repo:owner/name` syntax to specify which repo to work on. The agent replies in-thread with status updates and PR links. +- **Linear** β€” Comment `@openswe` on any issue. The agent reads the full issue context, reacts with πŸ‘€ to acknowledge, and posts results back as comments. +- **GitHub** β€” Tag `@openswe` in PR comments on agent-created PRs to have it address review feedback and push fixes to the same branch. -### 5. Run the agent +Each invocation creates a deterministic thread ID, so follow-up messages on the same issue or thread route to the same running agent. -```bash -uv run langgraph dev --no-browser -``` +### 7. Validation β€” Prompt-Driven + Safety Nets -The LangGraph server runs on `http://localhost:2024` and serves the webhook endpoints automatically. +The agent is instructed to run linters, formatters, and tests before committing. The `open_pr_if_needed` middleware acts as a backstop β€” if the agent finishes without opening a PR, the middleware handles it automatically. -### 6. Verify it works - -Comment `@openswe` on any Linear issue. You should see: -- A πŸ‘€ reaction on your comment within a few seconds -- A new run appear in your LangSmith project +This is an area where you can extend Open SWE for your org: add deterministic CI checks, visual verification, or review gates as additional middleware. See the [Customization Guide](CUSTOMIZATION.md#6-middleware) for how. --- -## Usage +## Comparison -Open SWE can be used in multiple ways: +| Decision | Open SWE | Stripe (Minions) | Ramp (Inspect) | Coinbase (Cloudbot) | +|---|---|---|---|---| +| **Harness** | Composed (Deep Agents/LangGraph) | Forked (Goose) | Composed (OpenCode) | Built from scratch | +| **Sandbox** | Pluggable (Modal, Daytona, Runloop, etc.) | AWS EC2 devboxes (pre-warmed) | Modal containers (pre-warmed) | In-house | +| **Tools** | ~15, curated | ~500, curated per-agent | OpenCode SDK + extensions | MCPs + custom Skills | +| **Context** | AGENTS.md + issue/thread | Rule files + pre-hydration | OpenCode built-in | Linear-first + MCPs | +| **Orchestration** | Subagents + middleware | Blueprints (deterministic + agentic) | Sessions + child sessions | Three modes | +| **Invocation** | Slack, Linear, GitHub | Slack + embedded buttons | Slack + web + Chrome extension | Slack-native | +| **Validation** | Prompt-driven + PR safety net | 3-layer (local + CI + 1 retry) | Visual DOM verification | Agent councils + auto-merge | -- πŸ“‹ **From Linear**. Mention `@openswe` in a comment on any Linear issue to trigger the agent. It will automatically read the issue description and full context, then autonomously start working on it. You can also include additional instructions in the comment if needed (e.g. `@openswe focus on the auth module`). -- πŸ™ **GitHub (for Open SWE-generated PRs)**. In PRs which Open SWE has created, you can tag it in comments or reviews via `@openswe` to have it resolve reviews automatically for you. Tagging `@openswe` on an Open SWE generated PR will create a new run passing all of the comments from the PR as the prompt. Any changes will be directly committed back to the same branch. \ No newline at end of file +--- + +## Features + +- **Trigger from Linear, Slack, or GitHub** β€” mention `@openswe` in a comment to kick off a task +- **Instant acknowledgement** β€” reacts with πŸ‘€ the moment it picks up your message +- **Message it while it's running** β€” send follow-up messages mid-task and it'll pick them up before its next step +- **Run multiple tasks in parallel** β€” each task runs in its own isolated cloud sandbox +- **GitHub OAuth built-in** β€” authenticates with your GitHub account automatically +- **Opens PRs automatically** β€” commits changes and opens a draft PR when done, linked back to your ticket +- **Subagent support** β€” the agent can spawn child agents for parallel subtasks + +--- + +## Getting Started + +- **[Installation Guide](INSTALLATION.md)** β€” GitHub App creation, LangSmith, Linear/Slack/GitHub triggers, and production deployment +- **[Customization Guide](CUSTOMIZATION.md)** β€” swap the sandbox, model, tools, triggers, system prompt, and middleware for your org + +## License + +MIT