How unohee/openswarm works
1. What this repository is
OpenSwarm is a Node.js/TypeScript orchestrator for autonomous coding agents. Its job is not to implement one agent, but to coordinate many agent runs, route tasks from external systems, manage execution state, and persist memory/history across sessions.
2. Top-level execution modes
The repo has two main operating shapes: a direct CLI/TUI experience for interactive use, and a daemon mode for autonomous operation. src/index.ts and src/cli.ts are the entry points for commands like chat, run, exec, start, init, and validate. The default openswarm command launches a terminal chat UI, while daemon mode powers scheduled work and integrations.
3. Core configuration and service lifecycle
src/core/ holds the foundational runtime boundary: config loading/validation, service startup/shutdown, event hub, tracing, and shared types. Configuration is YAML-driven with environment substitution, so most subsystems are wired from a central config rather than hardcoded. This layer is the control plane for the rest of the system.
4. Provider abstraction for agent execution
src/adapters/ is the key boundary between OpenSwarm and the external AI CLIs. It abstracts over Claude Code CLI and OpenAI Codex CLI, plus process registration and stream buffering. This means the orchestration layers above it can ask for “worker” or “reviewer” behavior without caring which CLI provider is executing underneath.
5. Agent pipeline as the main work unit
src/agents/ defines the actual role-based execution pipeline: worker, reviewer, tester, documenter, and auditor. The central flow is pairPipeline.ts, which runs Worker → Reviewer, with optional Tester and Documenter stages. agentBus.ts and related helpers coordinate message passing, review outcomes, stream parsing, and metrics across those roles.
6. Autonomous daemon and scheduling
src/automation/ is where unattended operation lives. The autonomous runner, scheduler, PR processor, long-running monitor, and conflict resolution logic combine to repeatedly pick up work, execute it, and recover from failures. This subsystem is what turns the project from a chat tool into a background agent service.
7. Task selection and workflow control
src/orchestration/ acts as the policy layer. It parses tasks, detects conflicts, schedules work, and decides what is safe to run next. The decisionEngine and related workflow code are the guardrails that keep tasks scoped, prioritized, and non-overlapping before they reach the agent pipeline.
8. External system integrations
src/linear/, src/discord/, and src/github/ are the main integration boundaries. Linear supplies issues and project state, Discord is the command-and-control surface for monitoring and runtime actions, and GitHub is used mainly for CI and PR status monitoring. These integrations feed tasks into the orchestrator and receive progress/results back out.
9. Memory and knowledge subsystems
OpenSwarm has two distinct long-term cognition layers. src/memory/ stores retrieved experience and beliefs using LanceDB-style vector memory and compaction logic, while src/knowledge/ builds a static analysis graph of the repository for dependency and impact reasoning. In practice, memory is about “what happened before,” and knowledge is about “what code is connected to what.”
10. Support tooling and local operator experience
src/support/ contains the operator-facing utilities: TUI/dashboard rendering, chat backends, Git/worktree management, rollback, rate/quota tracking, and stuck detection. This is the glue that makes the system usable in local or semi-local execution, especially when tasks are running in separate worktrees or need recovery.
11. State persistence and task rehydration
Runtime state is persisted in several places: a user state directory under ~/.openswarm/, Claude/OpenSwarm JSON history files, and the config file. There is also a dedicated src/taskState/ store and a Python model file for task-state modeling. The architecture therefore keeps short-lived execution state, long-lived memory, and task history as separate concerns.
12. Locale, templates, and prompt composition
src/locale/ and templates/ are not just text assets; they are part of how the agent system is instructed and standardized. They provide localized prompts and role templates for bootstrapping agents, reviewing work, analyzing issues, and generating reports. This is an important boundary because prompt content is treated as a first-class runtime input.
13. Operational packaging
The repo includes Docker, docker-compose, and macOS launchd scripts, which means it supports both containerized and native service deployment. Those files do not change the core architecture, but they matter for diagramming the runtime environment: the daemon can run as a long-lived service with external CLI tooling installed on the host.
14. Primary data flow
The main flow is: Linear issues or Discord commands enter the system → orchestration/decision logic selects and scopes work → the agent pipeline runs through a provider adapter → results are written back to issue/task state, memory, and possibly GitHub/Discord updates. That loop is the architectural center of the repo, with memory/knowledge providing context and automation/scheduling keeping it running continuously.
Main entry points: pairPipeline.ts Pair pipeline · autonomousRunner.ts Autonomous runner · decisionEngine.ts Decision engine · service.ts Service lifecycle
Components 31
Entry points
CLI and command startup paths
- Main entry · Top-level Node.js launch path for the application
src/index.ts - CLI commands · Dispatches interactive and utility commands such as chat, run, exec, start, init, and validate
src/cli.ts - Prompt handler · Handles interactive command input for the TUI/CLI experience
src/cli/promptHandler.ts
Core runtime
Configuration, lifecycle, tracing, and shared services
- Config · Loads and validates YAML-driven configuration with environment substitution
src/core/config.ts - Service lifecycle · Starts, wires, and shuts down core services
src/core/service.ts - Event hub · Shared internal event distribution and coordination
src/core/eventHub.ts - Tracing · Collects traces and runtime diagnostics
src/core/traceCollector.ts - Shared types · Common runtime types and interfaces
src/core/types.ts
Agent pipeline
Role-based execution and message flow
- Adapter layer · Exports the execution provider abstraction used by higher layers
src/adapters/index.ts - Claude CLI · Adapter for Claude Code CLI execution
src/adapters/claude.ts - Codex CLI · Adapter for OpenAI Codex CLI execution
src/adapters/codex.ts - Pair pipeline · Coordinates Worker → Reviewer with optional Tester and Documenter stages
src/agents/pairPipeline.ts - Worker · Primary task execution role
src/agents/worker.ts - Reviewer · Validates and critiques worker output
src/agents/reviewer.ts - Tester · Runs verification-oriented agent work
src/agents/tester.ts - Documenter · Produces documentation and summaries
src/agents/documenter.ts - Agent bus · Moves messages, outcomes, and metrics across agent roles
src/agents/agentBus.ts
Autonomy and ops
Scheduling, daemon execution, and service management
- Decision engine · Chooses what tasks are safe and ready to run
src/orchestration/decisionEngine.ts - Task scheduler · Orders and schedules work items before execution
src/orchestration/taskScheduler.ts - Autonomous runner · Long-running unattended execution loop
src/automation/autonomousRunner.ts - Automation scheduler · Repeating scheduling and handoff for background work
src/automation/scheduler.ts - Monitor · Observes long-running activity and recovers from failures
src/automation/longRunningMonitor.ts
Integrations
External systems and host-facing surfaces
- Discord core · Discord command and event surface
src/discord/discordCore.ts - GitHub · GitHub status and PR-facing integration
src/github/github.ts - Linear · Issue and project source for tasks
src/linear/linear.ts - Support tools · TUI, chat, worktree, rollback, quota, and recovery utilities
src/support/index.ts
Context systems
Memory, knowledge, and prompt assets
- Memory core · Stores retrieved experience and beliefs across sessions
src/memory/memoryCore.ts - Compaction · Compresses and maintains long-term memory state
src/memory/compaction.ts - Knowledge graph · Builds repository dependency and impact context
src/knowledge/graph.ts - Prompt templates · Localized role templates and bootstrap prompts
src/locale/prompts/en.ts - Task state · Dedicated persistent store for task rehydration and runtime state
src/taskState/store.ts
Connections 30
- Main entry → CLI commands: starts · Main entry hands control to command routing
- CLI commands → Prompt handler: interactive input · CLI delegates interactive use to the prompt handler
- CLI commands → Config: loads · Commands read configuration before executing
- Service lifecycle → Event hub: publishes · Service lifecycle wires the internal event hub
- Service lifecycle → Tracing: traces · Lifecycle emits diagnostics through tracing
- Service lifecycle → Shared types: uses · Shared runtime contracts shape service wiring
- Adapter layer → Claude CLI: selects · Provider facade exposes Claude execution
- Adapter layer → Codex CLI: selects · Provider facade exposes Codex execution
- Pair pipeline → Worker: runs · Pipeline begins with worker execution
- Pair pipeline → Reviewer: reviews · Pipeline routes worker output to review
- Pair pipeline → Tester: optional · Some flows add testing before completion
- Pair pipeline → Documenter: optional · Some flows add documentation generation
- Worker → Adapter layer: executes via · Worker delegates model work through the provider layer
- Reviewer → Agent bus: reports · Review results and signals move through the bus
- Worker → Agent bus: streams · Worker progress and outputs are coordinated by the bus
- Decision engine → Task scheduler: orders · Decision layer hands approved work to scheduling
- Autonomous runner → Decision engine: requests · Autonomous execution asks policy what to run next
- Automation scheduler → Autonomous runner: drives · Background scheduler triggers repeated runner cycles
- Monitor → Autonomous runner: watches · Monitoring observes and helps recover the daemon loop
- Discord core → Decision engine: commands · Discord commands enter task policy and control
- Linear → Task scheduler: feeds tasks · Linear issues become scheduled work items
- GitHub → Monitor: status · GitHub checks and PR state feed monitoring
- Support tools → Prompt handler: powers · Operator tooling backs chat and TUI flows
- Support tools → Task state: persists · Support utilities interact with durable task state
- Memory core → Compaction: maintains · Memory maintenance keeps long-term store manageable
- Pair pipeline → Memory core: writes context · Agent outcomes are stored for later recall
- Knowledge graph → Decision engine: informs · Repository knowledge helps decide what is safe or relevant to run
- Prompt templates → Pair pipeline: templates · Prompt assets shape role behavior and bootstrapping
- Task state → Autonomous runner: rehydrates · Persisted task state supports resuming execution
- Config → Autonomous runner: configures · Central config wires autonomous behavior