diff --git a/README.md b/README.md index 98a40fe1..32a91ccc 100644 --- a/README.md +++ b/README.md @@ -1,159 +1,39 @@ -# Open SWE +
+ + + + Open SWE Logo + +
+ +Open SWE is an open-source cloud based coding agent. It's built with [LangGraph](https://langchain-ai.github.io/langgraphjs/), and is designed to autonomously understand, plan, and execute code changes across entire repositories. + +Think of Open SWE as your own personal engineer who can handle complex tasks end to end, from planning to execution, to opening a pull request. > [!WARNING] > Open SWE is under active development and is not yet ready for production use. -Open SWE is an open-source cloud based coding agent. +> [!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.** + +![UI Screenshot](./static/ui-screenshot.png) + +# Features + +- 📝 **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. ## Usage -First, clone the repository: +Open SWE can be used in multiple ways: -```bash -git clone https://github.com/langchain-ai/open-swe.git -cd open-swe -``` +- 🖥️ **From the UI**. You can create, manage and execute Open SWE tasks from the [web application](https://swe.langchain.com). See the ['From the UI' page](https://docs.langchain.com/labs/swe/usage/ui) in the docs for more information. +- 📝 **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). See the ['From GitHub' page](https://docs.langchain.com/labs/swe/usage/github) in the docs for more information. -Next, install dependencies: +# Documentation -```bash -yarn install -``` - -Copy the `.env.example` files to `.env` in their respective packages, and fill in the values: - -```bash -# Agent .env file -cp ./apps/open-swe/.env.example ./apps/open-swe/.env -# Web .env file -cp ./apps/web/.env.example ./apps/web/.env -``` - -The open-swe `.env` file should contain the following variables: - -```bash -# ------------------LangSmith tracing------------------ -LANGCHAIN_PROJECT="default" -LANGCHAIN_API_KEY="" -LANGCHAIN_TRACING_V2=true -# ----------------------------------------------------- - -# Defaults to Anthropic models, OpenAI & Google keys are optional, unless using those models -ANTHROPIC_API_KEY="" -OPENAI_API_KEY="" -GOOGLE_API_KEY="" - -# Daytona API key for accessing and modifying the code in the cloud sandbox. -DAYTONA_API_KEY="" - -# Encryption key for secrets (32-byte hex string for AES-256) -# Should be the same value as the one used in the web app. -# Can be generated via: `openssl rand -hex 32` -SECRETS_ENCRYPTION_KEY="" -# Used for setting the git user name & email for commits. -GITHUB_APP_NAME="open-swe-dev" - -# Defaults to 2024 if not set. -# LGP will automatically set this for you in production. -# PORT="2024" -``` - -And the web `.env` file should contain the following variables: - -```bash -# Change both to production URLs when deployed -NEXT_PUBLIC_API_URL="http://localhost:3000/api" -LANGGRAPH_API_URL="http://localhost:2024" -NEXT_PUBLIC_ASSISTANT_ID="open-swe" - -# For the GitHub OAuth flow -GITHUB_APP_CLIENT_ID="" -GITHUB_APP_CLIENT_SECRET="" -GITHUB_APP_REDIRECT_URI="http://localhost:3000/api/auth/github/callback" - -GITHUB_APP_NAME="open-swe-dev" -GITHUB_APP_ID="" -GITHUB_APP_PRIVATE_KEY="" - -# Encryption key for secrets (32-byte hex string for AES-256) -# Should be the same value as the one used in the open-swe app. -# Can be generated via: `openssl rand -hex 32` -SECRETS_ENCRYPTION_KEY="" -``` - -**REMINDER**: The `SECRETS_ENCRYPTION_KEY` environment variable must be the same in both the web and open-swe apps. - -To get the GitHub App secrets, first create a new GitHub app (note: this is not the same as the OAuth app) in [the developer settings](https://github.com/settings/apps/new). - -Give the app a name and description. - -Under `Callback URL`, set it to: `http://localhost:3000/api/auth/github/callback` for local development. Then, uncheck `Expire user authorization tokens`, and check `Request user authorization (OAuth) during installation`. - -Under `Post installation`, check `Redirect on update`. - -Under `Webhook`, uncheck `Active`. - -Under `Repository permissions`, give the app the following permissions: - -- `Contents` - `Read & Write` -- `Metadata` - `Read & Write` -- `Pull requests` - `Read & Write` -- `Issues` - `Read & Write` - -Finally, under `Where can this GitHub App be installed?` ensure `Any account` is selected. - -After creating the app, you will be taken to the app's settings page. Copy/generate the following fields for your environment variables: - -`App ID` - `GITHUB_APP_ID` -`Client ID` - `GITHUB_APP_CLIENT_ID` -`Client secrets` - Generate a new secret key, and set it under `GITHUB_APP_CLIENT_SECRET` -Scroll down to `Private keys`, and generate a new private key. This will download a file. Set the contents of this file under `GITHUB_APP_PRIVATE_KEY`. -Set `GITHUB_APP_REDIRECT_URI` to `http://localhost:3000/api/auth/github/callback` for local development. -Set `GITHUB_APP_NAME` to the name of your app. - -That's it! You can now authenticate users with GitHub, and generate tokens for them. - -## Running the graph - -> [!INFO] -> Since Open SWE is still under development, the following requires hard coding the repository information. This will be changed before the release. - -To run the graph, first you must set which repository you want Open SWE to make changes to inside the `web` package. To do this, search for instances of `repo: "open-swe",` inside the `apps/web` directory. This should yield _7_ results in _5_ files. Go through each of these, and modify the `owner` and `repo` properties to match the repository you want Open SWE to make changes to. (ensure your GitHub PAT has access to this repository). - -After updating these values, you should start the web server: - -```bash -# Inside `apps/web` -yarn dev -``` - -And the agent server: - -```bash -# Inside `apps/open-swe` -yarn dev -``` - -You can now open the web app at `http://localhost:3000` and send a request. - -Sending a request will trigger the agent, which first enters the planning subgraph. This will run for just under a minute, and once it's finished, it'll interrupt the graph with the proposed plan. - -To start the agent execution flow, you can: -- accept the plan as is -- edit & submit the plan - -Both of these actions will trigger the agent to start the execution flow with the plan. - -If you are not happy with the plan, you can also send a response. This will cause the agent to rewrite the plan according to the instructions you provided. - -> [!TIP] -> Responding to the plan interrupt will not trigger the agent to re-enter the planning subgraph, so it will not be able to gather more information than it already has. If you want the agent to start over and gather new context, you must create a new chat and send an updated prompt. - -Once you've accepted the plan, it will begin the execution flow. When the agent finishes, a pull request will automatically be opened in the repository. - -> [!NOTE] -> The chat UI is very buggy at the moment, so I recommend also having the agent server terminal window open so you can inspect the logs as the agent runs. - -## Accessing Changes - -Open SWE will automatically create a branch whenever you create a new thread with a naming format of `open-swe/`. Every time a file is created, modified, or deleted, the changes will be committed to this branch. You can access the changes in the repository by checking out this branch. +To get started using Open SWE locally, see the [documentation here](https://docs.langchain.com/labs/swe/). diff --git a/apps/docs/.prettierrc b/apps/docs/.prettierrc new file mode 100644 index 00000000..222861c3 --- /dev/null +++ b/apps/docs/.prettierrc @@ -0,0 +1,4 @@ +{ + "tabWidth": 2, + "useTabs": false +} diff --git a/apps/docs/README.md b/apps/docs/README.md index 65a9111e..4de37a5b 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -1,6 +1,6 @@ -# Open Agent Platform Docs +# Open SWE Docs -The OAP docs are built with Mintlify. To preview the docs locally, run the following command: +The Open SWE docs are built with Mintlify. To preview the docs locally, run the following command: ```bash npx mintlify dev diff --git a/apps/docs/docs.json b/apps/docs/docs.json index d1edf64d..fc99c1ad 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -15,17 +15,11 @@ "groups": [ { "group": "Get Started", - "pages": [ - "index" - ] + "pages": ["index"] }, { "group": "Usage", - "pages": [ - "usage/intro", - "usage/ui", - "usage/webhook" - ] + "pages": ["usage/intro", "usage/ui", "usage/github"] }, { "group": "Development Setup", @@ -72,4 +66,4 @@ "twitter": "https://twitter.com/langchainai" } } -} \ No newline at end of file +} diff --git a/apps/docs/index.mdx b/apps/docs/index.mdx index 9db3f1b0..cff9d555 100644 --- a/apps/docs/index.mdx +++ b/apps/docs/index.mdx @@ -1,44 +1,33 @@ --- -title: 'Introduction' -description: 'An introduction to Open SWE' +title: "Introduction" +description: "An introduction to Open SWE" --- Open SWE is an open-source cloud-based coding agent built with [LangGraph](https://langchain-ai.github.io/langgraphjs/). It's designed to autonomously understand, plan, and execute code changes across entire repositories. -Open SWE is currently under active development and is not yet ready for production use. + Open SWE is currently under active development and is not yet ready for + production use. ## How It Works Open SWE operates through three specialized LangGraph agents: + - **Manager Graph**: Orchestrates user interactions and coordinates between other graphs - **Planner Graph**: Analyzes requirements and creates detailed execution plans - **Programmer Graph**: Executes code changes based on approved plans The agent can be used through a web interface or triggered automatically via GitHub webhooks, making it flexible for both interactive development and automated workflows. - - + Concepts - + How to set up Open SWE for development - + Open SWE features, and how to use them @@ -52,6 +41,5 @@ This documentation covers everything you need to know about Open SWE: - **Setup**: Complete development environment setup including monorepo structure, dependencies, and authentication -Try out the [live demo](https://swe.langchain.com) to see Open SWE in action. + Try out the [live demo](https://swe.langchain.com) to see Open SWE in action. - diff --git a/apps/docs/package.json b/apps/docs/package.json index abbab301..e81e3c79 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -4,9 +4,12 @@ "repository": "https://github.com/langchain-ai/open-swe", "private": true, "scripts": { - "dev": "mint dev" + "dev": "mint dev", + "format": "prettier --write .", + "format:check": "prettier --check ." }, "devDependencies": { - "mint": "^4.2.12" + "mint": "^4.2.12", + "prettier": "^3.5.2" } } diff --git a/apps/docs/setup/authentication.mdx b/apps/docs/setup/authentication.mdx index cf42d947..c4353966 100644 --- a/apps/docs/setup/authentication.mdx +++ b/apps/docs/setup/authentication.mdx @@ -1,6 +1,6 @@ --- -title: 'Authentication' -description: 'How authentication works in Open SWE' +title: "Authentication" +description: "How authentication works in Open SWE" --- Open SWE implements a comprehensive authentication system that secures both client-side interactions and server-side operations. The authentication flow involves GitHub OAuth for user authentication, encrypted token handling, and multi-layered security for LangGraph server requests. @@ -16,7 +16,9 @@ Open SWE uses GitHub OAuth for client-side authentication, providing secure acce - **Settings management** is available at `/settings` for updating GitHub authentication -GitHub OAuth provides the foundation for all user interactions, enabling Open SWE to access repositories and perform actions on behalf of authenticated users. + GitHub OAuth provides the foundation for all user interactions, enabling Open + SWE to access repositories and perform actions on behalf of authenticated + users. ## LangGraph Server Authentication @@ -28,7 +30,9 @@ All requests to the LangGraph server are authenticated through a sophisticated p The Next.js application includes a proxy route (`apps/web/src/app/api/[..._path]/route.ts`) that acts as an intermediary for all LangGraph server requests. This proxy uses the [`langgraph-nextjs-api-passthrough`](https://www.npmjs.com/package/langgraph-nextjs-api-passthrough) package to handle request forwarding with enhanced security. -The proxy route ensures that sensitive authentication tokens never reach the client directly, maintaining security while enabling seamless communication with the LangGraph server. + The proxy route ensures that sensitive authentication tokens never reach the + client directly, maintaining security while enabling seamless communication + with the LangGraph server. ### Header Injection System @@ -42,23 +46,28 @@ The proxy route automatically injects the following encrypted headers into each - **`x-github-installation-name`** - Installation name (username or organization name) -All headers are prefixed with `x-` to ensure they're included in LangGraph run configurations, making them accessible during execution while maintaining security through encryption. + All headers are prefixed with `x-` to ensure they're included in LangGraph run + configurations, making them accessible during execution while maintaining + security through encryption. ### Token Encryption Open SWE implements AES-256-GCM encryption for all secrets passed to the LangGraph server to prevent exposure in: + - LangSmith trace metadata - Run configurations - Potential unauthorized access scenarios The encryption process uses the `SECRETS_ENCRYPTION_KEY` environment variable and includes: + - **Initialization Vector (IV)** for unique encryption per token - **Authentication Tag** for data integrity verification - **Base64 encoding** for safe transport -The same encryption key must be configured in both the web application and LangGraph agent for proper token decryption. + The same encryption key must be configured in both the web application and + LangGraph agent for proper token decryption. ## Authentication Middleware @@ -74,7 +83,8 @@ The middleware first checks for GitHub webhook requests by detecting the `X-Hub- 3. **Separate user verification** in subsequent run creation requests -Webhook authentication is handled separately from user authentication to enable automated GitHub issue processing while maintaining security. + Webhook authentication is handled separately from user authentication to + enable automated GitHub issue processing while maintaining security. ### Standard Request Authentication @@ -82,6 +92,7 @@ Webhook authentication is handled separately from user authentication to enable For non-webhook requests, the middleware validates: #### Required Headers + - **Installation name** (`x-github-installation-name`) - **Installation token** (`x-github-installation-token`) @@ -92,11 +103,13 @@ Missing either header results in a 401 Unauthorized error. The middleware supports two authentication paths: **Web Application Requests:** + - Uses encrypted GitHub access token (`x-github-access-token`) - Verifies user identity through GitHub API - Extracts user ID and login from token **Webhook-Generated Requests:** + - Uses explicit user headers (`x-github-user-id`, `x-github-user-login`) - Validates user ID and login against installation token - Ensures webhook-created runs are properly attributed @@ -104,13 +117,15 @@ The middleware supports two authentication paths: ### Identity and Permissions Upon successful authentication, the middleware returns an identity object containing: + - **User ID** for resource ownership verification - **Display name** (GitHub login) - **Installation name** for repository context - **Comprehensive permissions** for LangGraph operations -The user ID serves as the primary identifier for resource access control, ensuring users can only access their own threads, runs, and assistants. + The user ID serves as the primary identifier for resource access control, + ensuring users can only access their own threads, runs, and assistants. ## Resource Access Control @@ -118,6 +133,7 @@ The user ID serves as the primary identifier for resource access control, ensuri Open SWE implements fine-grained access control for all LangGraph resources: ### Metadata-Based Ownership + - **Create operations** automatically add user ID to resource metadata - **Read/Update/Delete operations** verify user ID matches resource owner - **Search operations** filter results by user ownership @@ -131,9 +147,11 @@ During LangGraph run execution, encrypted tokens are accessible through the run' 3. **Action execution** (creating issues, making commits, etc.) -This design ensures tokens remain encrypted in storage and traces while being available for necessary GitHub operations during run execution. + This design ensures tokens remain encrypted in storage and traces while being + available for necessary GitHub operations during run execution. -Always ensure the `SECRETS_ENCRYPTION_KEY` environment variable is identical between your web application and LangGraph agent deployments. + Always ensure the `SECRETS_ENCRYPTION_KEY` environment variable is identical + between your web application and LangGraph agent deployments. diff --git a/apps/docs/setup/development.mdx b/apps/docs/setup/development.mdx index 5857d855..c1e2ae9a 100644 --- a/apps/docs/setup/development.mdx +++ b/apps/docs/setup/development.mdx @@ -1,17 +1,19 @@ --- -title: 'Development Setup' -description: 'How to set up Open SWE for development' +title: "Development Setup" +description: "How to set up Open SWE for development" --- This guide will walk you through setting up Open SWE for local development. You'll need to clone the repository, install dependencies, configure environment variables, create a GitHub App, and start the development servers. -This setup is for development purposes. For production deployment, you'll need to adjust URLs and create separate GitHub Apps for production use. + This setup is for development purposes. For production deployment, you'll need + to adjust URLs and create separate GitHub Apps for production use. ## Prerequisites Before starting, ensure you have the following installed: + - Node.js (version 18 or higher) - Yarn (version 3.5.1 or higher) - Git @@ -28,6 +30,7 @@ Before starting, ensure you have the following installed: ```bash cd open-swe ``` + @@ -38,6 +41,7 @@ Before starting, ensure you have the following installed: ``` This will install dependencies for all packages in the monorepo workspace. + @@ -61,10 +65,10 @@ Before starting, ensure you have the following installed: NEXT_PUBLIC_GITHUB_APP_CLIENT_ID="" GITHUB_APP_CLIENT_SECRET="" GITHUB_APP_REDIRECT_URI="http://localhost:3000/api/auth/github/callback" - + # Encryption key for secrets (generate with: openssl rand -hex 32) SECRETS_ENCRYPTION_KEY="" - + # GitHub App details (will be filled after creating GitHub App) GITHUB_APP_NAME="open-swe-dev" GITHUB_APP_ID="" @@ -72,7 +76,7 @@ Before starting, ensure you have the following installed: ...add your private key here... -----END RSA PRIVATE KEY----- " - + # API URLs for development NEXT_PUBLIC_API_URL="http://localhost:3000/api" LANGGRAPH_API_URL="http://localhost:2024" @@ -88,18 +92,18 @@ Before starting, ensure you have the following installed: LANGCHAIN_API_KEY="lsv2_pt_..." # Get from LangSmith LANGCHAIN_TRACING_V2="true" LANGCHAIN_TEST_TRACKING="false" - + # LLM Provider Keys (at least one required) ANTHROPIC_API_KEY="" # Recommended - default provider OPENAI_API_KEY="" # Optional GOOGLE_API_KEY="" # Optional - + # Infrastructure DAYTONA_API_KEY="" # Required. For cloud sandboxes - + # Tools FIRECRAWL_API_KEY="" # For URL content extraction - + # GitHub App settings (same as web app) GITHUB_APP_NAME="open-swe-dev" GITHUB_APP_ID="" @@ -108,7 +112,7 @@ Before starting, ensure you have the following installed: -----END RSA PRIVATE KEY----- " GITHUB_WEBHOOK_SECRET="" # Will be generated in next step - + # Server configuration PORT="2024" OPEN_SWE_APP_URL="http://localhost:3000" @@ -118,6 +122,7 @@ Before starting, ensure you have the following installed: Generate the `SECRETS_ENCRYPTION_KEY` using: `openssl rand -hex 32`. This key must be identical in both environment files. + @@ -150,7 +155,7 @@ Before starting, ensure you have the following installed: ngrok http 2024 ``` Use the ngrok URL + `/webhook/github` (e.g., `https://abc123.ngrok.io/webhook/github`) - + 3. **Webhook secret**: Generate and save this value: ```bash openssl rand -hex 32 @@ -161,12 +166,12 @@ Before starting, ensure you have the following installed: **Repository permissions:** - **Contents**: Read & Write - - **Issues**: Read & Write + - **Issues**: Read & Write - **Pull requests**: Read & Write - **Metadata**: Read only (automatically enabled) **Organization permissions:** None - + **Account permissions:** None ### Subscribe to Events @@ -175,7 +180,7 @@ Before starting, ensure you have the following installed: ### Installation Settings - - **Where can this GitHub App be installed?**: + - **Where can this GitHub App be installed?**: - Choose "Any account" for broader testing - Or "Only on this account" to limit to your repositories @@ -190,12 +195,12 @@ Before starting, ensure you have the following installed: - **GITHUB_APP_NAME**: The name you chose - **GITHUB_APP_ID**: Found in the "About" section (e.g., `12345678`) - **NEXT_PUBLIC_GITHUB_APP_CLIENT_ID**: Found in the "About" section - - **GITHUB_APP_CLIENT_SECRET**: + - **GITHUB_APP_CLIENT_SECRET**: 1. Scroll to "Client secrets" section 2. Click "Generate new client secret" 3. Copy the generated value - **GITHUB_APP_PRIVATE_KEY**: - 1. Scroll to "Private keys" section + 1. Scroll to "Private keys" section 2. Click "Generate a private key" 3. Download the `.pem` file and copy its contents 4. Format as a single line with `\\n` for line breaks, or use the multiline format shown in the example @@ -203,6 +208,7 @@ Before starting, ensure you have the following installed: Keep your GitHub App credentials secure and never commit them to version control. The `.env` files are already included in `.gitignore`. + @@ -225,6 +231,7 @@ Before starting, ensure you have the following installed: Both servers need to be running simultaneously for full functionality. The web app communicates with the LangGraph agent through API calls. + @@ -236,7 +243,9 @@ Once both servers are running: 2. **Test GitHub authentication**: Try logging in with your GitHub account -If you encounter issues, check the console logs in both terminal windows for error messages. Common issues include missing environment variables or incorrect GitHub App configuration. + If you encounter issues, check the console logs in both terminal windows for + error messages. Common issues include missing environment variables or + incorrect GitHub App configuration. ## Next Steps diff --git a/apps/docs/setup/intro.mdx b/apps/docs/setup/intro.mdx index 0ce1df6a..a728b2d5 100644 --- a/apps/docs/setup/intro.mdx +++ b/apps/docs/setup/intro.mdx @@ -1,6 +1,6 @@ --- -title: 'Introduction' -description: 'How to set up Open SWE for development' +title: "Introduction" +description: "How to set up Open SWE for development" --- # Development Setup Overview @@ -12,19 +12,13 @@ Welcome to the Open SWE development setup guide. This section will walk you thro The setup process is organized into focused sections to help you get up and running efficiently: - - Complete guide to cloning the repository, installing dependencies, configuring environment variables, and starting the development servers. + + Complete guide to cloning the repository, installing dependencies, + configuring environment variables, and starting the development servers. - - Understanding the authentication flow, GitHub App configuration, and security mechanisms used throughout Open SWE. + + Understanding the authentication flow, GitHub App configuration, and + security mechanisms used throughout Open SWE. @@ -59,13 +53,13 @@ Open SWE is built with modern technologies designed for scalability and develope ## Monorepo Structure -Open SWE uses a Yarn workspace monorepo with three main applications and a shared package for common utilities and types. + Open SWE uses a Yarn workspace monorepo with three main applications and a + shared package for common utilities and types. - **`apps/open-swe`** - LangGraph agent application -- **`apps/web`** - Next.js web interface +- **`apps/web`** - Next.js web interface - **`apps/docs`** - Mintlify documentation site - **`packages/shared`** - Shared utilities, types, and constants The monorepo is orchestrated by Turbo, which handles build dependencies and parallel task execution across packages. - diff --git a/apps/docs/setup/monorepo.mdx b/apps/docs/setup/monorepo.mdx index 785a321f..d886dfe4 100644 --- a/apps/docs/setup/monorepo.mdx +++ b/apps/docs/setup/monorepo.mdx @@ -1,6 +1,6 @@ --- -title: 'Monorepo' -description: 'How the Open SWE monorepo is configured' +title: "Monorepo" +description: "How the Open SWE monorepo is configured" --- Open SWE is organized as a Yarn workspace monorepo with Turbo build orchestration, designed to efficiently manage multiple applications and shared code. This structure enables code reuse, consistent tooling, and streamlined development workflows. @@ -12,17 +12,20 @@ The monorepo is organized into two main directories: ### Applications (`apps/`) **`apps/open-swe`** - LangGraph Agent Application + - Contains the core LangGraph agent implementation with TypeScript - Includes three specialized graphs: manager, planner, and programmer - Handles GitHub webhook integration and LLM interactions -**`apps/web`** - Next.js Web Interface +**`apps/web`** - Next.js Web Interface + - React frontend with Next.js framework - Uses Shadcn UI components (Radix UI) with Tailwind CSS - Provides the user interface for interacting with the LangGraph agent - Includes authentication and proxy routes for secure communication **`apps/docs`** - Mintlify Documentation + - Contains this documentation site built with Mintlify - Provides comprehensive setup and usage guides - Includes API documentation and development resources @@ -30,13 +33,16 @@ The monorepo is organized into two main directories: ### Packages (`packages/`) **`packages/shared`** - Common Utilities Package + - Centralized location for shared types, constants, and utilities - Used by both the agent and web applications - Exports modules via `@open-swe/shared` namespace - Contains crypto utilities, GraphState types, and Open SWE specific modules -The shared package must be built before other packages can import from it. Any code used by both the agent and web app should be placed here to avoid duplication. + The shared package must be built before other packages can import from it. Any + code used by both the agent and web app should be placed here to avoid + duplication. ## Turbo Orchestration @@ -119,7 +125,10 @@ The `apps/open-swe` package includes a critical `postinstall` hook: ``` -This postinstall hook is **required** for LangGraph Platform deployment. Since Open SWE is a monorepo and the agent requires access to built files from the shared package, we must run the build process before starting the LangGraph server. + This postinstall hook is **required** for LangGraph Platform deployment. Since + Open SWE is a monorepo and the agent requires access to built files from the + shared package, we must run the build process before starting the LangGraph + server. ### Why This Matters @@ -129,7 +138,9 @@ This postinstall hook is **required** for LangGraph Platform deployment. Since O 3. **Build Order**: Ensures the shared package is built before the agent attempts to use it -If you encounter import errors related to the shared package during development, run `yarn build` from the root to ensure all packages are properly built and linked. + If you encounter import errors related to the shared package during + development, run `yarn build` from the root to ensure all packages are + properly built and linked. ## Workspace Configuration diff --git a/apps/docs/usage/webhook.mdx b/apps/docs/usage/github.mdx similarity index 82% rename from apps/docs/usage/webhook.mdx rename to apps/docs/usage/github.mdx index e2868d09..20908e81 100644 --- a/apps/docs/usage/webhook.mdx +++ b/apps/docs/usage/github.mdx @@ -1,7 +1,8 @@ --- -title: 'From Webhooks' -description: 'How to use Open SWE from webhooks' +title: "From Github" +description: "How to use Open SWE from Github" --- + # GitHub Webhook Integration Open SWE integrates seamlessly with GitHub through webhooks, allowing you to trigger automated code changes directly from GitHub issues. This provides a streamlined workflow where you can request code changes by simply adding labels to issues in repositories where Open SWE is installed. @@ -15,17 +16,21 @@ Open SWE monitors GitHub issues for specific labels that trigger automated runs. Open SWE supports two types of labels that control how the agent operates: **Manual Mode (`open-swe`)** + - Requires manual approval of the generated plan before code execution - Gives you full control over what changes will be made - Ideal for complex or sensitive changes where you want to review the approach first **Auto Mode (`open-swe-auto`)** + - Automatically approves and executes the generated plan - Provides faster turnaround for straightforward requests - Best for simple changes or when you trust the agent to proceed autonomously -In development environments, the labels are `open-swe-dev` and `open-swe-auto-dev` respectively. The system automatically uses the appropriate labels based on the `NODE_ENV` environment variable. + In development environments, the labels are `open-swe-dev` and + `open-swe-auto-dev` respectively. The system automatically uses the + appropriate labels based on the `NODE_ENV` environment variable. ## Automatic Run Creation @@ -50,7 +55,9 @@ Once a run is created, Open SWE automatically posts a comment on the triggering - **Development metadata** - Run ID and thread ID for debugging (in a collapsible section) -The run link allows you to monitor progress in real-time, view the generated plan, and interact with the agent if needed. You can switch between manual and auto mode even after the run has started. + The run link allows you to monitor progress in real-time, view the generated + plan, and interact with the agent if needed. You can switch between manual and + auto mode even after the run has started. ## User Access Restrictions @@ -58,17 +65,21 @@ The run link allows you to monitor progress in real-time, view the generated pla Open SWE implements strict access controls to ensure security and privacy: ### Issue Creator Access + - **Only the user who created the issue** can access the generated run URL - This prevents unauthorized users from viewing or modifying runs triggered by others - Access is enforced through GitHub authentication and user verification ### Repository Permissions + - Open SWE respects GitHub's repository permissions - Users must have appropriate access to the repository to trigger runs - The GitHub App installation determines which repositories can use Open SWE -If you need to share access to a run with team members, you can do so through the Open SWE web interface after the run is created, or by having team members with repository access create their own issues. + If you need to share access to a run with team members, you can do so through + the Open SWE web interface after the run is created, or by having team members + with repository access create their own issues. ## Pull Request Integration @@ -76,17 +87,21 @@ If you need to share access to a run with team members, you can do so through th When Open SWE successfully completes code changes, it automatically creates pull requests that are linked back to the original issue: ### Automatic PR Creation + - **Generated after plan execution** - PRs are created once the Programmer Graph completes its work - **Linked to triggering issue** - PRs reference the original issue in their description - **Preserves commit history** - All intermediate commits are maintained for transparency ### Issue Resolution + - **Automatic closure** - When the generated PR is merged, GitHub automatically closes the linked issue - **Clear audit trail** - The connection between issue, run, and PR provides complete traceability - **Status updates** - Issue comments track the progress from request to completion -You can review the generated PR before merging, even in auto mode. The auto-accept setting only applies to plan approval, not PR merging, giving you final control over what code enters your repository. + You can review the generated PR before merging, even in auto mode. The + auto-accept setting only applies to plan approval, not PR merging, giving you + final control over what code enters your repository. ## Getting Started diff --git a/apps/docs/usage/intro.mdx b/apps/docs/usage/intro.mdx index a589baeb..e4dcd39d 100644 --- a/apps/docs/usage/intro.mdx +++ b/apps/docs/usage/intro.mdx @@ -1,6 +1,6 @@ --- -title: 'Introduction' -description: 'How to use Open SWE' +title: "Introduction" +description: "How to use Open SWE" --- # Using Open SWE @@ -10,19 +10,13 @@ Open SWE provides two primary ways to interact with the coding agent, each desig ## Usage Methods - - Interactive chat interface with manual and auto modes for direct agent communication + + Interactive chat interface with manual and auto modes for direct agent + communication - - Automated triggers through GitHub issue labels for seamless repository integration + + Automated triggers through GitHub issue labels for seamless repository + integration @@ -30,10 +24,12 @@ Open SWE provides two primary ways to interact with the coding agent, each desig ### Try the Demo -You can explore Open SWE's capabilities using our hosted demo at [swe.langchain.com](https://swe.langchain.com). +You can explore Open SWE's capabilities using our hosted demo at [swe.langchain.com](https://swe.langchain.com). -The demo application requires you to provide your own LLM API keys. For production use or development, we recommend setting up your own instance following our [development setup guide](/setup/development). + The demo application requires you to provide your own LLM API keys. For + production use or development, we recommend setting up your own instance + following our [development setup guide](/setup/development). ### Choose Your Workflow @@ -44,8 +40,9 @@ The demo application requires you to provide your own LLM API keys. For producti ## What's Next? -Start with the [Web Interface guide](/usage/ui) to understand Open SWE's core capabilities, then explore [GitHub Webhooks](/usage/webhook) for automated integration into your development workflow. + Start with the [Web Interface guide](/usage/ui) to understand Open SWE's core + capabilities, then explore [GitHub Webhooks](/usage/webhook) for automated + integration into your development workflow. Both usage methods leverage the same underlying LangGraph agent architecture with specialized graphs for planning, programming, and management, ensuring consistent behavior regardless of how you interact with Open SWE. - diff --git a/apps/docs/usage/ui.mdx b/apps/docs/usage/ui.mdx index 38cae6ed..3b2671fe 100644 --- a/apps/docs/usage/ui.mdx +++ b/apps/docs/usage/ui.mdx @@ -1,6 +1,6 @@ --- -title: 'From the UI' -description: 'How to use Open SWE from the UI' +title: "From the UI" +description: "How to use Open SWE from the UI" --- Open SWE provides a powerful web interface that allows you to interact with the coding agent through a chat-like experience. The UI supports both automated and manual workflows, giving you control over how the agent processes your requests. @@ -10,12 +10,14 @@ Open SWE provides a powerful web interface that allows you to interact with the The UI offers two distinct modes for handling your coding requests: -You can toggle between auto and manual mode using the lightning bolt (⚡) icon in the main input area. + You can toggle between auto and manual mode using the lightning bolt (⚡) icon + in the main input area. ### Auto Mode When **Auto Mode** is enabled (lightning bolt icon is highlighted): + - Plans are automatically accepted and executed without user intervention - The agent proceeds directly from planning to implementation - Ideal for straightforward requests where you trust the agent's planning @@ -23,12 +25,14 @@ When **Auto Mode** is enabled (lightning bolt icon is highlighted): ### Manual Mode When **Manual Mode** is active (lightning bolt icon is not highlighted): + - You must manually review and accept proposed plans before execution - Provides opportunity to edit, modify, or reject plans - Allows for more control over the implementation approach -Start with manual mode for important changes to review the agent's approach before execution. + Start with manual mode for important changes to review the agent's approach + before execution. ## Manager Agent Capabilities @@ -39,29 +43,45 @@ The Manager agent acts as the central orchestrator, intelligently routing your m - Provides contextual responses and status updates about ongoing operations. You can ask the manager what it can do, what the status of different agents is, etc. + Provides contextual responses and status updates about ongoing operations. + You can ask the manager what it can do, what the status of different agents + is, etc. - Initiates new planning sessions when you submit coding requests. If your message contains a coding request, the manager will create a new planning session & corresponding GitHub issue. + Initiates new planning sessions when you submit coding requests. If your + message contains a coding request, the manager will create a new planning + session & corresponding GitHub issue. - Forwards additional context or requirements to running planner sessions. If you send a message while the planner is running, the manager can forward that message to the planner, without interrupting its flow. + Forwards additional context or requirements to running planner sessions. If + you send a message while the planner is running, the manager can forward + that message to the planner, without interrupting its flow. - Resumes planner sessions that were paused for the user to accept or reject plans. If the planner has paused for plan acceptance, you can message the manager with feedback about the plan. This will be forwarded to the planner, and it will continue its flow based on your feedback. + Resumes planner sessions that were paused for the user to accept or reject + plans. If the planner has paused for plan acceptance, you can message the + manager with feedback about the plan. This will be forwarded to the planner, + and it will continue its flow based on your feedback. - Provides additional context or instructions to running implementation sessions. If you send a message while the programmer is running, the manager can forward that message to the programmer, without interrupting its flow. + Provides additional context or instructions to running implementation + sessions. If you send a message while the programmer is running, the manager + can forward that message to the programmer, without interrupting its flow. - Creates new tasks, independent of the current request. If you send a message to the manager with a request for a task that is unrelated to the current request, or can be implemented in parallel via a different session, the manager will create a new GitHub issue, and initiate a new planning session for that issue. + Creates new tasks, independent of the current request. If you send a message + to the manager with a request for a task that is unrelated to the current + request, or can be implemented in parallel via a different session, the + manager will create a new GitHub issue, and initiate a new planning session + for that issue. ### What the Manager _cannot_ Do -The Manager has several important limitations to ensure proper workflow control: + The Manager has several important limitations to ensure proper workflow + control: - **Cannot create new Programmer runs** - This only happens after plan acceptance or in auto mode. @@ -77,6 +97,7 @@ The Manager intelligently classifies your messages and routes them to the approp ### Message Classification When you send a message, the Manager analyzes: + - Current status of Planner and Programmer graphs - Content and intent of your message - Existing conversation context @@ -101,19 +122,22 @@ Planning runs are handled by the Planner graph, which creates detailed execution - The Planner analyzes your repository and gathers relevant context about the codebase + The Planner analyzes your repository and gathers relevant context about the + codebase Creates a structured plan with specific, actionable steps - Presents the proposed plan for review (in manual mode) or automatic acceptance (in auto mode) + Presents the proposed plan for review (in manual mode) or automatic + acceptance (in auto mode) ### Plan Interruption Plans are presented as interruptions that require user response: + - **Manual Mode**: You must explicitly accept or reject the plan - **Auto Mode**: Plans are automatically accepted and execution begins - **Plan Editing**: You can modify proposed plans before acceptance @@ -145,7 +169,8 @@ Once a plan is accepted, the Programmer graph executes the implementation. -The Programmer automatically commits changes after each step, ensuring your work is preserved even if the session is interrupted. + The Programmer automatically commits changes after each step, ensuring your + work is preserved even if the session is interrupted. ## Getting Started @@ -163,11 +188,13 @@ To begin using the Open SWE UI: Type your coding request in the terminal input and press Cmd+Enter to send - Watch as the Manager routes your request and coordinates the planning and implementation + Watch as the Manager routes your request and coordinates the planning and + implementation -Make sure you have properly configured your GitHub App and authentication before using the UI. See the [Development Setup](/setup/development) guide for details. + Make sure you have properly configured your GitHub App and authentication + before using the UI. See the [Development Setup](/setup/development) guide for + details. - diff --git a/static/ui-screenshot.png b/static/ui-screenshot.png new file mode 100644 index 00000000..4fdf6e40 Binary files /dev/null and b/static/ui-screenshot.png differ diff --git a/yarn.lock b/yarn.lock index 6c15f759..1f9fe763 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4126,6 +4126,7 @@ __metadata: resolution: "@open-swe/docs@workspace:apps/docs" dependencies: mint: ^4.2.12 + prettier: ^3.5.2 languageName: unknown linkType: soft