How langchain-ai/open-swe works
Purpose and Runtime Entry Points
Open SWE is a deployable software-engineering agent system: it receives work from dashboard, GitHub, Slack, Linear, or schedules; executes durable agent runs; works in isolated environments; and delivers or reviews pull requests. The custom FastAPI application is agent/webapp.py, with server startup in agent/server.py; LangGraph graph entrypoints are registered through agent/graphs/agent.py, agent/graphs/reviewer.py, and agent/graphs/scheduler.py. langgraph.json and langgraph.desktop.json define runtime deployment variants.
Invocation and Thread Lifecycle
Inbound integrations normalize requests into durable threads and invocations. Thread state, access, run views, plans, summaries, and approvals are concentrated in agent/threads/routes.py, agent/threads/runs.py, and agent/threads/workflow_approval.py. Dispatch selects an execution path based on source and task type in agent/dispatch.py and agent/invocation.py. A thread persists conversation/work context across multiple LangGraph runs; cloud coding threads bind to a persistent sandbox, while read-only review/chat can avoid one.
Agent Graph Assembly and Guardrails
The principal coding graph plans, investigates, edits, validates, and delivers changes; reviewer, analyzer, and chat graphs specialize for read-only PR work and repository-style learning. Graph composition resides in agent/graphs/agent.py, agent/graphs/reviewer.py, and agent/graphs/analyzer.py. Cross-cutting middleware governs preparation, model selection/fallback, dynamic tool exposure, retries, validation, tracing, plan mode, and push restrictions: agent/middleware/prepare_run.py, agent/middleware/model_selection.py, agent/middleware/dynamic_tools.py, and agent/middleware/workflow_push_guard.py. Prompts and tool contracts are versioned as repository resources under agent/resources/prompts/system/main.md, agent/resources/prompts/reviewer/main.md, and agent/resources/prompts/tools/.
Sandboxed Execution Boundary
Coding execution is isolated behind a provider-neutral sandbox lifecycle. agent/sandboxes/lifecycle.py creates, recovers, and manages persistent environments; agent/sandboxes/repo_prep.py prepares repositories and workspace setup; agent/sandboxes/providers/registry.py selects providers. Supported implementations include LangSmith, Modal, Daytona, Runloop, E2B, and local execution under agent/sandboxes/providers/. This boundary protects server-held credentials and avoids silently replacing unreachable sandboxes that may contain uncommitted work.
Integrations, Delivery, and Automation
GitHub is both an ingress and delivery boundary: webhook handling, authenticated API access, PR context/diffs, comments, checks, and PR operations reside in agent/github/webhook.py, agent/github/pull_requests.py, and agent/github/checks.py. Slack and Linear provide parallel event-driven entry points in agent/slack/routes.py, agent/slack/events.py, and agent/linear/webhook.py. Scheduled automations and CI monitoring flow through agent/schedules/store.py, agent/scheduler.py, and agent/baby_sit.py. The expedited-review subsystem adds opt-in approval/readiness/voting workflows under agent/expedited_review/.
State, Identity, and Observability
PostgreSQL-backed ORM and migrations define durable product state, including analytics, threads/PRs, users, and workspaces: agent/database/orm.py, agent/database/postgres.py, and agent/database/migrations/versions/. Authorization and credential scoping are enforced in agent/users/authorization.py, agent/credential_scope.py, and agent/encryption.py. Analytics uses capture/outbox/worker-style stages in agent/analytics/capture.py, agent/analytics/outbox.py, and agent/analytics/worker.py. LangSmith is the default tracing and sandbox service; MCP integrations are modeled and routed in agent/mcp/runtime.py and agent/mcp/routes.py.
Product Surfaces
The browser dashboard is a TypeScript/React Vite application rooted at ui/src/router.tsx, with agent-thread streaming UI in ui/src/features/agents/lib/stream/AgentStreamProvider.tsx and server proxy boundaries in ui/server/backend-proxy.ts. The experimental Electron desktop client launches/supervises a local backend and operates on allowlisted local projects via desktop/src/main.cts, desktop/src/backend-supervisor.cjs, and desktop/src/project-store.cts. Desktop-local agent behavior bridges through agent/desktop.py and agent/desktop_branch.py.
Main entry points: webapp.py FastAPI application · agent.py Coding agent graph · prepare_run.py Execution middleware · routes.py Threads and run lifecycle
Components 22
Product surfaces
- React dashboard · Thread streaming interface.
ui/src/router.tsx - Electron desktop · Supervises a local backend for allowlisted projects.
desktop/src/main.cts - GitHub, Slack & Linear · Webhook and event-driven work sources.
agent/github/webhook.py - Schedules & CI monitor · Triggers scheduled work and CI follow-up.
agent/scheduler.py - Dashboard backend proxy
ui/server/backend-proxy.ts
API and orchestration
- FastAPI application · Custom server entry surface for product and integration requests.
agent/webapp.py - Desktop agent bridge
agent/desktop.py - Threads and run lifecycle · Owns thread context, runs, plans, summaries, and approvals.
agent/threads/routes.py - Invocation dispatch · Selects execution by source and task type.
agent/dispatch.py
Agent execution
- Coding agent graph · Plans, investigates, edits, validates, and delivers changes.
agent/graphs/agent.py - Review and analysis graphs · Read-only PR review, repository analysis, and chat paths.
agent/graphs/reviewer.py - Execution middleware · Applies model, tool, retry, validation, tracing, and push controls.
agent/middleware/prepare_run.py - Versioned prompts and tools
agent/resources/prompts/system/main.md
Sandbox boundary
- Sandbox lifecycle · Creates and recovers persistent coding environments.
agent/sandboxes/lifecycle.py - Repository preparation
agent/sandboxes/repo_prep.py - Sandbox providers · Selects LangSmith, Modal, Daytona, Runloop, E2B, or local execution.
agent/sandboxes/providers/registry.py
State and external services
- GitHub PR delivery · Supplies PR context and publishes comments, checks, and PR operations.
agent/github/pull_requests.py - PostgreSQL product state · Durable threads, PRs, users, workspaces, and analytics state.
agent/database/postgres.py - Authorization and credentials · Scopes access and encrypts credentials.
agent/users/authorization.py - Analytics pipeline · Capture, durable outbox, and worker delivery stages.
agent/analytics/outbox.py - MCP runtime
agent/mcp/runtime.py - LangSmith · Default tracing service and a sandbox provider.
Connections 23
- React dashboard → Dashboard backend proxy: browser requests
- Dashboard backend proxy → FastAPI application: proxies
- Electron desktop → Desktop agent bridge: local agent requests
- Desktop agent bridge → FastAPI application: local backend
- GitHub, Slack & Linear → FastAPI application: webhooks
- Schedules & CI monitor → FastAPI application: automation triggers
- FastAPI application → Threads and run lifecycle: creates and reads
- Threads and run lifecycle → PostgreSQL product state: persists context and runs
- FastAPI application → Invocation dispatch: invokes
- Invocation dispatch → Coding agent graph: coding tasks
- Invocation dispatch → Review and analysis graphs: review and chat tasks
- Coding agent graph → Execution middleware: governed by
- Review and analysis graphs → Execution middleware: governed by
- Execution middleware → Versioned prompts and tools: loads contracts
- Coding agent graph → Sandbox lifecycle: persistent coding environment
- Sandbox lifecycle → Repository preparation: prepares workspace
- Sandbox lifecycle → Sandbox providers: selects provider
- Coding agent graph → GitHub PR delivery: delivers changes
- Review and analysis graphs → GitHub PR delivery: reads PRs and posts review
- FastAPI application → Authorization and credentials: authorizes requests
- Execution middleware → LangSmith: traces runs
- Coding agent graph → MCP runtime: uses external tools
- Threads and run lifecycle → Analytics pipeline: emits product events