Bosun Documentation

Bosun is an open-source autonomous supervisor for AI coding workflows. It watches task execution, routes work across agent executors (Copilot, Codex, Claude), handles retries/failover, automates PR lifecycle, and keeps you in control through Telegram, WhatsApp, and a full-featured control center.

New to Bosun? Start with the Quick Start guide — it takes less than 5 minutes.

Why Bosun?

AI coding agents are fast, but unattended loops are expensive:

Silent failures — agents crash with no notification
Repeated retries — same error looping without progress
Stale worktrees — merge drift and orphaned branches
Disconnected notifications — no visibility into what's happening

Bosun is the control plane that keeps delivery moving: task routing, monitored orchestration, conflict/PR lifecycle automation, and live bot control.

What's New in 0.36

GitHub Projects v2 Integration: Full read/write support for GitHub Projects v2, including status sync and custom field mapping.
Enhanced Security: Issue trust guard to prevent prompt injection attacks.
Library Management: New Library tab for managing prompts, agent profiles, and skills.
Task Attachments: Support for task and session uploads.
Workspace Isolation: Agents now use the workspace repo root instead of the developer repo.
UI & Setup Improvements: Web UI parity with terminal wizard, redesigned landing page, and visual polish across the dashboard.
Advanced Configuration: Support for multiple API connection profiles per executor and enhanced Jira configuration parity.

Core Capabilities

Capability	Description
Multi-Executor Routing	Weighted distribution across Copilot, Codex, and Claude with automatic failover
Smart PR Flow	Creates PRs, monitors CI, auto-rebases, merges on green
Self-Healing	Autofix patterns, circuit breakers, heartbeat-based stale recovery
Task Boards	Internal board + GitHub Issues + GitHub Projects v2 + Jira adapters
Telegram Control	30+ bot commands, Mini App with 7 tabs, sentinel watchdog
Multi-Agent Coordination	Shared state, atomic claims, heartbeat liveness, stale sweeps
Container Isolation	Docker, Podman, and Apple Container support with concurrent limits

Documentation Guide

Quick Start

Install, configure, and launch your first fleet in under 5 minutes.

Configuration

Complete reference for .env, JSON config, executors, and env var overrides.

CLI Reference

Every flag, command, and option documented with examples.

Architecture

How the supervisor, orchestrator, and agents fit together.

Integrations

GitHub, Telegram, Jira, WhatsApp, Docker, Cloudflare — all covered.

Requirements

Node.js 18+ (22 recommended)
git installed and on PATH
GitHub CLI (gh) — recommended for PR operations
OS: Linux, macOS, and Windows fully supported
Shell: Bash for .sh wrappers, PowerShell (pwsh) for .ps1 wrappers