From 1d19c05b7ef31a59c121815d20ab4063e58ebd45 Mon Sep 17 00:00:00 2001 From: aran-yogesh Date: Fri, 6 Mar 2026 14:23:29 -0800 Subject: [PATCH 1/6] chore: readme update --- README.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 105 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index e7988c48..b1e4ea99 100644 --- a/README.md +++ b/README.md @@ -10,39 +10,126 @@

Open SWE - An Open-Source Asynchronous Coding Agent

-> [!WARNING] -> **⚠️ DEPRECATION NOTICE** -> -> This repository is no longer actively maintained and will not receive further updates. The project has been deprecated and users are advised to seek alternative solutions for their coding agent needs. - 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. -> [!TIP] -> Try out Open SWE yourself using our [public demo](https://swe.langchain.com)! > > **Note: you're required to set your own LLM API keys to use the demo.** > [!NOTE] -> πŸ“š See the **Open SWE documentation files [here](https://github.com/langchain-ai/open-swe/tree/main/apps/docs)** -> > πŸ’¬ Read the **announcement blog post [here](https://blog.langchain.com/introducing-open-swe-an-open-source-asynchronous-coding-agent/)** -> -> πŸ“Ί Watch the **announcement video [here](https://youtu.be/TaYVvXbOs8c)** # Features ![UI Screenshot](./static/ui-screenshot.png) -- πŸ“ **Planning**: Open SWE has a dedicated planning step which allows it to deeply understand complex codebases and nuanced tasks. You're also given the ability to accept, edit, or reject the proposed plan before it's executed. -- 🀝 **Human in the loop**: With Open SWE, you can send it messages while it's running (both during the planning and execution steps). This allows for giving real time feedback and instructions without having to interrupt the process. -- πŸƒ **Parallel Execution**: You can run as many Open SWE tasks as you want in parallel! Since it runs in a sandbox environment in the cloud, you're not limited by the number of tasks you can run at once. -- πŸ§‘β€πŸ’» **End to end task management**: Open SWE will automatically create GitHub issues for tasks, and create pull requests which will close the issue when implementation is complete. +- πŸ”— **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 +## Installation + +### Prerequisites + +- 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 +``` + +### 2. Install dependencies + +```bash +uv sync +``` + +### 3. Set environment variables + +Create a `.env` file in `apps/agent/` with the following: + +```bash +# LangSmith +LANGSMITH_API_KEY_PROD="" # Your LangSmith API key +LANGSMITH_ENDPOINT="https://api.smith.langchain.com" +LANGSMITH_HOST_API_URL="https://api.host.langchain.com" +LANGCHAIN_TRACING_V2="true" +LANGCHAIN_PROJECT="" + +# LLM +ANTHROPIC_API_KEY="" # Anthropic API key (recommended default provider) + +# GitHub OAuth (via LangSmith agent auth) +GITHUB_OAUTH_PROVIDER_ID="" # GitHub OAuth provider ID from LangSmith +X_SERVICE_AUTH_JWT_SECRET="" # Secret for service JWT tokens + +# 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 + +# GitHub Webhook +GITHUB_WEBHOOK_SECRET="" # Secret for verifying GitHub webhooks + +# Linear +LINEAR_API_KEY="" # Linear API key +LINEAR_WEBHOOK_SECRET="" # Secret for verifying Linear webhooks + +# Slack (optional) +SLACK_BOT_TOKEN="" +SLACK_BOT_USER_ID="" +SLACK_BOT_USERNAME="" +SLACK_SIGNING_SECRET="" + +# Sandbox +DEFAULT_SANDBOX_TEMPLATE_NAME="" # LangSmith sandbox template name (uses default if not set) + +# Token encryption +TOKEN_ENCRYPTION_KEY="" # 32-byte url-safe base64 key for encrypting GitHub tokens +``` + +### 4. Run the agent + +In one terminal, start the LangGraph dev server: + +```bash +uv run langgraph dev +``` + +In a second terminal, start the webhook server: + +```bash +make run +``` + +### 5. Expose webhooks with ngrok + +In a third terminal, expose the webhook server so Linear/GitHub/Slack can reach it: + +```bash +ngrok http 8000 +``` + +Use the ngrok HTTPS URL as your webhook endpoint when configuring Linear, GitHub, and Slack integrations (e.g. `https://xxxx.ngrok.io/webhooks/linear`). + +The LangGraph server runs on `http://localhost:2024` and the webhook server on `http://localhost:8000`. + +--- + ## Usage Open SWE can be used in multiple ways: -- πŸ–₯️ **From the UI**. You can create, manage and execute Open SWE tasks from the [web application](https://swe.langchain.com). -- πŸ“ **From GitHub**. You can start Open SWE tasks directly from GitHub issues simply by adding a label `open-swe`, or `open-swe-auto` (adding `-auto` will cause Open SWE to automatically accept the plan, requiring no intervention from you). The default `open-swe` labels now use Claude Opus 4.5 for optimal performance. Note: `open-swe-max` and `open-swe-max-auto` labels are deprecated and should no longer be used. - +- πŸ“‹ **From Linear**. Mention `@openswe` in a comment on any Linear issue and describe the task you want it to perform (e.g. `@openswe fix the login bug described above`). The agent will pick up the issue context along with your instructions and start working on it. +- πŸ™ **GitHub (for Open SWE-generated PRs)**. Once Open SWE completes implementation, it pushes changes to a branch `open-swe/` and opens a **draft pull request** linking back to the originating Linear issue. From there, you can review the code, request changes, and merge when ready. \ No newline at end of file From a6d05a86b22f94e4b8e0f355f2727f6030eb57ab Mon Sep 17 00:00:00 2001 From: aran-yogesh Date: Fri, 6 Mar 2026 14:36:26 -0800 Subject: [PATCH 2/6] lineaer webhook update instructions --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/README.md b/README.md index b1e4ea99..0e7f1cdd 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,47 @@ The LangGraph server runs on `http://localhost:2024` and the webhook server on ` --- +## Setting up the Linear Webhook + +### 1. Get your webhook URL + +Start ngrok and copy the HTTPS URL: + +```bash +ngrok http 8000 +# e.g. https://xxxx.ngrok.io +``` + +Your Linear webhook URL will be: `https://xxxx.ngrok.io/webhooks/linear` + +### 2. Create the webhook in Linear + +1. Go to **Linear** β†’ **Settings** β†’ **API** β†’ **Webhooks** +2. Click **New webhook** +3. Fill in the form: + - **Label**: `open-swe` + - **URL**: `https://xxxx.ngrok.io/webhooks/linear` + - **Secret**: generate a random string and copy it β€” this goes in `LINEAR_WEBHOOK_SECRET` in your `.env` +4. Under **Data change events**, enable: + - **Comments** β†’ `Create` +5. Click **Create webhook** + +### 3. Set the Linear API key + +Open SWE uses `LINEAR_API_KEY` to fetch full issue details (description, project, team) and to post comments back. To get it: + +1. Go to **Linear** β†’ **Settings** β†’ **API** β†’ **Personal API keys** +2. Click **New API key**, name it `open-swe` +3. Copy the key into `LINEAR_API_KEY` in your `.env` + +### 4. Verify it works + +Comment `@openswe` on any Linear issue. You should see: +- A πŸ‘€ reaction appear on your comment within a few seconds +- A new run appear in your LangSmith project + +--- + ## Usage Open SWE can be used in multiple ways: From 75bc943ac524d21910cac66012d85826d6757fc5 Mon Sep 17 00:00:00 2001 From: aran-yogesh Date: Fri, 6 Mar 2026 14:47:05 -0800 Subject: [PATCH 3/6] order update instructions --- README.md | 83 +++++++++++++++++++++---------------------------------- 1 file changed, 31 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 0e7f1cdd..57c0202b 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,31 @@ cd open-swe/apps/agent uv sync ``` -### 3. Set environment variables +### 3. Set up the Linear webhook + +In a terminal, start ngrok to get your public URL: + +```bash +ngrok http 8000 +# e.g. https://xxxx.ngrok.io +``` + +Then in Linear: + +1. Go to **Settings** β†’ **API** β†’ **Webhooks** β†’ **New webhook** +2. Fill in: + - **Label**: `open-swe` + - **URL**: `https://xxxx.ngrok.io/webhooks/linear` + - **Secret**: generate a random string β€” copy it, you'll need it for `LINEAR_WEBHOOK_SECRET` +3. Under **Data change events**, enable **Comments** β†’ `Create` only +4. Click **Create webhook** + +To get your `LINEAR_API_KEY`: + +1. Go to **Settings** β†’ **API** β†’ **Personal API keys** β†’ **New API key** +2. Name it `open-swe` and copy the key + +### 4. Set environment variables Create a `.env` file in `apps/agent/` with the following: @@ -83,8 +107,8 @@ GITHUB_APP_INSTALLATION_ID="" # GitHub App installation ID GITHUB_WEBHOOK_SECRET="" # Secret for verifying GitHub webhooks # Linear -LINEAR_API_KEY="" # Linear API key -LINEAR_WEBHOOK_SECRET="" # Secret for verifying Linear webhooks +LINEAR_API_KEY="" # Linear API key (from step 3) +LINEAR_WEBHOOK_SECRET="" # Secret you set when creating the webhook (from step 3) # Slack (optional) SLACK_BOT_TOKEN="" @@ -99,12 +123,12 @@ DEFAULT_SANDBOX_TEMPLATE_NAME="" # LangSmith sandbox template name (uses defa TOKEN_ENCRYPTION_KEY="" # 32-byte url-safe base64 key for encrypting GitHub tokens ``` -### 4. Run the agent +### 5. Run the agent In one terminal, start the LangGraph dev server: ```bash -uv run langgraph dev +uv run langgraph dev --no-browser ``` In a second terminal, start the webhook server: @@ -113,57 +137,12 @@ In a second terminal, start the webhook server: make run ``` -### 5. Expose webhooks with ngrok - -In a third terminal, expose the webhook server so Linear/GitHub/Slack can reach it: - -```bash -ngrok http 8000 -``` - -Use the ngrok HTTPS URL as your webhook endpoint when configuring Linear, GitHub, and Slack integrations (e.g. `https://xxxx.ngrok.io/webhooks/linear`). - The LangGraph server runs on `http://localhost:2024` and the webhook server on `http://localhost:8000`. ---- - -## Setting up the Linear Webhook - -### 1. Get your webhook URL - -Start ngrok and copy the HTTPS URL: - -```bash -ngrok http 8000 -# e.g. https://xxxx.ngrok.io -``` - -Your Linear webhook URL will be: `https://xxxx.ngrok.io/webhooks/linear` - -### 2. Create the webhook in Linear - -1. Go to **Linear** β†’ **Settings** β†’ **API** β†’ **Webhooks** -2. Click **New webhook** -3. Fill in the form: - - **Label**: `open-swe` - - **URL**: `https://xxxx.ngrok.io/webhooks/linear` - - **Secret**: generate a random string and copy it β€” this goes in `LINEAR_WEBHOOK_SECRET` in your `.env` -4. Under **Data change events**, enable: - - **Comments** β†’ `Create` -5. Click **Create webhook** - -### 3. Set the Linear API key - -Open SWE uses `LINEAR_API_KEY` to fetch full issue details (description, project, team) and to post comments back. To get it: - -1. Go to **Linear** β†’ **Settings** β†’ **API** β†’ **Personal API keys** -2. Click **New API key**, name it `open-swe` -3. Copy the key into `LINEAR_API_KEY` in your `.env` - -### 4. Verify it works +### 6. Verify it works Comment `@openswe` on any Linear issue. You should see: -- A πŸ‘€ reaction appear on your comment within a few seconds +- A πŸ‘€ reaction on your comment within a few seconds - A new run appear in your LangSmith project --- From 86ea40e04f277aa073fbbb6ddce39121d10382f2 Mon Sep 17 00:00:00 2001 From: Aran Yogesh Date: Fri, 6 Mar 2026 14:56:12 -0800 Subject: [PATCH 4/6] Update README.md Co-authored-by: Brace Sproul --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 57c0202b..822de21e 100644 --- a/README.md +++ b/README.md @@ -83,8 +83,6 @@ Create a `.env` file in `apps/agent/` with the following: ```bash # LangSmith LANGSMITH_API_KEY_PROD="" # Your LangSmith API key -LANGSMITH_ENDPOINT="https://api.smith.langchain.com" -LANGSMITH_HOST_API_URL="https://api.host.langchain.com" LANGCHAIN_TRACING_V2="true" LANGCHAIN_PROJECT="" From 229cc08713b92fff3b0f4d669fa373e0f991ab8e Mon Sep 17 00:00:00 2001 From: aran-yogesh Date: Fri, 6 Mar 2026 15:05:42 -0800 Subject: [PATCH 5/6] readme update --- README.md | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 822de21e..5896fc43 100644 --- a/README.md +++ b/README.md @@ -57,8 +57,9 @@ uv sync In a terminal, start ngrok to get your public URL: ```bash -ngrok http 8000 +ngrok http 2024 # e.g. https://xxxx.ngrok.io + ``` Then in Linear: @@ -89,10 +90,6 @@ LANGCHAIN_PROJECT="" # LLM ANTHROPIC_API_KEY="" # Anthropic API key (recommended default provider) -# GitHub OAuth (via LangSmith agent auth) -GITHUB_OAUTH_PROVIDER_ID="" # GitHub OAuth provider ID from LangSmith -X_SERVICE_AUTH_JWT_SECRET="" # Secret for service JWT tokens - # GitHub App (Bot) GITHUB_APP_ID="" # GitHub App ID GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- @@ -118,24 +115,17 @@ SLACK_SIGNING_SECRET="" DEFAULT_SANDBOX_TEMPLATE_NAME="" # LangSmith sandbox template name (uses default if not set) # Token encryption -TOKEN_ENCRYPTION_KEY="" # 32-byte url-safe base64 key for encrypting GitHub tokens +# Generate with: openssl rand -base64 32 +TOKEN_ENCRYPTION_KEY="" ``` ### 5. Run the agent -In one terminal, start the LangGraph dev server: - ```bash uv run langgraph dev --no-browser ``` -In a second terminal, start the webhook server: - -```bash -make run -``` - -The LangGraph server runs on `http://localhost:2024` and the webhook server on `http://localhost:8000`. +The LangGraph server runs on `http://localhost:2024` and serves the webhook endpoints automatically. ### 6. Verify it works @@ -149,5 +139,5 @@ Comment `@openswe` on any Linear issue. You should see: Open SWE can be used in multiple ways: -- πŸ“‹ **From Linear**. Mention `@openswe` in a comment on any Linear issue and describe the task you want it to perform (e.g. `@openswe fix the login bug described above`). The agent will pick up the issue context along with your instructions and start working on it. -- πŸ™ **GitHub (for Open SWE-generated PRs)**. Once Open SWE completes implementation, it pushes changes to a branch `open-swe/` and opens a **draft pull request** linking back to the originating Linear issue. From there, you can review the code, request changes, and merge when ready. \ No newline at end of file +- πŸ“‹ **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 From abd26fbbafc8368c3346e087de408a95c2d0feef Mon Sep 17 00:00:00 2001 From: aran-yogesh Date: Fri, 6 Mar 2026 15:21:38 -0800 Subject: [PATCH 6/6] readme updates --- README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5896fc43..0f9d6e2c 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,6 @@ Open SWE is an open-source cloud-based asynchronous coding agent built with [Lan # Features -![UI Screenshot](./static/ui-screenshot.png) - - πŸ”— **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 @@ -68,14 +66,14 @@ Then in Linear: 2. Fill in: - **Label**: `open-swe` - **URL**: `https://xxxx.ngrok.io/webhooks/linear` - - **Secret**: generate a random string β€” copy it, you'll need it for `LINEAR_WEBHOOK_SECRET` + - **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** -To get your `LINEAR_API_KEY`: +To get your `LINEAR_API_KEY` (set this under `LINEAR_API_KEY` in `.env`): 1. Go to **Settings** β†’ **API** β†’ **Personal API keys** β†’ **New API key** -2. Name it `open-swe` and copy the key +2. Name it `open-swe`, select **All access**, and copy the key ### 4. Set environment variables @@ -99,7 +97,8 @@ GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- GITHUB_APP_INSTALLATION_ID="" # GitHub App installation ID # GitHub Webhook -GITHUB_WEBHOOK_SECRET="" # Secret for verifying GitHub webhooks +# Generate with: openssl rand -hex 32 +GITHUB_WEBHOOK_SECRET="" # Linear LINEAR_API_KEY="" # Linear API key (from step 3)