Raw capture — raw/barnstormer.md

url: https://github.com/2389-research/barnstormer date_fetched: 2026-07-05 backfilled: true

Agentic spec builder — an event-sourced specification management tool with an AI agent swarm and a real-time web UI.

barnstormer helps you build software specifications collaboratively with AI. You describe what you want to build, and a swarm of specialized agents brainstorm ideas, organize plans, identify risks, and generate architecture diagrams — all in real time through an interactive web interface.

# From GitHub (requires Rust toolchain)
cargo install --git https://github.com/2389-research/barnstormer
# Or clone and build
git clone https://github.com/2389-research/barnstormer.git
cd barnstormer
cargo build --release

Prebuilt binaries for Linux, macOS (Intel + Apple Silicon), and Windows are available on the Releases page.

A native macOS wrapper now lives in crates/barnstormer-tauri/. It launches Barnstormer's existing Axum UI in an embedded local runtime and stores desktop data under macOS Application Support instead of assuming a terminal-managed .env.

Build the app bundle with:

cargo tauri build --bundles app --config crates/barnstormer-tauri/tauri.conf.jsonThe desktop setup flow opens a native settings window first if no provider key is configured, then launches the main Barnstormer window after saving at least one provider key. More detail is in docs/desktop-app.md. For release-grade macOS signing and the required GitHub secret contract, see docs/release-signing-secrets.md.

# Configure at least one LLM provider
cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY
# Start the server (opens browser automatically)
barnstormer start
# Or start without opening a browser
barnstormer start --no-open
# Check if barnstormer is running
barnstormer status
# Import a spec from any file (DOT, YAML, markdown, plain text)
barnstormer import path/to/file.md
barnstormer import design.dot --format dot
barnstormer import --text "Build a CLI task manager"
cat notes.txt | barnstormer import -

The server runs at http://127.0.0.1:7331 by default.

Four crates in a Cargo workspace, plus a binary entrypoint:

Binary entrypoint: src/main.rs

All mutations flow through event sourcing:

Command → SpecActor → Event → SpecState (in-memory)
                         │
                         ├─→ JSONL log (durable)
                         ├─→ SQLite index (queryable cache)
                         └─→ SSE broadcast (real-time UI)

State is materialized by replaying events through a reducer. The JSONL log is the source of truth; SQLite serves as a queryable cache. On startup, barnstormer recovers all specs from persisted events.

The SwarmOrchestrator runs a team of specialized AI agents that collaborate on your spec. Each agent has its own event receiver and a focused role:

The default swarm runs 4 agents (Manager, Brainstormer, Planner, DotGenerator). The Critic role is defined and available but not activated by default.

Agents communicate through 7 tools:

• read_state— Read current spec state summary
• write_commands— Submit spec-mutating commands (create/update/move/delete cards, update spec core)
• emit_narration— Post reasoning to the activity feed
• emit_diff_summary— Mark a step as finished with a change summary
• ask_user_boolean/- ask_user_multiple_choice/- ask_user_freeform— Ask the user questions (CAS-protected to prevent concurrent questions)

The UI is built with Askama templates, HTMX, and SSE for real-time updates without full page reloads.

Layout:

• Nav rail(left) — Spec list, provider status, new spec button, import button
• Command bar(top) — Spec title, view toggles, agent controls (start/pause/resume), undo
• Canvas(center) — Swappable views:- Document— Auto-generated markdown from spec data
• Board— Kanban-style drag-and-drop lanes with SortableJS

• Diagram— DOT graph rendered with Viz.js

• Chat rail(right) — Conversation transcript, question cards, and message input

• Agent LEDs— Colored status indicators showing which agents are running, paused, or stopped

SSE events (card changes, transcript updates, agent status) trigger HTMX partial re-renders to keep the UI in sync.

Copy .env.example to .env and configure:

Specs can be exported in three formats:

• Markdown— Human-readable document with spec details and cards organized by lane
• YAML— Structured data export of the full spec state
• DOT— Graphviz diagram source showing card relationships and flow

Export via the web UI (/web/specs/{id}/export/markdown|yaml|dot) or the API.

When BARNSTORMER_AUTH_TOKEN is set, API routes require Authorization: Bearer <token>.

Subscribe to /api/specs/{id}/events/stream for real-time updates:

spec_created, spec_core_updated, card_created, card_updated, card_moved, card_deleted, transcript_appended, question_asked, question_answered, agent_step_started, agent_step_finished, undo_applied, snapshot_written

# Run all tests
cargo test --all
# Run with clippy
cargo clippy --all-targets -- -D warnings

Tests cover domain logic, persistence, crash recovery, API routes, auth middleware, SSE streaming, agent tools, swarm orchestration, and an integration smoke test (tests/smoke.rs).

barnstormer/
├── src/main.rs                    # Binary entrypoint (CLI, server startup)
├── crates/
│   ├── barnstormer-core/          # Domain types, events, commands, state, exporters
│   │   └── src/
│   │       ├── actor.rs           # SpecActor (command processing, event broadcast)
│   │       ├── command.rs         # Command definitions (tagged enum)
│   │       ├── event.rs           # Event definitions and payload types
│   │       ├── state.rs           # SpecState reducer
│   │       ├── card.rs            # Card model (idea, task, plan, decision, constraint, risk)
│   │       ├── transcript.rs      # Transcript entries
│   │       └── export/            # Markdown, YAML, DOT exporters
│   ├── barnstormer-store/         # Persistence layer
│   │   └── src/
│   │       ├── jsonl.rs           # JSONL event log
│   │       ├── snapshot.rs        # State snapshots
│   │       ├── sqlite.rs          # SQLite index
│   │       ├── recovery.rs        # Crash recovery
│   │       └── manager.rs         # StorageManager orchestration
│   ├── barnstormer-server/        # HTTP server and web UI
│   │   └── src/
│   │       ├── routes.rs          # Route definitions
│   │       ├── web/               # Web UI handlers
│   │       ├── api/               # JSON API handlers
│   │       ├── auth.rs            # Bearer token middleware
│   │       └── config.rs          # Server configuration
│   └── barnstormer-agent/         # AI agent system
│       └── src/
│           ├── swarm.rs           # SwarmOrchestrator (agent lifecycle, round-robin)
│           ├── context.rs         # AgentRole enum, per-agent context
│           ├── client.rs          # LLM provider adapters
│           ├── import.rs          # LLM-powered spec import (any text → structured spec)
│           └── mux_tools/         # 7 agent tools (read, write, narrate, ask)
├── static/                        # CSS, JS (board.js, style.css)
├── templates/                     # Askama HTML templates
├── tests/smoke.rs                 # Integration smoke test
└── .env.example                   # Environment variable template

• All code files start with a 2-line ABOUTME:comment describing the file's purpose
• IDs use ULID(universally unique, lexicographically sortable)
• All mutations go through event sourcing: Command → Event → State
• Commands use #[serde(tag = "type")]— agents must produce{"type": "CreateCard", ...}
• Broadcast channel (4096 capacity) for event distribution
• Question handling uses CAS (compare-and-swap) to prevent concurrent agent questions

Built by 2389 Research, Inc. · GitHub · Email · Twitter · LinkedIn · Bluesky

© 2026 2389 Research, Inc.