### Start OpenSwarm Service

Source: https://context7.com/unohee/openswarm/llms.txt

Use this command to start the OpenSwarm service. Ensure npm is installed and configured.

```bash
npm run service:start
```

--------------------------------

### Start Full OpenSwarm Daemon

Source: https://context7.com/unohee/openswarm/llms.txt

Starts the full daemon with Discord bot, Linear integration, and autonomous execution. Requires a config.yaml file for setup.

```bash
# Generate config scaffold
openswarm init

# Validate configuration
openswarm validate

# Start full daemon (requires config.yaml)
openswarm start
```

--------------------------------

### Service Lifecycle Management

Source: https://context7.com/unohee/openswarm/llms.txt

Code examples for starting and managing the OpenSwarm service, including configuration loading and handling shutdown signals.

```APIDOC
## Service Lifecycle

### Starting the Full Service

Loads configuration, validates it, and starts the main service components (Discord bot, Linear integration, autonomous runner).

#### Request Example

```typescript
import { loadConfig, validateConfig } from './core/config.js';
import { startService, stopService } from './core/service.js';

const config = loadConfig();
const validation = validateConfig(config);

if (!validation.valid) {
  console.error('Config errors:', validation.errors);
  process.exit(1);
}

await startService(config);

process.on('SIGINT', async () => {
  await stopService();
  process.exit(0);
});
```

### macOS launchd Service

Instructions for installing the service on macOS using `launchd`.

#### Command

```bash
npm run service:install
```
```

--------------------------------

### Install and Launch OpenSwarm

Source: https://github.com/unohee/openswarm/blob/main/README.md

Global installation via npm and launching the TUI chat interface.

```bash
npm install -g @intrect/openswarm
openswarm
```

--------------------------------

### Start Pair Session Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!pair start [taskId]` to initiate a new pair session, optionally specifying a task ID.

```bash
!pair start [taskId]
```

--------------------------------

### Example Local Notes

Source: https://github.com/unohee/openswarm/blob/main/templates/TOOLS.md

Record environment-specific details like camera names, SSH hosts, and TTS preferences. This section provides examples of how to structure these notes.

```markdown
### Cameras

- living-room → Main space, 180° wide angle
- front-door → Entrance, motion triggered

### SSH

- home-server → 192.168.x.x, user: admin
- dev-box → user@192.168.x.x

### TTS

- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: Kitchen HomePod

### MCP Servers

- pykis-local: Korea Investment & Securities API
- pykiwoom: Kiwoom Securities API
- playwright: Browser automation
```

--------------------------------

### Example Boot Checklist

Source: https://github.com/unohee/openswarm/blob/main/templates/BOOT.md

Use this markdown format to list sequential steps for service startup. Ensure each step is concise and actionable.

```markdown
# Boot Checklist

1. Sync latest code with git pull
2. Verify dependencies with npm install
3. Confirm environment variables are loaded
4. Report service status to Discord
```

--------------------------------

### Start Autonomous Execution Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!auto start [cron] [--pair]` to start autonomous mode. Optionally specify a cron schedule or the `--pair` flag.

```bash
!auto start [cron] [--pair]
```

--------------------------------

### Install macOS launchd Service

Source: https://context7.com/unohee/openswarm/llms.txt

Install the OpenSwarm service to run automatically on macOS using launchd.

```bash
# Install as system service
npm run service:install
```

--------------------------------

### Start OpenSwarm Service

Source: https://context7.com/unohee/openswarm/llms.txt

Programmatically load, validate configuration, and start the OpenSwarm service, which includes the Discord bot, Linear integration, and autonomous runner. Includes SIGINT handler for graceful shutdown.

```typescript
import { loadConfig, validateConfig } from './core/config.js';
import { startService, stopService } from './core/service.js';

// Load and validate config
const config = loadConfig();
const validation = validateConfig(config);

if (!validation.valid) {
  console.error('Config errors:', validation.errors);
  process.exit(1);
}

// Start service (Discord bot, Linear integration, autonomous runner)
await startService(config);

// Handle shutdown
process.on('SIGINT', async () => {
  await stopService();
  process.exit(0);
});
```

--------------------------------

### Create and Run Pair Pipelines

Source: https://context7.com/unohee/openswarm/llms.txt

Shows how to create and run a PairPipeline with different configurations. Supports default, full, and custom pipelines based on configuration objects, and includes an example task definition.

```typescript
import {
  PairPipeline,
  createDefaultPipeline,
  createFullPipeline,
  createPipelineFromConfig,
  type PipelineConfig,
  type PipelineResult,
} from './agents/pairPipeline.js';
import type { TaskItem } from './orchestration/decisionEngine.js';

// Create default pipeline (Worker + Reviewer)
const defaultPipeline = createDefaultPipeline(3); // max 3 iterations

// Create full pipeline with all stages
const fullPipeline = createFullPipeline({
  maxIterations: 3,
  continueOnTestFail: false,
  skipDocumenterIfNoChange: true,
});

// Create pipeline from config
const configuredPipeline = createPipelineFromConfig(
  {
    worker: { enabled: true, model: 'claude-sonnet-4-20250514', timeoutMs: 1800000 },
    reviewer: { enabled: true, model: 'claude-haiku-4-5-20251001', timeoutMs: 600000 },
    tester: { enabled: true, model: 'claude-haiku-4-5-20251001', timeoutMs: 300000 },
    documenter: { enabled: false, model: 'claude-haiku-4-5-20251001', timeoutMs: 120000 },
  },
  3, // maxIterations
);

// Define task
const task: TaskItem = {
  id: 'task-123',
  source: 'linear',
  title: 'Fix authentication bug in login flow',
  description: 'Users report intermittent login failures...',
  priority: 2,
  projectPath: '/home/user/dev/my-project',
  issueId: 'abc-123',
  issueIdentifier: 'INT-456',
  createdAt: Date.now(),
  linearProject: { id: 'proj-1', name: 'Backend API' },
};

// Run pipeline
const result: PipelineResult = await fullPipeline.run(task, '/home/user/dev/my-project');

console.log({
  success: result.success,
  finalStatus: result.finalStatus,  // 'approved' | 'rejected' | 'failed' | 'cancelled' | 'decomposed'
  iterations: result.iterations,
  totalDuration: result.totalDuration,
  filesChanged: result.workerResult?.filesChanged,
  reviewDecision: result.reviewResult?.decision,
  totalCost: result.totalCost,  // { costUsd: 0.0234, inputTokens: 5000, outputTokens: 1200 }
});
```

--------------------------------

### View OpenSwarm Service Logs

Source: https://context7.com/unohee/openswarm/llms.txt

Use this command to view the logs for the OpenSwarm service. Ensure npm is installed and configured.

```bash
npm run service:logs
```

--------------------------------

### Restart OpenSwarm Service

Source: https://context7.com/unohee/openswarm/llms.txt

Use this command to restart the OpenSwarm service. Ensure npm is installed and configured.

```bash
npm run service:restart
```

--------------------------------

### Start and Control Autonomous Runner

Source: https://context7.com/unohee/openswarm/llms.txt

Programmatically configure and manage the autonomous runner. Integrations like Discord reporters and Linear fetchers can be set up before starting the runner. Manual controls, project management, turbo mode, provider switching, and stats retrieval are available.

```typescript
import {
  startAutonomous,
  stopAutonomous,
  getRunner,
  setDiscordReporter,
  setLinearFetcher,
} from './automation/autonomousRunner.js';
import type { TaskItem } from './orchestration/decisionEngine.js';

// Set up integrations
setDiscordReporter(async (content) => {
  // Send to Discord channel
  await discordChannel.send(content);
});

setLinearFetcher(async (): Promise<TaskItem[]> => {
  const issues = await linear.getMyIssues({ slim: true });
  return issues.map(issue => linearIssueToTask(issue));
});

// Start autonomous runner
const runner = await startAutonomous({
  linearTeamId: process.env.LINEAR_TEAM_ID,
  allowedProjects: ['~/dev/my-project', '~/dev/api'],
  heartbeatSchedule: '*/15 * * * *',  // Every 15 minutes
  autoExecute: true,
  maxConsecutiveTasks: 3,
  cooldownSeconds: 300,
  pairMode: true,
  pairMaxAttempts: 3,
  maxConcurrentTasks: 4,
  worktreeMode: true,           // Isolate tasks in git worktrees
  enableDecomposition: true,
  decompositionThresholdMinutes: 30,
  dailyTaskCap: 6,              // Per-project 5h rolling window cap
  interTaskCooldownMs: 1800000, // 30min between tasks
  defaultAdapter: 'claude',
  defaultRoles: {
    worker: { enabled: true, model: 'claude-haiku-4-5-20251001', timeoutMs: 1800000 },
    reviewer: { enabled: true, model: 'claude-haiku-4-5-20251001', timeoutMs: 600000 },
  },
});

// Manual control
await runner.runNow();            // Trigger immediate heartbeat
runner.pauseScheduler();          // Pause task scheduling
runner.resumeScheduler();         // Resume task scheduling

// Project management
runner.enableProject('/home/user/dev/my-project');
runner.disableProject('/home/user/dev/disabled-project');
runner.getEnabledProjects();      // ['/home/user/dev/my-project']

// Turbo mode (4h auto-expire)
runner.setTurboMode(true);        // 5min heartbeat, 20 daily cap
runner.getTurboMode();            // true/false

// Switch provider at runtime
runner.switchProvider('codex');   // Switch to Codex adapter
runner.switchProvider('claude');  // Switch back to Claude

// Get stats
const stats = runner.getStats();
console.log({
  isRunning: stats.isRunning,
  lastHeartbeat: stats.lastHeartbeat,
  pendingApproval: stats.pendingApproval,
  turboMode: stats.turboMode,
  schedulerStats: stats.schedulerStats,  // { running, queued, completed }
  dailyPace: stats.dailyPace,            // 5h rolling window info
});

// Get queue info
const queued = runner.getQueuedTasks();
const running = runner.getRunningTasks();
const history = runner.getPipelineHistory(50);

// Stop runner
stopAutonomous();
```

--------------------------------

### Delegate Command Usage

Source: https://github.com/unohee/openswarm/blob/main/templates/AGENTS.md

Example usage of the /delegate command to dispatch a Claude instance to another codebase for a specific task.

```bash
/delegate ~/dev/tools/pykis "Check API parameters"
/delegate ~/dev/tools/pykiwoom "Analyze real-time subscription logic"
```

--------------------------------

### View OpenSwarm Service Errors

Source: https://context7.com/unohee/openswarm/llms.txt

Use this command to view error logs for the OpenSwarm service. Ensure npm is installed and configured.

```bash
npm run service:errors
```

--------------------------------

### View OpenSwarm Service Status

Source: https://context7.com/unohee/openswarm/llms.txt

Use this command to view the current status of the OpenSwarm service. Ensure npm is installed and configured.

```bash
npm run service:status
```

--------------------------------

### Uninstall OpenSwarm Service

Source: https://context7.com/unohee/openswarm/llms.txt

Use this command to uninstall the OpenSwarm service. Ensure npm is installed and configured.

```bash
npm run service:uninstall
```

--------------------------------

### Other Utility Commands

Source: https://github.com/unohee/openswarm/blob/main/README.md

Miscellaneous commands for checking CI status, switching providers, accessing memory, and getting help.

```APIDOC
## Other Utility Commands

### GitHub CI failure status

- **Command**: `!ci`

### Switch CLI provider at runtime

- **Command**: `!provider <claude|codex>`
  - `provider`: The provider to switch to ('claude' or 'codex').

### Recent session records (Codex)

- **Command**: `!codex`

### Search cognitive memory

- **Command**: `!memory search "<query>"`
  - `query`: The search query, enclosed in double quotes.

### Full command reference

- **Command**: `!help`
```

--------------------------------

### Stop OpenSwarm Service

Source: https://context7.com/unohee/openswarm/llms.txt

Use this command to stop the OpenSwarm service. Ensure npm is installed and configured.

```bash
npm run service:stop
```

--------------------------------

### Initialize OpenSwarm Project

Source: https://github.com/unohee/openswarm/blob/main/README.md

Cloning the repository and preparing the configuration file.

```bash
git clone https://github.com/unohee/OpenSwarm.git
cd OpenSwarm
npm install
cp config.example.yaml config.yaml
```

--------------------------------

### List All Schedules Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!schedule` to list all configured schedules.

```bash
!schedule
```

--------------------------------

### Display Full Command Reference Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!help` to display the full command reference for the CLI.

```bash
!help
```

--------------------------------

### Initialize and Use Codex Adapter

Source: https://context7.com/unohee/openswarm/llms.txt

Demonstrates initializing the CodexCliAdapter and executing a command via spawnCli. Note that Codex manages Git operations internally.

```typescript
import { CodexCliAdapter } from './adapters/codex.js';
import { spawnCli } from './adapters/base.js';

const adapter = new CodexCliAdapter();

// Codex uses --full-auto mode with managed Git
console.log(adapter.capabilities);
// {
//   supportsStreaming: true,
//   supportsJsonOutput: true,
//   supportsModelSelection: true,
//   managedGit: true,  // Codex manages git operations
//   supportedSkills: [],
// }

const result = await spawnCli(adapter, {
  prompt: 'Refactor the database connection pool',
  cwd: '/home/user/dev/backend',
  model: 'gpt-4',  // Codex uses GPT models
  timeoutMs: 300000,
});

const workerResult = adapter.parseWorkerOutput(result);
```

--------------------------------

### Autonomous Runner Control

Source: https://context7.com/unohee/openswarm/llms.txt

Programmatic control over the autonomous runner, including starting, stopping, and managing its state and configurations.

```APIDOC
## Autonomous Runner Control

### Description
Programmatically control the autonomous runner, including starting, stopping, and managing its state and configurations.

### Methods

- `startAutonomous(options)`: Starts the autonomous runner with specified configuration options.
- `stopAutonomous()`: Stops the autonomous runner.
- `getRunner()`: Retrieves the current runner instance.
- `setDiscordReporter(reporter)`: Sets a function to report events to Discord.
- `setLinearFetcher(fetcher)`: Sets a function to fetch tasks from Linear.

### `startAutonomous` Options

- **linearTeamId** (string) - Optional - The Linear team ID.
- **allowedProjects** (string[]) - Optional - List of allowed project paths.
- **heartbeatSchedule** (string) - Optional - Cron schedule for heartbeats.
- **autoExecute** (boolean) - Optional - Automatically execute tasks.
- **maxConsecutiveTasks** (number) - Optional - Maximum consecutive tasks.
- **cooldownSeconds** (number) - Optional - Cooldown period in seconds.
- **pairMode** (boolean) - Optional - Enable pair programming mode.
- **pairMaxAttempts** (number) - Optional - Maximum attempts for pair mode.
- **maxConcurrentTasks** (number) - Optional - Maximum concurrent tasks.
- **worktreeMode** (boolean) - Optional - Enable worktree isolation.
- **enableDecomposition** (boolean) - Optional - Enable task decomposition.
- **decompositionThresholdMinutes** (number) - Optional - Threshold for decomposition in minutes.
- **dailyTaskCap** (number) - Optional - Daily task limit.
- **interTaskCooldownMs** (number) - Optional - Cooldown between tasks in milliseconds.
- **defaultAdapter** (string) - Optional - Default adapter name.
- **defaultRoles** (object) - Optional - Default roles configuration.
  - **worker** (object) - Optional - Worker role configuration.
    - **enabled** (boolean) - Required - Whether the worker is enabled.
    - **model** (string) - Required - The model to use for the worker.
    - **timeoutMs** (number) - Optional - Timeout for worker tasks.
  - **reviewer** (object) - Optional - Reviewer role configuration.
    - **enabled** (boolean) - Required - Whether the reviewer is enabled.
    - **model** (string) - Required - The model to use for the reviewer.
    - **timeoutMs** (number) - Optional - Timeout for reviewer tasks.

### Runner Instance Methods

- `runNow()`: Triggers an immediate heartbeat.
- `pauseScheduler()`: Pauses task scheduling.
- `resumeScheduler()`: Resumes task scheduling.
- `enableProject(projectPath)`: Enables a project.
- `disableProject(projectPath)`: Disables a project.
- `getEnabledProjects()`: Returns a list of enabled projects.
- `setTurboMode(enabled)`: Toggles turbo mode.
- `getTurboMode()`: Returns the current turbo mode status.
- `switchProvider(adapterName)`: Switches the current adapter.
- `getStats()`: Retrieves runner statistics.
- `getQueuedTasks()`: Returns a list of queued tasks.
- `getRunningTasks()`: Returns a list of running tasks.
- `getPipelineHistory(limit)`: Returns the pipeline history up to a specified limit.

### Request Example

```typescript
import {
  startAutonomous,
  stopAutonomous,
  getRunner,
  setDiscordReporter,
  setLinearFetcher,
} from './automation/autonomousRunner.js';

setDiscordReporter(async (content) => {
  await discordChannel.send(content);
});

setLinearFetcher(async (): Promise<TaskItem[]> => {
  const issues = await linear.getMyIssues({ slim: true });
  return issues.map(issue => linearIssueToTask(issue));
});

const runner = await startAutonomous({
  linearTeamId: process.env.LINEAR_TEAM_ID,
  allowedProjects: ['~/dev/my-project', '~/dev/api'],
  heartbeatSchedule: '*/15 * * * *',
  autoExecute: true,
  maxConsecutiveTasks: 3,
  cooldownSeconds: 300,
  pairMode: true,
  pairMaxAttempts: 3,
  maxConcurrentTasks: 4,
  worktreeMode: true,
  enableDecomposition: true,
  decompositionThresholdMinutes: 30,
  dailyTaskCap: 6,
  interTaskCooldownMs: 1800000,
  defaultAdapter: 'claude',
  defaultRoles: {
    worker: { enabled: true, model: 'claude-haiku-4-5-20251001', timeoutMs: 1800000 },
    reviewer: { enabled: true, model: 'claude-haiku-4-5-20251001', timeoutMs: 600000 },
  },
});

await runner.runNow();
runner.pauseScheduler();
runner.enableProject('/home/user/dev/my-project');

const stats = runner.getStats();
console.log(stats);

stopAutonomous();
```
```

--------------------------------

### Project Build Command

Source: https://github.com/unohee/openswarm/blob/main/templates/HEARTBEAT.md

Standard command to verify project build status.

```bash
pnpm build  # or the appropriate build command for the project
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/unohee/openswarm/blob/main/README.md

Required environment variables for Discord and Linear integration.

```bash
DISCORD_TOKEN=your-discord-bot-token
DISCORD_CHANNEL_ID=your-channel-id
LINEAR_API_KEY=your-linear-api-key
LINEAR_TEAM_ID=your-linear-team-id
```

--------------------------------

### Load and Validate Configuration

Source: https://context7.com/unohee/openswarm/llms.txt

Demonstrates loading configuration from a YAML file and validating its structure. Supports loading from the current directory or a custom path, and expanding paths with tilde notation.

```typescript
import { loadConfig, validateConfig, expandPath } from './core/config.js';

// Load config from config.yaml (auto-finds in cwd)
const config = loadConfig();

// Or load from custom path
const config = loadConfig('/path/to/config.yaml');

// Validate configuration
const validation = validateConfig(config);
if (!validation.valid) {
  console.error('Config errors:', validation.errors);
  // ['Agent "main" project path does not exist: ~/dev/nonexistent']
}

// Expand paths (resolve ~/
const fullPath = expandPath('~/dev/my-project');
// '/Users/username/dev/my-project'

// Expand with relative path resolution
const absolutePath = expandPath('./src', true);
// '/current/working/directory/src'
```

--------------------------------

### OpenSwarm Configuration File Structure

Source: https://context7.com/unohee/openswarm/llms.txt

The main configuration file supports environment variable substitution. It defines adapters, integrations (Discord, Linear, GitHub), agent settings, and autonomous execution parameters.

```yaml
# config.yaml
adapter: claude  # Default CLI adapter: claude or codex

discord:
  token: ${DISCORD_TOKEN}
  channelId: ${DISCORD_CHANNEL_ID}
  webhookUrl: ${DISCORD_WEBHOOK_URL:-}

linear:
  apiKey: ${LINEAR_API_KEY}
  teamId: ${LINEAR_TEAM_ID}

github:
  repos:
    - owner/repo
  checkInterval: 300000  # 5 minutes

agents:
  - name: main
    projectPath: ~/dev/my-project
    heartbeatInterval: 1800000  # 30 minutes
    linearLabel: main
    enabled: true
    paused: false

defaultHeartbeatInterval: 1800000

# Autonomous execution settings
autonomous:
  enabled: true
  pairMode: true
  schedule: "*/15 * * * *"
  maxAttempts: 3
  maxConcurrentTasks: 4
  worktreeMode: true  # Isolate each task in git worktree

  allowedProjects:
    - ~/dev/my-project
    - ~/dev/backend-api

  # Task decomposition (Planner Agent)
  decomposition:
    enabled: true
    thresholdMinutes: 30
    maxDepth: 2
    maxChildrenPerTask: 5
    dailyLimit: 20
    plannerModel: claude-sonnet-4-20250514

  # Per-role configuration
  defaultRoles:
    worker:
      enabled: true
      adapter: claude
      model: claude-haiku-4-5-20251001
      escalateModel: claude-sonnet-4-20250514
      escalateAfterIteration: 3
      timeoutMs: 1800000
    reviewer:
      enabled: true
      model: claude-haiku-4-5-20251001
      timeoutMs: 600000
    tester:
      enabled: false
    documenter:
      enabled: false
    auditor:
      enabled: false

```

--------------------------------

### SessionStart Hook Actions

Source: https://github.com/unohee/openswarm/blob/main/templates/AGENTS.md

A list of actions automatically executed by the SessionStart hook when a new session begins.

```yaml
Actions:
  - Clear tmux scrollback buffer
  - Activate Python virtual environment
  - Display current time and market status (Korean market)
  - Git repository status (branch, recent commits, changes)
  - GitHub PR info (my open PRs, review requests)
  - Linear issues (if project is configured)
```

--------------------------------

### Discord Commands for Autonomous Mode

Source: https://context7.com/unohee/openswarm/llms.txt

Control the autonomous mode via Discord commands, including starting, stopping, triggering heartbeats, approving/rejecting tasks, and toggling turbo mode.

```bash
# Check autonomous status
!auto
```

```bash
# Start autonomous mode (pair mode with default schedule)
!auto start
```

```bash
# Start with custom schedule and pair mode
!auto start "*/30 * * * *" --pair
```

```bash
# Stop autonomous mode
!auto stop
```

```bash
# Trigger immediate heartbeat
!auto run
```

```bash
# Approve pending task
!approve
```

```bash
# Reject pending task
!reject
```

```bash
# Toggle turbo mode
!turbo on
```

```bash
!turbo off
```

```bash
!turbo status
```

--------------------------------

### OpenSwarm Tech Stack Overview

Source: https://github.com/unohee/openswarm/blob/main/README.md

Lists the core technologies and languages used in the OpenSwarm project, including runtime, build tools, and specific libraries.

```markdown
| Category | Technology |
|----------|-----------|
| Runtime | Node.js 22+ (ESM) |
| Language | TypeScript (strict mode) |
| Build | tsc |
| Agent Execution | Claude Code CLI (`claude -p`) or OpenAI Codex CLI (`codex exec`) |
| Task Management | Linear SDK (`@linear/sdk`) |
| Communication | Discord.js 14 |
| Vector DB | LanceDB + Apache Arrow |
| Embeddings | Xenova/transformers (multilingual-e5-base, 768D) |
| Scheduling | Croner |
| Config | YAML + Zod validation |
| Linting | oxlint |
| Testing | Vitest |
```

--------------------------------

### OpenSwarm State and Data Paths

Source: https://github.com/unohee/openswarm/blob/main/README.md

Details the state and data directories used by OpenSwarm, including configuration files and runtime data.

```markdown
| Path | Description |
|------|-------------|
| `~/.openswarm/` | State directory (memory, codex, metrics, workflows) |
| `~/.claude/openswarm-*.json` | Pipeline history and task state |
| `config.yaml` | Main configuration |
| `dist/` | Compiled output |
```

--------------------------------

### Switch Adapters at Runtime

Source: https://context7.com/unohee/openswarm/llms.txt

Shows how to retrieve adapters by name and switch providers dynamically within an AutonomousRunner instance.

```typescript
import { getAdapter } from './adapters/index.js';

// Get adapter by name
const claudeAdapter = getAdapter('claude');
const codexAdapter = getAdapter('codex');

// In AutonomousRunner (via Discord command)
runner.switchProvider('codex');  // !provider codex
runner.switchProvider('claude'); // !provider claude
```

--------------------------------

### Fetch and rebase PR

Source: https://github.com/unohee/openswarm/blob/main/templates/PR_LAND.md

Checks out the PR branch and prepares it for integration via rebase or squash.

```sh
gh pr checkout <PR>
git rebase main  # or squash
```

--------------------------------

### Add New Schedule Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!schedule add <name> <path> <interval> "<prompt>"` to add a new schedule with a name, path, interval, and prompt.

```bash
!schedule add <name> <path> <interval> "<prompt>"
```

--------------------------------

### Add changelog entry

Source: https://github.com/unohee/openswarm/blob/main/templates/PR_LAND.md

Format for documenting changes and attributing contributors.

```text
- Fix something ([#123](url) by [@user](url))
```

--------------------------------

### OpenSwarm Project Structure

Source: https://github.com/unohee/openswarm/blob/main/README.md

Overview of the OpenSwarm project's directory structure, highlighting key modules and their purposes.

```tree
src/
├── index.ts                 # Entry point
├── cli.ts                   # CLI entry point (run, exec, chat, init, validate, start)
├── cli/                     # CLI subcommand handlers
│   └── promptHandler.ts     # exec command: daemon submit, auto-start, polling
├── core/                    # Config, service lifecycle, types, event hub
├── adapters/                # CLI provider adapters (claude, codex), process registry
├── agents/                  # Worker, reviewer, tester, documenter, auditor
│   ├── pairPipeline.ts      # Worker → Reviewer → Tester → Documenter pipeline
│   ├── agentBus.ts          # Inter-agent message bus
│   └── cliStreamParser.ts   # Claude CLI output parser
├── orchestration/           # Decision engine, task parser, scheduler, workflow
├── automation/              # Autonomous runner, cron scheduler, PR processor
├── memory/                  # LanceDB + Xenova embeddings cognitive memory
├── knowledge/               # Code knowledge graph (scanner, analyzer, graph)
├── discord/                 # Bot core, command handlers, pair session UI
├── linear/                  # Linear SDK wrapper, project updater
├── github/                  # GitHub CLI wrapper for CI monitoring
├── support/                 # Web dashboard, planner, rollback, git tools
├── locale/                  # i18n (en/ko) with prompt templates
└── __tests__/               # Vitest test suite
```

--------------------------------

### Configure CLI Adapter

Source: https://github.com/unohee/openswarm/blob/main/README.md

Setting the primary provider in config.yaml.

```yaml
adapter: claude   # "claude" (default) or "codex"
```

--------------------------------

### Manage Daemon Service

Source: https://github.com/unohee/openswarm/blob/main/README.md

Commands for managing the OpenSwarm daemon as a macOS launchd service.

```bash
npm run service:install    # Build and install as system service
npm run service:start      # Start
npm run service:stop       # Stop
npm run service:restart    # Restart
npm run service:status     # Status and recent logs
npm run service:logs       # stdout (follow mode)
npm run service:errors     # stderr (follow mode)
npm run service:uninstall  # Uninstall
```

--------------------------------

### OpenSwarm v0.1.0 Changelog Entry

Source: https://github.com/unohee/openswarm/blob/main/README.md

Describes the initial release (v0.1.0) of OpenSwarm, outlining its core features such as the worker/reviewer pipeline, adapter support, Discord bot, Linear integration, cognitive memory, and web dashboard.

```markdown
### v0.1.0
- Initial release
- Worker/Reviewer pair pipeline
- Claude Code CLI + Codex CLI adapters
- Discord bot control
- Linear integration
- LanceDB cognitive memory
- Web dashboard (port 3847)
- Rich TUI chat interface
```

--------------------------------

### Use Claude CLI Adapter

Source: https://context7.com/unohee/openswarm/llms.txt

Initializes and uses the Claude CLI adapter to spawn processes and parse agent outputs.

```typescript
import { ClaudeCliAdapter } from './adapters/claude.js';
import { spawnCli } from './adapters/base.js';

const adapter = new ClaudeCliAdapter();

// Check availability
const available = await adapter.isAvailable();  // Checks `which claude`

// Build command (internal)
const { command, args } = adapter.buildCommand({
  prompt: '/tmp/prompt.txt',
  cwd: '/home/user/dev/project',
  model: 'claude-sonnet-4-20250514',
  maxTurns: 50,
});
// 'echo "" | claude -p "$(cat /tmp/prompt.txt)" --output-format stream-json --verbose --permission-mode bypassPermissions --model claude-sonnet-4-20250514 --max-turns 50'

// Spawn CLI process
const result = await spawnCli(adapter, {
  prompt: 'Implement the login function with proper error handling',
  cwd: '/home/user/dev/api',
  timeoutMs: 300000,
  model: 'claude-sonnet-4-20250514',
  maxTurns: 50,
  onLog: (line) => console.log(line),
  processContext: { taskId: 'task-123', stage: 'worker' },
});

// Parse Worker output
const workerResult = adapter.parseWorkerOutput(result);
// { success: true, summary: '...', filesChanged: [...], commands: [...] }

// Parse Reviewer output
const reviewResult = adapter.parseReviewerOutput(result);
// { decision: 'approve', feedback: '...', issues: [], suggestions: [] }
```

--------------------------------

### Project Test Command

Source: https://github.com/unohee/openswarm/blob/main/templates/HEARTBEAT.md

Standard command to verify project test suite.

```bash
pnpm test  # or the appropriate test command for the project
```

--------------------------------

### Run Schedule Immediately Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!schedule run <name>` to execute a specific schedule immediately.

```bash
!schedule run <name>
```

--------------------------------

### Direct Pair Run Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!pair run <taskId> [project]` to directly run a pair session for a specific task and project.

```bash
!pair run <taskId> [project]
```

--------------------------------

### OpenSwarm CLI Commands

Source: https://github.com/unohee/openswarm/blob/main/README.md

Common CLI commands for chat, daemon management, and task execution.

```bash
openswarm                        # TUI chat (default)
openswarm chat [session]         # Simple readline chat
openswarm start                  # Start full daemon (requires config.yaml)
openswarm run "Fix the bug" -p ~/my-project   # Run a single task
openswarm exec "Run tests" --local --pipeline # Execute via daemon
openswarm init                   # Generate config.yaml scaffold
openswarm validate               # Validate config.yaml
```

--------------------------------

### Discord Commands for Task Management

Source: https://context7.com/unohee/openswarm/llms.txt

Execute development tasks, list repositories, scan for new ones, view running tasks, and cancel tasks using Discord commands.

```bash
# Run a dev task in a repository
!dev my-repo "Fix the authentication bug in login.ts"
```

```bash
# List known repositories
!dev list
```

```bash
# Scan ~/dev for repositories
!dev scan
```

```bash
# List running tasks
!tasks
```

```bash
# Cancel a running task
!cancel task-abc123
```

--------------------------------

### POST /command/delegate

Source: https://github.com/unohee/openswarm/blob/main/templates/AGENTS.md

Dispatches a Claude instance to perform tasks in a specified codebase path.

```APIDOC
## POST /command/delegate

### Description
Delegates a specific task to a Claude instance operating within a different codebase path.

### Method
POST

### Parameters
#### Path Parameters
- **path** (string) - Required - The local file system path to the target codebase
- **task description** (string) - Required - The task to be performed

### Request Example
/delegate ~/dev/tools/pykis "Check API parameters"
```

--------------------------------

### Manual Daemon Execution

Source: https://github.com/unohee/openswarm/blob/main/README.md

Commands for running the daemon manually or via Docker.

```bash
npm run build && npm start   # Production
npm run dev                  # Development (tsx watch)
docker compose up -d         # Docker
```

--------------------------------

### Switch CLI Provider Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!provider <claude|codex>` to switch the CLI provider between Claude and Codex at runtime.

```bash
!provider <claude|codex>
```

--------------------------------

### List Linear Issues Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!issues` to list all Linear issues within the project.

```bash
!issues
```

--------------------------------

### Run project gates

Source: https://github.com/unohee/openswarm/blob/main/templates/PR_LAND.md

Executes build, linting, and testing scripts to verify code integrity.

```sh
npm run build && npm run lint && npm run test
```

--------------------------------

### View Pair Statistics Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!pair stats` to access statistics related to pair sessions.

```bash
!pair stats
```

--------------------------------

### View Agent Daily Execution Limits Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!limits` to check the agent's daily execution limits.

```bash
!limits
```

--------------------------------

### Linear Integration Commands

Source: https://github.com/unohee/openswarm/blob/main/README.md

Commands for interacting with Linear issues and viewing agent limits.

```APIDOC
## Linear Integration Commands

### List Linear issues

- **Command**: `!issues`

### View issue details

- **Command**: `!issue <id>`

### Agent daily execution limits

- **Command**: `!limits`
```

--------------------------------

### Create temporary branch

Source: https://github.com/unohee/openswarm/blob/main/templates/PR_LAND.md

Initializes a new local branch based on the latest main branch.

```sh
git checkout main
git pull
git checkout -b land-pr-<number>
```

--------------------------------

### Launch OpenSwarm TUI Chat Interface

Source: https://context7.com/unohee/openswarm/llms.txt

Launches the interactive TUI chat interface for conversations with Claude Code. Can also be used for a simple readline chat or with a named session.

```bash
# Launch TUI chat interface (default)
openswarm

# Alternative: simple readline chat
openswarm chat

# Start chat with named session
openswarm chat my-session --tui
```

--------------------------------

### Changelog Attribution Formats

Source: https://github.com/unohee/openswarm/blob/main/templates/CHANGELOG_AUDIT.md

Required syntax for documenting internal and external contributions.

```markdown
- Fixed foo ([#123](https://github.com/owner/repo/issues/123))
```

```markdown
- Added bar ([#456](https://github.com/owner/repo/pull/456) by [@user](https://github.com/user))
```

--------------------------------

### Submit Daemon Task with OpenSwarm CLI

Source: https://context7.com/unohee/openswarm/llms.txt

Submits a task to the running daemon or executes locally with the `--local` flag. Supports options for path, timeout, model, and pipeline execution.

```bash
# Execute via daemon (auto-starts if not running)
openswarm exec "Fix the authentication bug" --path ~/dev/api --pipeline

# Execute locally without daemon
openswarm exec "Update the README" --local --worker-only

# With timeout and model override
openswarm exec "Refactor the database module" \
  --path ~/dev/backend \
  --timeout 900 \
  --model claude-sonnet-4-20250514 \
  --pipeline \
  --verbose
```

--------------------------------

### List Commits Since Last Tag

Source: https://github.com/unohee/openswarm/blob/main/templates/CHANGELOG_AUDIT.md

Displays a one-line summary of all commits made after the specified tag.

```bash
git log <tag>..HEAD --oneline
```

--------------------------------

### Changelog Section Structure

Source: https://github.com/unohee/openswarm/blob/main/templates/CHANGELOG_AUDIT.md

Standardized order for sections within the CHANGELOG.md file.

```markdown
### Breaking Changes
API changes requiring migration

### Added
New features

### Changed
Changes to existing features

### Fixed
Bug fixes

### Removed
Removed features
```

--------------------------------

### Discord Commands

Source: https://context7.com/unohee/openswarm/llms.txt

A comprehensive list of Discord commands for managing tasks, autonomous mode, integrations, and service status.

```APIDOC
## Discord Commands

### Task Management Commands

- `!dev <repo> <task>`: Run a dev task in a repository.
- `!dev list`: List known repositories.
- `!dev scan`: Scan `~/dev` for repositories.
- `!tasks`: List running tasks.
- `!cancel <task-id>`: Cancel a running task.

### Autonomous Mode Commands

- `!auto`: Check autonomous status.
- `!auto start [schedule] [--pair]`: Start autonomous mode.
- `!auto stop`: Stop autonomous mode.
- `!auto run`: Trigger immediate heartbeat.
- `!approve`: Approve a pending task.
- `!reject`: Reject a pending task.
- `!turbo on|off|status`: Toggle turbo mode.

### Linear Integration Commands

- `!issues [session]`: List assigned issues.
- `!issue <issue-id>`: View issue details.
- `!limits`: Check execution limits.

### Scheduling Commands

- `!schedule`: List all schedules.
- `!schedule run <schedule-name>`: Run a schedule immediately.
- `!schedule toggle <schedule-name>`: Toggle schedule enabled/disabled.
- `!schedule add <name> <repo> <cron> <description>`: Add a new schedule.
- `!schedule remove <schedule-name>`: Remove a schedule.

### Other Commands

- `!status [service]`: Check agent status.
- `!pause [service]`: Pause agent.
- `!resume [service]`: Resume agent.
- `!ci`: Check GitHub CI status.
- `!notifications`: Check GitHub notifications.
- `!provider <provider-name>`: Switch CLI provider.
- `!memory search <query>`: Search cognitive memory.
```

--------------------------------

### Discord Commands for Linear Integration

Source: https://context7.com/unohee/openswarm/llms.txt

Manage Linear issues directly from Discord, including listing assigned issues, viewing issue details, and checking execution limits.

```bash
# List assigned issues
!issues
```

```bash
# List issues for specific session
!issues backend
```

```bash
# View issue details
!issue INT-123
```

```bash
# Check execution limits
!limits
```

--------------------------------

### Configure Per-Role Adapter Overrides

Source: https://github.com/unohee/openswarm/blob/main/README.md

Defining specific models and adapters for worker and reviewer roles.

```yaml
autonomous:
  defaultRoles:
    worker:
      adapter: codex
      model: o4-mini
    reviewer:
      adapter: claude
      model: claude-sonnet-4-20250514
```

--------------------------------

### OpenSwarm v0.2.0 Changelog Entry

Source: https://github.com/unohee/openswarm/blob/main/README.md

Highlights key changes in version 0.2.0, including npm publishing, extraction of `@intrect/claude-driver`, autonomous runner improvements, task-state rehydration, and the addition of a `--verbose` flag.

```markdown
### v0.2.0
- Published as `@intrect/openswarm` on npm
- Extracted `@intrect/claude-driver` as standalone zero-dependency package
- Autonomous runner hardening and multi-project orchestration
- Task-state rehydration from Linear comments
- `--verbose` flag for detailed execution logging
- Codex adapter: dropped o-series model override
```

--------------------------------

### Worker/Reviewer Pair Commands

Source: https://github.com/unohee/openswarm/blob/main/README.md

Commands for managing and viewing pair sessions and their history.

```APIDOC
## Worker/Reviewer Pair Commands

### View pair session status

- **Command**: `!pair`

### Start a pair session

- **Command**: `!pair start [taskId]`
  - `taskId`: The ID of the task to start a pair session for.

### Direct pair run

- **Command**: `!pair run <taskId> [project]`
  - `taskId`: The ID of the task to run.
  - `project`: Optional project name.

### Stop a pair session

- **Command**: `!pair stop [sessionId]`
  - `sessionId`: Optional session ID to stop.

### View session history

- **Command**: `!pair history [n]`
  - `n`: Optional number of history entries to display.

### View pair statistics

- **Command**: `!pair stats`
```

--------------------------------

### Discord Commands for Scheduling

Source: https://context7.com/unohee/openswarm/llms.txt

Manage task schedules via Discord, including listing, running, toggling, adding, and removing schedules with specified cron expressions and descriptions.

```bash
# List all schedules
!schedule
```

```bash
# Run a schedule immediately
!schedule run daily-tests
```

```bash
# Toggle schedule enabled/disabled
!schedule toggle daily-tests
```

```bash
# Add new schedule
!schedule add nightly-build ~/dev/api "0 2 * * *" "Run build and tests"
```

```bash
# Remove schedule
!schedule remove nightly-build
```

--------------------------------

### Toggle Schedule Enable/Disable Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!schedule toggle <name>` to enable or disable a schedule.

```bash
!schedule toggle <name>
```

--------------------------------

### Add co-author attribution

Source: https://github.com/unohee/openswarm/blob/main/templates/PR_LAND.md

Standard git trailer for crediting original authors during a squash merge.

```text
Co-Authored-By: User <user@email.com>
```

--------------------------------

### OpenSwarm v0.2.2 Changelog Entry

Source: https://github.com/unohee/openswarm/blob/main/README.md

Notes that version 0.2.2 of OpenSwarm automatically launches the TUI chat interface when run without arguments.

```markdown
### v0.2.2
- `openswarm` without arguments now launches TUI chat directly
```

--------------------------------

### Handle Pair Pipeline Events

Source: https://context7.com/unohee/openswarm/llms.txt

Illustrates how to subscribe to and handle various events emitted by the PairPipeline during its execution. This includes stage lifecycle, iteration progress, pipeline completion, and error events.

```typescript
import { PairPipeline } from './agents/pairPipeline.js';

const pipeline = new PairPipeline({
  stages: ['worker', 'reviewer', 'tester'],
  maxIterations: 3,
  verbose: true,
});

// Stage lifecycle events
pipeline.on('stage:start', ({ stage, context }) => {
  console.log(`Starting ${stage}...`);
});

pipeline.on('stage:complete', ({ stage, result, context }) => {
  console.log(`${stage} completed in ${result.duration}ms, success: ${result.success}`);
});

pipeline.on('stage:fail', ({ stage, result, context, error }) => {
  console.error(`${stage} failed: ${error.message}`);
});

// Iteration events
pipeline.on('iteration:start', ({ iteration, maxIterations, context }) => {
  console.log(`Starting iteration ${iteration}/${maxIterations}`);
});

pipeline.on('iteration:complete', ({ iteration, context }) => {
  console.log(`Iteration ${iteration} completed successfully`);
});

pipeline.on('iteration:fail', ({ iteration, stage, context }) => {
  console.log(`Iteration ${iteration} failed at ${stage}, will retry...`);
});

// Pipeline completion events
pipeline.on('pipeline:complete', (result: PipelineResult) => {
  console.log('Pipeline completed:', result.finalStatus);
});

pipeline.on('pipeline:fail', (result: PipelineResult) => {
  console.error('Pipeline failed:', result.finalStatus);
});

// Stuck detection and halt events
pipeline.on('stuck', ({ reason, suggestion, context }) => {
  console.warn(`STUCK: ${reason}. Suggestion: ${suggestion}`);
});

pipeline.on('halt', ({ confidence, haltReason, sessionId }) => {
  console.warn(`HALT: confidence=${confidence}%, reason=${haltReason}`);
});

// Verbose logging
pipeline.on('log', ({ line }) => {
  console.log(`[verbose] ${line}`);
});

await pipeline.run(task, projectPath);
```

--------------------------------

### POST /command/audit

Source: https://github.com/unohee/openswarm/blob/main/templates/AGENTS.md

Analyzes the codebase for 'BS' patterns such as fake execution or exception hiding.

```APIDOC
## POST /command/audit

### Description
Detects low-quality code patterns and calculates a BS Index based on critical, warning, and minor issues.

### Method
POST

### Response
- **BS Index** (float) - Calculated as (CRITICAL * 10 + WARNING * 3 + MINOR * 1) / file count
```

--------------------------------

### Execute Single Task with OpenSwarm CLI

Source: https://context7.com/unohee/openswarm/llms.txt

Executes a single task through the agent pipeline without requiring a config.yaml file. Specify the task, project path, and optional parameters like model and pipeline stages.

```typescript
// CLI usage
// openswarm run "<task>" -p <project-path> [options]

// Internal implementation (src/runners/cliRunner.ts)
import { runCli } from './runners/cliRunner.js';

await runCli({
  task: "Add error handling to the API endpoints",
  projectPath: "~/dev/my-project",
  model: "claude-sonnet-4-20250514",
  pipeline: true,         // Full pipeline: worker + reviewer + tester + documenter
  workerOnly: false,      // Worker only, no review
  maxIterations: 3,       // Max retry iterations
  verbose: true,          // Enable detailed logging
});

// Expected output:
//   OpenSwarm v0.1.0
//   Project:  ~/dev/my-project
//   Pipeline: worker -> reviewer -> tester -> documenter
//
//   ~ worker...
//   v worker (45.2s)
//   ~ reviewer...
//   v reviewer (12.3s)
//
//   Result: APPROVED
//   Summary: Added try-catch blocks to all API endpoints
//   Files:   src/api/users.ts, src/api/orders.ts
//   $0.0234 | Duration: 58.1s
```

--------------------------------

### Find the Last Release Tag

Source: https://github.com/unohee/openswarm/blob/main/templates/CHANGELOG_AUDIT.md

Retrieves the most recent version tag from the git repository.

```bash
git tag --sort=-version:refname | head -1
```

--------------------------------

### Check Pair Session Status Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!pair` to view the status of the current pair session.

```bash
!pair
```

--------------------------------

### Autonomous Execution Commands

Source: https://github.com/unohee/openswarm/blob/main/README.md

Commands for managing and monitoring autonomous execution modes.

```APIDOC
## Autonomous Execution Commands

### Check execution status

- **Command**: `!auto`

### Start autonomous mode

- **Command**: `!auto start [cron] [--pair]`
  - `cron`: Optional cron schedule string.
  - `--pair`: Optional flag to enable pairing.

### Stop autonomous mode

- **Command**: `!auto stop`

### Trigger immediate heartbeat

- **Command**: `!auto run`

### Approve or reject pending task

- **Command**: `!approve` / `!reject`
```

--------------------------------

### Approve or Reject Pending Task Command

Source: https://github.com/unohee/openswarm/blob/main/README.md

Use `!approve` or `!reject` to approve or reject a pending task.

```bash
!approve
```

```bash
!reject
```