# Hangar


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


![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.

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

Initialize a new project

![Initialize a new project](docs/screenshots/hangar_init.png)

Open your browser to http://localhost:8000 and use hangar's included terminal to start your agent

Try a simple prompt to get a feel

```bash
create a web based snake game. use openspec and beads.
```

![Start your agent](docs/screenshots/hangar_start.png)

Check out the specs as they are generated

![Check out the specs](docs/screenshots/hangar_specs.png)

Check out the tasks and how they depend on each other

![Check out the tasks](docs/screenshots/hangar_tasks.png)

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


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