diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 84988e6a..7b650b4e 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -23,7 +23,7 @@ { "group": "Usage", "pages": [ - "usage/index", + "usage/intro", "usage/ui", "usage/webhook" ] @@ -31,9 +31,10 @@ { "group": "Development Setup", "pages": [ - "setup/index", + "setup/intro", "setup/development", - "setup/authentication" + "setup/authentication", + "setup/monorepo" ] } ] @@ -43,7 +44,7 @@ "anchors": [ { "anchor": "Demo", - "href": "https://openswe.langchain.com", + "href": "https://swe.langchain.com", "icon": "link" }, { diff --git a/apps/docs/index.mdx b/apps/docs/index.mdx index 0ec1fe47..9db3f1b0 100644 --- a/apps/docs/index.mdx +++ b/apps/docs/index.mdx @@ -3,6 +3,22 @@ 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. + + +## 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. + + How to set up Open SWE for development Open SWE features, and how to use them -(add a very high level overview of what open swe is, and what content the docs cover) +## What's in These Docs + +This documentation covers everything you need to know about Open SWE: + +- **Concepts**: Core principles and architecture behind Open SWE +- **Usage**: How to interact with Open SWE through the web interface and GitHub webhooks +- **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. + + diff --git a/apps/docs/package.json b/apps/docs/package.json index b93b271f..abbab301 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -7,6 +7,6 @@ "dev": "mint dev" }, "devDependencies": { - "mint": "^4.1.19" + "mint": "^4.2.12" } } diff --git a/apps/docs/setup/authentication.mdx b/apps/docs/setup/authentication.mdx index cdd9d813..01af3267 100644 --- a/apps/docs/setup/authentication.mdx +++ b/apps/docs/setup/authentication.mdx @@ -3,37 +3,137 @@ title: 'Authentication' description: 'How authentication works in Open SWE' --- -(in this page, cover how the auth flow 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. -- Discuss how we use GitHub Oauth for client side auth - - if user is not logged in, it will require them to login - - if they are logged in, it'll redirect them to the chat page - - users can update their gh auth via the `/settings` page -- Discuss LangGraph auth - - all requests made to the LangGraph server are authenticated - - when making requests from the client, they first go through a proxy route in the Next.js app. - - proxy route uses the `langgraph-nextjs-api-passthrough` package (https://www.npmjs.com/package/langgraph-nextjs-api-passthrough) - - this proxy route injects the following headers to the request: - - `GITHUB_TOKEN_COOKIE` (`"x-github-access-token"`) - this is the user's access token for github. it will allow us to take actions on behalf of the user, such as create gh issues and comments - - `GITHUB_INSTALLATION_TOKEN_COOKIE` (`"x-github-installation-token"`) - this is the installation token for the github app. it will allow us to take actions on behalf of the github app, such as make commits and open pull requests - - `GITHUB_INSTALLATION_NAME` (`"x-github-installation-name"`) - this is the name of the installation. will be either your github username if you're making requests against a repo your user owns, or an org name if making requests on a repo in an org - - all headers are prefixed with `x-` so that they are included in the configurable field of the langgraph runs, so we can access them during a run and not only in the auth middleware - - all secrets (gh tokens) are encrypted in this proxy route to prevent them being exposed in LangSmith traces, or if other users are somehow able to access your threads/runs. - - finally, the request is forwarded to your actual langgraph server, where it first runs through an auth middleware to verify the user is authenticated. - - the first check in the langgraph server auth middleware looks to see if a header is present which would indicate the request is coming from a github webhook - - if true, it will verify the webhook signature, and authorize it if so. we do not include the user information in this auth step, as that is done in the next request that the webhook handler makes to actually create a new langgraph run based on the webhook event. here is where your gh user is included so that the thread/run created by this webhook is only exposed to you, the user. - - all requests made to the langgraph server go through this auth middleware. this includes requests to custom routes (like the webhook handler) and requests made to the langgraph server (like creating a new thread/run) - - if it's not a webhook request, we check for two required headers - - the installation name - - the installation token - - if either are not defined, we throw a 401 unauthorized error - - after getting these headers, we check to see if there's a github access token (tied to a user) - - if there is, we use that to verify the user. this would indicate the request was made from the web app - - if there isn't, we check for two additional headers - - the user id - - the user login - - after getting these values, we verify the user ID & login passed in headers are valid, and that the installation token is valid - - this occurs when a run is created from a github webhook +## GitHub OAuth Authentication - - finally, after validating either the github user id & login, or getting the user ID and login from the user's github access token, we return a new identity object. this contains the user's ID, and the installation name. we use the user ID to ensure the only resources you're allowed to access are your own. the auth middleware then forwards to a handler which runs for each resource type (e.g. create new thread). in this handler we add your user id to metadata if it's a create request, and if it's a get request we verify the user id from the identity matches the one in the metadata. - - since the access tokens/installation tokens are prefixed with `x-` they're going to be included in the configurable field of the langgraph runs (still encrypted). so whenever we need to take some action (e.g. create new issue) we first extract that field from the configurable field, decrypt, then preform the action. \ No newline at end of file +Open SWE uses GitHub OAuth for client-side authentication, providing secure access to user accounts and repository permissions. + +### Authentication Flow + +- **Unauthenticated users** are automatically redirected to GitHub OAuth login +- **Authenticated users** are redirected directly to the chat interface +- **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. + + +## LangGraph Server Authentication + +All requests to the LangGraph server are authenticated through a sophisticated proxy system that ensures secure communication between the web interface and the agent backend. + +### Proxy Route Architecture + +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. + + +### Header Injection System + +The proxy route automatically injects the following encrypted headers into each request: + +#### Authentication Headers + +- **`x-github-access-token`** - User's GitHub access token for user-specific actions (creating issues, comments) +- **`x-github-installation-token`** - GitHub App installation token for app-level actions (commits, pull requests) +- **`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. + + +### Token Encryption + +Open SWE implements AES-256-GCM encryption for all GitHub tokens to prevent exposure in: +- LangSmith trace metadata +- Run configurations +- Potential unauthorized access scenarios + +The encryption process uses the `GITHUB_TOKEN_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. + + +## Authentication Middleware + +The LangGraph server implements comprehensive authentication middleware (`apps/open-swe/src/security/auth.ts`) that validates all incoming requests. + +### Webhook Authentication + +The middleware first checks for GitHub webhook requests by detecting the `X-Hub-Signature-256` header: + +1. **Signature verification** using the configured webhook secret +2. **Automatic authorization** for valid webhook signatures +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. + + +### Standard Request Authentication + +For non-webhook requests, the middleware validates: + +#### Required Headers +- **Installation name** (`x-github-installation-name`) +- **Installation token** (`x-github-installation-token`) + +Missing either header results in a 401 Unauthorized error. + +#### User Verification Process + +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 + +### 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. + + +## Resource Access Control + +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 + +## Token Access During Execution + +During LangGraph run execution, encrypted tokens are accessible through the run's configurable field: + +1. **Token extraction** from run configuration +2. **Decryption** using the shared encryption key +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. + + + +Always ensure the `GITHUB_TOKEN_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 3d5239b7..96de70f3 100644 --- a/apps/docs/setup/development.mdx +++ b/apps/docs/setup/development.mdx @@ -3,52 +3,244 @@ title: 'Development Setup' description: 'How to set up Open SWE for development' --- -(in this page, cover what is needed 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. -- clone repo -- install deps -- copy env example files from both `apps/web/.env.example` & `apps/open-swe/.env.example` - - discuss filling in values for each (excluding GH app values. note that we'll cover that in the next step) -- create gh app - - mention having a dev github app and a prod github app - - add callout that this is a GitHub App, which is not the same as a GitHub oauth app - - walk through setup & permissions: - - https://github.com/settings/apps/new to create new github app - - give it a name & description - - set homepage url to your URL, or repo readme if no url - - set callback url to `http://localhost:3000/api/auth/github/callback` for dev - - uncheck `Expire user authorization tokens` so that the users tokens never expire - - check `Request user authorization (OAuth) during installation` so that we can allow users to use our gh app for login to the web app - - check `Redirect on update` so users are always redirected back to your app after updating permissions - - enable webhook - - set webhook url to `/webhook/github`. suggest using ngrok to create a public url which points to your local `http://localhost:2024` server for dev (`/webhook/github` is a custom route added to your langgraph server) - - create secret: `openssl rand -hex 32` and set this as the webhook secret, and save it under the `GITHUB_WEBHOOK_SECRET` in the `apps/open-swe/.env` file - - set permissions: - - Repository permissions: - - `Contents`: `Read & Write` - - `Issues`: `Read & Write` - - `Pull requests`: `Read & Write` - - `Metadata`: `Read only` (mandatory, will be enabled for you) - - Organization permissions: - - None - - Account permissions: - - None + +This setup is for development purposes. For production deployment, you'll need to adjust URLs and create separate GitHub Apps for production use. + - - Subscribe to events: - - `Issues` - required for webhook to work - - - `Where can this GitHub App be installed?`: `Any account` (or `Only on this account` if you want to limit it to your own account) - - Create GitHub App - - After creating app, we'll now be able to get/create secrets: - - `GITHUB_APP_NAME`: name of the app, e.g. `open-swe-dev` - - `GITHUB_APP_ID`: `App ID` of the app, e.g. `12345678` - - `GITHUB_APP_PRIVATE_KEY`: `Private key` of the app. To generate, scroll down to the `Private keys` section and generate a new one. e.g. `-----BEGIN RSA PRIVATE KEY-----\n...add your private key here...\n-----END RSA PRIVATE KEY-----\n` - - `GITHUB_APP_CLIENT_ID`: `Client ID` of the app - - `GITHUB_APP_CLIENT_SECRET`: Under the `Client secrets` section, click `Generate new client secret` and copy the value. - - done -- after setting all your env vars, you can now start the agent & web app servers - - `cd apps/open-swe` - `yarn dev` - starts a development server at `http://localhost:2024` - (in a separate terminal window) - - `cd apps/web` - `yarn dev` - starts a development server at `http://localhost:3000` +## Prerequisites -Done! Now you can visit `http://localhost:3000` to see the web app, and start using Open SWE! \ No newline at end of file +Before starting, ensure you have the following installed: +- Node.js (version 18 or higher) +- Yarn (version 3.5.1 or higher) +- Git + +## Setup Steps + + + + Clone the Open SWE repository to your local machine: + + ```bash + git clone https://github.com/langchain-ai/open-swe.git + ``` + ```bash + cd open-swe + ``` + + + + Install all dependencies using Yarn from the repository root: + + ```bash + yarn install + ``` + + This will install dependencies for all packages in the monorepo workspace. + + + + Copy the environment example files and configure them: + + ```bash + # Copy web app environment file + cp apps/web/.env.example apps/web/.env + ``` + ```bash + # Copy agent environment file + cp apps/open-swe/.env.example apps/open-swe/.env + ``` + + ### Web App Environment Variables (`apps/web/.env`) + + Fill in the following variables (GitHub App values will be added in the next step): + + ```bash Environment Variables [expandable] + # GitHub App OAuth settings (will be filled after creating GitHub App) + GITHUB_APP_CLIENT_ID="" + GITHUB_APP_CLIENT_SECRET="" + GITHUB_APP_REDIRECT_URI="http://localhost:3000/api/auth/github/callback" + + # Token encryption key (generate with: openssl rand -hex 32) + GITHUB_TOKEN_ENCRYPTION_KEY="" + + # GitHub App details (will be filled after creating GitHub App) + GITHUB_APP_NAME="open-swe-dev" + GITHUB_APP_ID="" + GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- + ...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" + ``` + + ### Agent Environment Variables (`apps/open-swe/.env`) + + Configure the agent environment variables: + + ```bash Environment Variables [expandable] + # LangSmith tracing & LangGraph platform + LANGCHAIN_PROJECT="default" + 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_TOKEN_ENCRYPTION_KEY="" # Must match web app value + GITHUB_APP_NAME="open-swe-dev" + GITHUB_APP_ID="" + GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- + ...add your private key here... + -----END RSA PRIVATE KEY----- + " + GITHUB_WEBHOOK_SECRET="" # Will be generated in next step + + # Server configuration + PORT="2024" + OPEN_SWE_APP_URL="http://localhost:3000" + ``` + + + Generate the `GITHUB_TOKEN_ENCRYPTION_KEY` using: `openssl rand -hex 32`. This key must be identical in both environment files. + + + + + + You'll need to create a **GitHub App** (not a GitHub OAuth App). These are different types of applications with different capabilities. Consider creating separate GitHub apps for development and production environments. + + + ### Create the GitHub App + + 1. Go to [GitHub App creation page](https://github.com/settings/apps/new) + 2. Fill in the basic information: + - **GitHub App name**: Your preferred name + - **Description**: Development instance of Open SWE coding agent + - **Homepage URL**: Your repository URL + - **Callback URL**: `http://localhost:3000/api/auth/github/callback` + + ### Configure OAuth Settings + + - ✅ **Request user authorization (OAuth) during installation** - Allows users to log in to the web app + - ✅ **Redirect on update** - Redirects users back to your app after permission updates + - ❌ **Expire user authorization tokens** - Keep tokens from expiring + + ### Set Up Webhook + + 1. ✅ **Enable webhook** + 2. **Webhook URL**: You'll need to use a tool like ngrok to expose your local server: + ```bash + # Install ngrok if you haven't already + # Then expose your local LangGraph server + 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 + ``` + Add this value to `GITHUB_WEBHOOK_SECRET` in `apps/open-swe/.env` + + ### Configure Permissions + + **Repository permissions:** + - **Contents**: Read & Write + - **Issues**: Read & Write + - **Pull requests**: Read & Write + - **Metadata**: Read only (automatically enabled) + + **Organization permissions:** None + + **Account permissions:** None + + ### Subscribe to Events + + - ✅ **Issues** - Required for webhook functionality + + ### Installation Settings + + - **Where can this GitHub App be installed?**: + - Choose "Any account" for broader testing + - Or "Only on this account" to limit to your repositories + + ### Complete App Creation + + Click **Create GitHub App** to finish the setup. + + ### Collect App Credentials + + After creating the app, collect the following values and add them to both environment files: + + - **GITHUB_APP_NAME**: The name you chose + - **GITHUB_APP_ID**: Found in the "About" section (e.g., `12345678`) + - **GITHUB_APP_CLIENT_ID**: Found in the "About" section + - **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 + 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 + + + Keep your GitHub App credentials secure and never commit them to version control. The `.env` files are already included in `.gitignore`. + + + + + With all environment variables configured, start both development servers: + + **Terminal 1 - Start the LangGraph Agent:** + ```bash + # apps/open-swe + yarn dev + ``` + This starts the LangGraph server at `http://localhost:2024` + + **Terminal 2 - Start the Web Application:** + ```bash + # apps/web + yarn dev + ``` + This starts the Next.js web app at `http://localhost:3000` + + + Both servers need to be running simultaneously for full functionality. The web app communicates with the LangGraph agent through API calls. + + + + +## Verification + +Once both servers are running: + +1. **Visit the web app**: Navigate to `http://localhost:3000` +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. + + +## Next Steps + +- Learn about [Authentication](/setup/authentication) to understand how the GitHub App integration works +- Explore [Usage](/usage/intro) to start using Open SWE for code changes +- Review the [Monorepo Structure](/setup/monorepo) for development best practices diff --git a/apps/docs/setup/index.mdx b/apps/docs/setup/index.mdx deleted file mode 100644 index 51350092..00000000 --- a/apps/docs/setup/index.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 'Introduction' -description: 'How to set up Open SWE for development' ---- - -(in this page, cover what the setup pages include, and link to them) - -- link to each individual page: monorepo, development, authentication -- discuss what tech is used - - typescript - - yarn - - turbo repo - - next.js for web app - - langgraph for agent - - mintlify for docs diff --git a/apps/docs/setup/intro.mdx b/apps/docs/setup/intro.mdx new file mode 100644 index 00000000..0ce1df6a --- /dev/null +++ b/apps/docs/setup/intro.mdx @@ -0,0 +1,71 @@ +--- +title: 'Introduction' +description: 'How to set up Open SWE for development' +--- + +# Development Setup Overview + +Welcome to the Open SWE development setup guide. This section will walk you through everything you need to know to get Open SWE running locally for development. + +## Setup Sections + +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. + + + Understanding the authentication flow, GitHub App configuration, and security mechanisms used throughout Open SWE. + + + +## Technology Stack + +Open SWE is built with modern technologies designed for scalability and developer experience: + +### Core Technologies + +- **TypeScript** - Strict type safety across the entire codebase +- **Yarn** - Package manager with workspace support (v3.5.1) +- **Turbo** - Monorepo build orchestration and task running + +### Agent Infrastructure + +- **LangGraph** - Multi-agent orchestration framework with three specialized graphs: + - Manager graph for user interaction orchestration + - Planner graph for execution plan creation + - Programmer graph for code change execution +- **Daytona** - Sandboxed development environments for safe code execution + +### Web Application + +- **Next.js** - React framework with App Router +- **Shadcn UI** - Component library built on Radix UI primitives +- **Tailwind CSS** - Utility-first CSS framework + +### Documentation + +- **Mintlify** - Documentation platform with MDX support + +## Monorepo Structure + + +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/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 b6295ce7..8d3506a5 100644 --- a/apps/docs/setup/monorepo.mdx +++ b/apps/docs/setup/monorepo.mdx @@ -3,17 +3,139 @@ title: 'Monorepo' description: 'How the Open SWE monorepo is configured' --- -(in this page, cover the monorepo structure, and best practices for using it) +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. -- cover the repo structure: - - monorepo - - `apps/open-swe` contains the agent - - `apps/web` contains the web app - - `apps/docs` contains the docs - - `packages/shared` contains shared utils, types, etc. any code which is used in both the agent & web app should go here -- turbo repo for monorepo management - - install deps in specific packages theyre used in, never in root - - only time to install deps in root is when adding a resolution. if multiple apps/packages share a dependency, add the resolution to root so that they all use the same version - - run build from root or `packages/shared` when making a change in `shared` and want access in other packages -- mention that the `apps/open-swe` package has a `postinstall` hook which runs `yarn build` after installing deps. - - this is required so that we can deploy on langgraph platform. since open swe is a monorepo and the agent requires accessing built files from the shared repo, we must run build before we can start the langgraph server \ No newline at end of file +## Repository Structure + +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 +- 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 + +### 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. + + +## Turbo Orchestration + +The monorepo uses [Turbo](https://turbo.build/) for efficient build orchestration and task management: + +### Task Dependencies + +```json +{ + "build": { + "dependsOn": ["^build"], + "outputs": ["dist/**", ".next/**", "!.next/cache/**"] + }, + "lint": { + "dependsOn": ["^lint"] + } +} +``` + +The `^build` dependency ensures that shared packages are built before dependent packages, maintaining proper build order across the monorepo. + +### Available Scripts + +Run these commands from the repository root: + +- `yarn build` - Build all packages in dependency order +- `yarn lint` - Run linting across all packages +- `yarn format` - Format code using Prettier + +## Dependency Management Best Practices + + + + Always install dependencies in the specific package where they're used, never in the root `package.json` unless adding a resolution. + + ```bash + # Correct - install in specific package + cd apps/web + yarn add some-package + + # Incorrect - don't install in root + yarn add some-package + ``` + + + + When multiple packages need the same dependency, add a resolution to the root `package.json` to ensure version consistency. + + ```json + { + "resolutions": { + "@langchain/langgraph-sdk": "^0.0.85", + "@langchain/core": "^0.3.58" + } + } + ``` + + + + Run `yarn build` from the root when making changes to `packages/shared` to make them available to other packages. + + ```bash + # After modifying packages/shared + yarn build + ``` + + + +## Postinstall Hook Requirements + +The `apps/open-swe` package includes a critical `postinstall` hook: + +```json +{ + "scripts": { + "postinstall": "turbo build" + } +} +``` + + +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 + +1. **Deployment Compatibility**: The LangGraph Platform needs all dependencies built and available +2. **Shared Package Access**: The agent imports utilities from `@open-swe/shared` which must be compiled +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. + + +## Workspace Configuration + +The monorepo uses Yarn 3.5.1 with the following configuration: + +- **Node Linker**: `node-modules` for compatibility +- **Workspaces**: Automatically discovers packages in `apps/*` and `packages/*` +- **Package Manager**: Enforced via `packageManager` field in `package.json` diff --git a/apps/docs/usage/index.mdx b/apps/docs/usage/index.mdx deleted file mode 100644 index f38d82f2..00000000 --- a/apps/docs/usage/index.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: 'Introduction' -description: 'How to use Open SWE' ---- - -(in this page, cover the high level ways you can use open swe, and link to each individual page for more details. also, link to the public demo and mention that you can use a deployed version from it) \ No newline at end of file diff --git a/apps/docs/usage/intro.mdx b/apps/docs/usage/intro.mdx new file mode 100644 index 00000000..a589baeb --- /dev/null +++ b/apps/docs/usage/intro.mdx @@ -0,0 +1,51 @@ +--- +title: 'Introduction' +description: 'How to use Open SWE' +--- + +# Using Open SWE + +Open SWE provides two primary ways to interact with the coding agent, each designed for different workflows and use cases. Whether you prefer direct interaction through a web interface or automated triggers through GitHub webhooks, Open SWE adapts to your development process. + +## Usage Methods + + + + Interactive chat interface with manual and auto modes for direct agent communication + + + Automated triggers through GitHub issue labels for seamless repository integration + + + +## Getting Started + +### Try the Demo + +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). + + +### Choose Your Workflow + +- **Web Interface**: Best for interactive development, experimentation, and when you want direct control over the agent's planning and execution process +- **GitHub Webhooks**: Ideal for automated workflows, issue-driven development, and team collaboration where coding tasks are tracked through GitHub issues + +## 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. + + +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 8eea051d..38cae6ed 100644 --- a/apps/docs/usage/ui.mdx +++ b/apps/docs/usage/ui.mdx @@ -3,15 +3,171 @@ title: 'From the UI' description: 'How to use Open SWE from the UI' --- -(in this page, cover how you can use Open SWE from the UI. Do not include screenshots, I will manually add those later) +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. + +## Auto vs Manual Mode + +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. + + +### 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 + +### 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. + + +## Manager Agent Capabilities + +The Manager agent acts as the central orchestrator, intelligently routing your messages and managing the overall workflow. Here's what the Manager can and cannot do: + +### What the manager _can_ do + + + + 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. + + + 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. + + + 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. + + + +### What the Manager _cannot_ Do + + +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. +- **Cannot stop running Planner/Programmer sessions** - To stop a session, you must click the cancel button in the UI. +- **Cannot re-plan while Programmer is running** - Once the programmer session has started, you can not go back to the planner. However, you can send a message to the manager which can be forwarded to the programmer. +- **Cannot open Pull Requests directly** - PRs are created automatically after Programmer completion (and changes are automatically committed anytime a file is modified). +- **Cannot accept plans in manual mode** - You must manually click accept for plan approval. + +## Message Handling and Routing + +The Manager intelligently classifies your messages and routes them to the appropriate component: + +### 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 +- Active plans and tasks + +### Routing Options + +Based on the analysis, messages are routed to: + +- **Start Planner**: For new coding requests requiring planning +- **Update Planner**: To add context to active planning sessions +- **Resume Planner**: To continue interrupted planning with new information +- **Update Programmer**: To provide context to active implementation sessions +- **Create New Issue**: For independent requests that should be separate GitHub issues +- **No Operation**: For messages that don't require specific routing + +## Planning Runs + +Planning runs are handled by the Planner graph, which creates detailed execution plans for your requests. + +### Planning Process + + + + 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) + + + +### 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 +- **Feedback**: You can provide feedback to the manager if you want the plan to be changed in some way + +### Automatic Approval + +When auto mode is enabled, plans are automatically accepted and implementation begins immediately after plan generation. + +## Programmer Runs + +Once a plan is accepted, the Programmer graph executes the implementation. + +### Programming Process + + + + Works through each step of the accepted plan systematically + + + Makes actual changes to files in your repository + + + Updates plan status and provides summaries of completed work + + + Automatically opens a PR with all changes when implementation is complete + + + + +The Programmer automatically commits changes after each step, ensuring your work is preserved even if the session is interrupted. + + +## Getting Started + +To begin using the Open SWE UI: + + + + Choose your GitHub repository and branch using the repository selector + + + Toggle auto/manual mode based on your preference for plan approval + + + 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 + + + + +Make sure you have properly configured your GitHub App and authentication before using the UI. See the [Development Setup](/setup/development) guide for details. + -discuss: -- Auto mode vs manual mode -- chatting with the agent (manager) - - what the manager can do: respond to user, create new planning run, send new message to active planning run, resume the planner after interrupted with a response, send new message to active programmer run - - what the manager can NOT do: create new programmer run (this can only happen by accepting the proposed plan/auto mode after plan is complete), stop the planner/programmer. re-plan while the programmer is running. open a PR (this will only happen after the programmer finishes. the programmer will always auto-commit after every change though), accept a plan (you need to manually click accept if not running in auto-mode) - - overview of how the manager can take actions: - - how messages you send to the manager trigger planning runs - - how messages you send to the manager can add new messages to planning run while its active - - how messages you send to the manager can resume the planner if it's interrupted w/ a proposed plan - - how messages you send to the manager can send new messages to active programmer run diff --git a/apps/docs/usage/webhook.mdx b/apps/docs/usage/webhook.mdx index 9c5ff93e..e2868d09 100644 --- a/apps/docs/usage/webhook.mdx +++ b/apps/docs/usage/webhook.mdx @@ -2,11 +2,101 @@ title: 'From Webhooks' description: 'How to use Open SWE from webhooks' --- +# GitHub Webhook Integration -(in this page, cover how you can trigger open swe from webhooks, specifically github issues) +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. -- discuss how adding a label to a GH issue that Open SWE is installed on can trigger a run - - cover manual vs auto mode (`open-swe` vs `open-swe-auto`) - - cover how open swe will reply to the issue with a message confirming it's started a new run, and it will include a link to the new run so you can view it in the open swe UI - - cover how only the user who created the issue will be able to view this URL -- discuss how PRs will link back to the issue that triggered it, so when the PR is closed, it will close the issue \ No newline at end of file +## Triggering Runs with Labels + +Open SWE monitors GitHub issues for specific labels that trigger automated runs. When you add one of these labels to an issue, Open SWE will automatically create a new run to process your request. + +### Label Types + +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. + + +## Automatic Run Creation + +When you add a supported label to a GitHub issue, Open SWE's webhook handler automatically: + +1. **Validates the request** - Verifies webhook signatures and authentication +2. **Extracts issue context** - Captures the issue title, description, and metadata +3. **Creates a new thread** - Generates a unique thread ID for the conversation +4. **Starts the Manager Graph** - Initiates the agent workflow with the issue content +5. **Configures execution mode** - Sets auto-accept based on the label type used + +The entire process happens within seconds of adding the label, providing immediate feedback through issue comments. + +## Issue Comments and Run Links + +Once a run is created, Open SWE automatically posts a comment on the triggering issue to confirm processing has started. This comment includes: + +- **Status confirmation** - "🤖 Open SWE has been triggered for this issue. Processing..." +- **Run link** - Direct URL to view the run in the Open SWE web interface +- **Access restriction notice** - Clarifies that only the issue creator can access the run +- **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. + + +## User Access Restrictions + +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. + + +## Pull Request Integration + +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. + + +## Getting Started + +To start using Open SWE with webhooks: + +1. **Ensure Open SWE is installed** on your repository as a GitHub App +2. **Create a detailed issue** describing the changes you want +3. **Add the appropriate label** (`open-swe` for manual mode or `open-swe-auto` for automatic mode) +4. **Monitor the issue comments** for the run link and status updates +5. **Review and merge the PR** when Open SWE completes the changes + +For setup instructions, see the [Development Setup](/setup/development) guide. diff --git a/yarn.lock b/yarn.lock index 75898ef8..513c8302 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3494,7 +3494,7 @@ __metadata: version: 0.0.0-use.local resolution: "@open-swe/docs@workspace:apps/docs" dependencies: - mint: ^4.1.19 + mint: ^4.2.12 languageName: unknown linkType: soft @@ -13652,7 +13652,7 @@ __metadata: languageName: node linkType: hard -"mint@npm:^4.1.19": +"mint@npm:^4.2.12": version: 4.2.12 resolution: "mint@npm:4.2.12" dependencies: