# 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.

![Hangar — Task DAG with phase-colored nodes, ready queue, and embedded terminal](docs/screenshots/01-overview-dag.png)

## What is Hangar?

Hangar is a visual control surface for [Beads](https://github.com/steveyegge/beads) + [OpenSpec](https://github.com/Fission-AI/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.

![Specs Browser — rich cards with artifact chips, status pills, and progress bars](docs/screenshots/03-specs-browser.png)

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 Detail — breadcrumb navigation, summary card, artifact tabs, rendered markdown](docs/screenshots/04-spec-detail.png)

### 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](docs/spec-wizard.md) 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.

![Task Detail — selected node with dependency highlighting, blocks list, and close reason](docs/screenshots/02-task-detail.png)

**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](https://claude.com/claude-code) | `claude "Work on task bd-x1y2"` |
| [Codex CLI](https://github.com/openai/codex) | `codex --full-auto "Implement auth"` |
| [Aider](https://aider.chat/) | `aider --auto-commits` |
| Plain bash | `bd close bd-x1y2 --reason "Done"` |

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

![Terminal expanded — full-height terminal with tab bar](docs/screenshots/07-terminal-expanded.png)

**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.

![Stats Dashboard — metrics grid, completion bar, per-epic breakdown](docs/screenshots/06-stats.png)

**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](docs/project-history.md) 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](https://www.python.org/) | 3.12+ | Runtime |
| [Beads](https://github.com/steveyegge/beads) | latest | Installed automatically by the agent skill on first use |
| [OpenSpec](https://github.com/Fission-AI/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

```bash
# 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:

```bash
cd ~/projects/my-app
hangar
```

Hangar starts on [http://localhost:8000](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:

```bash
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](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](https://claude.com/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 close-then-commit 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:

```bash
# 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](docs/getting-started.md) for detailed setup, or the [Greenfield Tutorial](docs/tutorials/greenfield.md) 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](https://kit.svelte.dev/) (Svelte 5) |
| Terminal | [xterm.js](https://xtermjs.org/) with fit + web-links addons |
| Backend | [FastAPI](https://fastapi.tiangolo.com/) (Python 3.12) |
| PTY | Python `pty` + `asyncio` for terminal sessions |
| File Watcher | [watchfiles](https://watchfiles.helpmanual.io/) (Rust `notify` crate) |
| Graph Layout | [ELK.js](https://github.com/kieler/elkjs) |
| Task Management | [Beads](https://github.com/steveyegge/beads) (`bd` CLI) |
| Spec Management | [OpenSpec](https://github.com/Fission-AI/OpenSpec) |
| Package Manager | [uv](https://docs.astral.sh/uv/) (Python), npm (Node) |
| Testing | pytest (~260 tests), vitest (57 tests), svelte-check |

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

## Documentation

| Document | Description |
|----------|-------------|
| [Getting Started](docs/getting-started.md) | Installation, setup, first launch |
| [Spec Wizard Guide](docs/spec-wizard.md) | AI-powered spec generation with review gates |
| [Architecture](docs/architecture.md) | System design, services, API endpoints |
| [Embedded Terminal](docs/embedded-terminal.md) | Terminal + live reactivity architecture |
| [Project History](docs/project-history.md) | Timeline, stats, close reasons, archive browsing |
| [Agent Adapters](docs/agent-adapters.md) | Working with different CLI agents |

### Tutorials

| Tutorial | Description |
|----------|-------------|
| [Greenfield](docs/tutorials/greenfield.md) | Build a project from scratch using the full Hangar workflow |
| [Brownfield](docs/tutorials/brownfield.md) | 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
