hangar-ide 0.1.2

Orchestration-first IDE for spec-driven AI development

Hangar

The orchestration-first IDE for spec-driven AI development.

Plan specs. Track dependencies. Run agents. Review changes. Ship.

The code editor is the agent. You're the architect.

What is Hangar?

Hangar is a visual control surface for Beads + OpenSpec workflows. Instead of managing specs and task graphs through CLI commands, you get a real-time dashboard that covers the full development lifecycle — from initial idea to shipped feature.

The interface is split into three zones:

• Left sidebar — Ready queue (unblocked tasks) and completed epics
• Main content — Switchable between Specs (browse/manage OpenSpec changes) and Tasks (dependency DAG)
• Bottom panel — Terminal, Review, Timeline, Stats

Everything updates live. When an agent closes a task in the terminal, the DAG redraws, the timeline gains an entry, and stats recalculate — no manual refresh needed.

Specs — Plan What to Build

The Specs tab is a first-class view for browsing and managing OpenSpec changes. Each change is a rich card showing status, artifact availability, and task progress.

Click into any change to see its full detail view with breadcrumb navigation, a summary header with completion ring, and tabbed artifact viewer for Proposal, Design, Specs, and Tasks documents.

Spec Wizard — AI-Powered Planning

The Spec Wizard is a step-by-step flow where you describe what you want to build, an AI agent generates each OpenSpec artifact, and you review and approve at every stage:

Describe intent  ->  Agent drafts Proposal  ->  You review  ->  Approve
                     Agent drafts Specs     ->  You review  ->  Approve
                     Agent drafts Design    ->  You review  ->  Approve
                     Agent drafts Tasks     ->  You review  ->  Approve  ->  Import to Beads

Each stage is a review gate: approve, edit inline, or regenerate with feedback. The wizard chains context — each artifact builds on approved predecessors.

See the Spec Wizard Guide for details.

Tasks — See the Dependency Graph

The Tasks tab renders the full Beads dependency graph using ELK.js with hybrid node design: phase-colored stripes, task number panels, 2-line title wrapping, status pills, and smooth bezier edge routing.

Click any node to highlight its dependency chain and open the detail panel with metadata, dependency navigation with status badges, and close reasons.

9 phase-colored categories (Foundation through Polish) with named aliases shown in legends and tooltips. Ready queue in the sidebar shows unblocked tasks sorted by priority.

Terminal — Run Any Agent

The embedded xterm.js terminal is agent-agnostic. Run any CLI tool:

Agent	Usage
Claude Code	claude "Work on task bd-x1y2"
Codex CLI	codex --full-auto "Implement auth"
Aider	aider --auto-commits
Plain bash	bd close bd-x1y2 --reason "Done"

Expand the terminal to fill the entire main area for focused agent interaction.

Action-to-Terminal Bridge — Sidebar buttons paste pre-formulated prompts into the terminal (e.g., "Claim Task" pastes bd update <id> --claim). The user always presses Enter.

Timeline & Stats — Track Everything

Timeline — Chronological event feed of all task activity (created, claimed, closed) with inline close reasons. Click any event to jump to that task in the DAG.

Stats — Aggregate project metrics at a glance: completion rate, average lead time, throughput, per-epic breakdowns with progress bars.

Close Reasons — Every bd close --reason "..." appears as a lightweight changelog entry in the task detail panel and the timeline feed.

Completed Epics — Sidebar section groups closed epics with task counts. Expand to browse children and navigate the DAG.

See the Project History Guide for details.

Live Reactivity

A filesystem watcher (watchfiles + SSE) detects changes to .beads/issues.jsonl and openspec/changes/**. When an agent closes a task, the DAG updates automatically. No polling, no manual refresh.

Agent closes task in terminal
  -> .beads/issues.jsonl changes on disk
  -> watchfiles detects change
  -> SSE event sent to browser
  -> DAG re-renders, timeline updates, stats recalculate

The Full Loop

1. PLAN     ->  Spec Wizard generates proposal, specs, design, tasks
2. IMPORT   ->  Tasks auto-imported to Beads with dependency inference
3. EXECUTE  ->  Pick from ready queue, run agent in the embedded terminal
4. OBSERVE  ->  DAG updates live as the agent closes tasks
5. REVIEW   ->  Review diffs, approve or iterate
6. CLOSE    ->  Close task with reason, move to next unblocked work
7. REPEAT   ->  Until all tasks are done

Install

Prerequisites

Requirement	Version	Notes
Python	3.12+	Runtime
Beads	latest	Installed automatically by the agent skill on first use
OpenSpec	latest	Installed automatically by the agent skill on first use

You typically don't need to install Beads or OpenSpec yourself — the bundled agent skills guide Claude Code through installing and configuring them when you start your first workflow.

Quick Start

# Install from PyPI
pip install hangar-ide

# Or with uv
uv tool install hangar-ide

# Or with pipx
pipx install hangar-ide

Then navigate to your project and run:

cd ~/projects/my-app
hangar

Hangar starts on http://localhost:8000, auto-discovers your project by finding .beads/ or openspec/ directories, and opens the browser.

Development Setup

To work on Hangar itself, clone the repo and run the backend and frontend dev servers separately:

git clone https://github.com/pyros-projects/hangar.git
cd hangar

# Backend
cd backend && uv sync && cd ..

# Frontend
cd frontend && npm install && cd ..

# Terminal 1: Backend with auto-reload
cd backend && uv run hangar --dev

# Terminal 2: Frontend dev server (hot reload)
cd frontend && npm run dev

In dev mode, open http://localhost:5173 (the Vite dev server proxies API requests to the backend).

First-Run Skill Installer

On first launch, Hangar checks whether your project has Claude Code agent skills installed. If not, an interactive wizard offers to install them:

┌─────────────────────────────────────────────────────┐
│ Agent skills not found in this project.             │
│                                                     │
│ Hangar bundles Claude Code skills for:              │
│     ◆ OpenSpec  — spec-driven change workflow       │
│     ◆ Beads     — task graph & agent memory         │
│                                                     │
│ Skills are installed as .claude/skills/ in your     │
│ project directory.                                  │
└─────────────────────────────────────────────────────┘

  Project: ~/my-project

    1  Install to this project
    2  Choose a different directory
    3  Skip for now
    4  Skip and don't ask again

These skills teach Claude Code how to use the OpenSpec and Beads CLIs — creating specs, managing task dependencies, following the commit-before-close workflow, and keeping tasks.md in sync with the Beads graph.

Skills are plain Markdown files copied to .claude/skills/{openspec,beads}/SKILL.md in your project. They ship inside the Hangar package — no network required.

CLI Flags

hangar [project_path] [options]

positional:
  project_path              Project directory (default: auto-discover)

options:
  -p, --port PORT           Server port (default: 8000)
  --host HOST               Server host (default: 127.0.0.1)
  --dev                     Dev mode with auto-reload
  --no-open                 Don't open browser on startup
  --install-skills [PATH]   Install agent skills and exit
  --no-install              Skip the skill installation wizard

Common usage:

# Start normally (auto-discover project, prompt to install skills)
hangar

# Explicit project path
hangar ~/projects/my-app

# Install skills to a specific project without starting the server
hangar --install-skills ~/projects/my-app

# Headless / CI mode (no browser, no wizard)
hangar --no-open --no-install

# Backend development with auto-reload
hangar --dev

The wizard writes a marker to ~/.config/hangar/no-prompt when you choose "don't ask again". Delete that file to re-enable the prompt.

See the Getting Started Guide for detailed setup, or the Greenfield Tutorial to build a project from scratch.

Architecture

Hangar is a thin orchestration layer. It doesn't replicate the logic of bd or openspec — it shells out to the real CLIs and presents their --json output visually.

Browser  <->  SvelteKit  <->  FastAPI  <->  bd / openspec / git CLIs
  UI           proxy          API            data sources
  xterm.js <----------WebSocket---------->  PTY (bash/agents)
  EventSource <-----------SSE------------>  watchfiles (live reactivity)

The backend auto-discovers your project root by walking up from cwd looking for .beads/ or openspec/ directories.

Tech Stack

Layer	Technology
Frontend	SvelteKit (Svelte 5)
Terminal	xterm.js with fit + web-links addons
Backend	FastAPI (Python 3.12)
PTY	Python pty + asyncio for terminal sessions
File Watcher	watchfiles (Rust notify crate)
Graph Layout	ELK.js
Task Management	Beads (bd CLI)
Spec Management	OpenSpec
Package Manager	uv (Python), npm (Node)
Testing	pytest (250 tests), vitest (48 tests), svelte-check

By the numbers: ~16,000 lines of code across 87 source files, 298 tests, 9 backend services, 12 frontend components.

Documentation

Document	Description
Getting Started	Installation, setup, first launch
Spec Wizard Guide	AI-powered spec generation with review gates
Architecture	System design, services, API endpoints
Embedded Terminal	Terminal + live reactivity architecture
Project History	Timeline, stats, close reasons, archive browsing
Agent Adapters	Working with different CLI agents

Tutorials

Tutorial	Description
Greenfield	Build a project from scratch using the full Hangar workflow
Brownfield	Add Hangar to an existing codebase

Known Limitations

• Single-user — Designed for single-developer use. No authentication or concurrent access handling.
• No rate limiting — For local development this is fine; for shared deployments, add a reverse proxy.

License

MIT