<div align="center">

# 🚄 specrails-desktop

### The local cockpit for shipping software with AI agents

**Draft specs by talking to Claude or Codex → drag them onto execution rails → watch the pipeline ship — all from one window, on your laptop, with every dollar tracked.**

[![npm version](https://img.shields.io/npm/v/specrails-desktop?color=4f46e5&label=npm&logo=npm&logoColor=white&style=flat-square)](https://www.npmjs.com/package/specrails-desktop)
[![license](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)](LICENSE)
[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white&style=flat-square)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white&style=flat-square)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-19-61dafb?logo=react&logoColor=black&style=flat-square)](https://react.dev)
[![Desktop](https://img.shields.io/badge/Desktop-Tauri-ffc131?logo=tauri&logoColor=black&style=flat-square)](https://tauri.app)
[![providers](https://img.shields.io/badge/agents-Claude%20%2B%20Codex-ff7a59?style=flat-square)](#-bring-your-own-agent)

[Quick start](#-quick-start) · [Features](#-what-you-can-do) · [Architecture](#%EF%B8%8F-how-its-built) · [Docs](#-documentation) · [Desktop app](#%EF%B8%8F-desktop-app)

</div>

---

## 🌟 What is this?

**Specrails Desktop** (`specrails-desktop`) turns *"I'll just let the AI do it"* into a workflow you can **see, steer, and trust**. It's the desktop app for specrails — a local-first dashboard and CLI that sits on top of [**specrails-core**](https://github.com/fjpulidop/specrails-core) and gives you **one window for all your projects**:

- 💬 Shape a spec in conversation with an AI, or generate one in a single shot.
- 🛤️ Drag specs onto **execution rails** and run them — one job at a time per project, in parallel across projects.
- 🤖 Watch the **Architect → Developer → Reviewer → Ship** pipeline stream live.
- 💰 See exactly **what each agent cost you** this week, per provider, per ticket.

> 🔒 **100% local. Single user. No accounts. No telemetry leaves your machine.**
> Your code stays on your laptop — nothing moves unless **you** spawn an agent against it.

---

## ✨ What you can do

### 📝 Turn ideas into specs

| | |
|---|---|
| 🗣️ **Explore** | Describe what you want in a chat; a **live draft** rebuilds itself every turn. Save it as a *draft ticket* and resume later, or commit when it looks right. First-token latency is tuned to feel electric. |
| ⚡ **Quick** | Already know what you want? Generate a full spec in one shot — optionally enriched with a **Contract Layer** of exact names, data shapes, invariants, and a file-touch list so the downstream agents don't reinvent anything. |
| 🌐 **From a website** | *Add Spec → From a website* opens an **embedded browser**. Navigate, hover-select an element or drag a rectangle, and the screenshot + DOM + applied CSS become attachments. The desktop build ships its own Chromium, so it works **offline**. |
| 💥 **SMASH** | Explode a big epic into a family of sub-specs in one click — children carry short summaries on their cards. |
| 🔁 **Continue Editing** | Reopen any draft / todo / backlog spec back in Explore, resuming the original conversation if there was one. |
| 🪟 **Compare** | Drag a spec modal to the screen edge → a picker of your todo specs slides in on the other side. Pick one and review them **side by side**, tablet-style. |

### 🚀 Run the pipeline

| | |
|---|---|
| 🛤️ **Execution rails** | Each rail is an independent lane. Within a project, jobs run **one at a time** (rails let you queue and organise the work); true parallelism is **across projects**. Each rail carries its own **agent profile** (which agents, which models, how tasks route). |
| 🧩 **Agent profiles** | A per-project, declarative catalog that tells the implement pipeline which agents to run and at what model — snapshotted per job so concurrent rails stay isolated. |
| 📡 **Live job detail** | A premium ticket-identity header, live duration ticker, incremental turns/tokens, and authoritative cost on exit. |
| 🔌 **Plugins** | A per-project marketplace of MCP-based integrations (**Serena** semantic code-nav bundled today). Additive by design — installing plugin N+1 never disturbs plugin N. |

### 💸 Track every cent

| | |
|---|---|
| 📊 **Analytics** | Every billable AI invocation — across rails, Quick, Explore, AI edits, SMASH, and file summaries — is recorded for **both Claude and Codex**. Burn-rate hero, daily timeline, top tickets, model breakdown, cost-vs-turns scatter. |
| 🧮 **Honest numbers** | Claude cost is the provider-billed figure; Codex cost is **estimated** from a local rate-card (the CLI doesn't report it) and clearly flagged with a `~`. Token totals include the cache tiers, so the figures actually reconcile. |
| 📤 **Exports** | One-click CSV/JSON, plus per-ticket spending deep-links. |

### 🛠️ Make it yours

| | |
|---|---|
| 🖥️ **Terminal panel** | A real VS-Code-style bottom panel (`Cmd/Ctrl+J`) powered by `node-pty` + xterm.js — WebGL rendering, search, ligatures, image inline, drag-drop paths, and OSC 133 shell integration. |
| 🎨 **Themes** | Five built-ins — `specrails` (default), `dracula`, `aurora-light`, `obsidian-dark`, `matrix` — applied before React hydrates (no flash). |
| 🧭 **Code explorer** | A read-only, non-developer-friendly file tree + Monaco viewer with plain-language AI summaries and *"touched by AI"* provenance chips. |
| 💬 **Minimizable chats** | Park an Explore or AI-Edit session into a dock chip and pick it back up later — never lost across refreshes or project switches. |

---

## 🤖 Bring your own agent

specrails-desktop treats **Claude Code** and **Codex CLI** as first-class, interchangeable providers through a single `ProviderAdapter` contract — no manager ever branches on `provider === 'X'`.

| | 🟣 Claude Code | 🟢 Codex CLI |
|---|:---:|:---:|
| Native streaming | ✅ | ✅ |
| Native session resume | ✅ | ✅ |
| Native cost reporting | ✅ | ⚠️ estimated via rate-card |
| Native OTEL telemetry | ✅ | 🔧 synthesized by the app |
| Agent profiles | ✅ | — |

A project can install **one or both**. When both are present, the UI lets you pick the engine per spec, per rail, or per terminal launch. Adding a third provider is *one file + one registry entry* — see [`docs/internals/`](docs/internals/).

---

## 🖼️ How it looks

```
┌──────────┬───────────────────────────────────────────────────┐
│          │  Dashboard · Jobs · Analytics · Agents · ⚙        │
│   Arc    │ ──────────────────────────────────────────────── │
│  side-   │                                                   │
│   bar    │   📋 SpecsBoard          │   🛤️  Rails             │
│          │   (your specs)          │   (execution lanes)     │
│ projects │                         │                         │
│  ● proj  │   #1  Login flow ●      │   ▶ Rail 1   #1 #2     │
│  ○ proj  │   #2  Webhook retry     │     [profile: default]  │
│          │   #3  Cost limits  ●    │                         │
│  ➕ Add   │   #4  Draft idea  ✎     │   ▶ Rail 2   running    │
│          │                         │     [profile: budget]   │
│   ⚙      │                         │                         │
└──────────┴───────────────────────────────────────────────────┘
                 ⌨️  Terminal panel  (Cmd/Ctrl + J)
```

---

## 🚀 Quick start

```bash
# 1️⃣  Install
npm install -g specrails-desktop

# 2️⃣  Start the app
specrails-desktop start

# 3️⃣  Add a project from the CLI…
specrails-desktop add /path/to/your/project

# …or click “➕ Add project” in the dashboard sidebar at
#   http://127.0.0.1:4200
```

If a project doesn't have specrails-core yet, a **3-step setup wizard** (Configure → Install → Done) installs it for you — one flow, no tier picker, ~1 minute on a warm cache.

> 💡 **Prefer a desktop app?** Grab a signed macOS or Windows build — see [Desktop app](#%EF%B8%8F-desktop-app). It bundles the server, so there's no separate `start`.

### 🧑‍💻 The `specrails-desktop` CLI

```bash
specrails-desktop start | stop | add | remove | list   # manage the app
specrails-desktop implement #42                         # run a specrails verb
specrails-desktop --status                              # manager status
specrails-desktop --jobs                                # recent job history
specrails-desktop --project <name|path>                 # target a project
specrails-desktop --help                                # full reference
```

When the app is running, the CLI talks to it over HTTP + WebSocket; when it isn't, it spawns the agent directly. Either way you get streamed logs.

---

## 📦 Prerequisites

- 🟩 **Node.js 20+**
- 🤖 **At least one AI CLI** on your `PATH`:
  - **[Claude Code](https://claude.com/claude-code)** — the `claude` binary, signed in (via Claude subscription login or an `ANTHROPIC_API_KEY`).
  - **[Codex CLI](https://developers.openai.com/codex)** ≥ 0.128.0 — the `codex` binary. Run `codex login` or set `OPENAI_API_KEY`.
- 🌿 **git**
- 🧪 *(optional)* **`uv`** — only if you want the Serena plugin
- 📦 **specrails-core** ≥ 4.6.0 in the project for Codex, ≥ 4.2.0 for Claude-only *(the wizard installs it)*

The provider is chosen **per project at install time** and is immutable afterward. On macOS the desktop app resolves Homebrew/Volta/nvm paths for you.

---

## 🏗️ How it's built

A clean **three-layer TypeScript monorepo** — one Express process runs in *Super mode* and manages every project.

```
🗄️  server/   Express 5 + WebSocket + SQLite (better-sqlite3)   · the brain
🎨  client/   React 19 + Vite + Tailwind v4                      · the dashboard
⌨️  cli/      specrails-desktop command bridge                   · the terminal door
```

```
~/.specrails/
├── desktop.sqlite                   # project registry
├── manager.pid                      # running server PID
└── projects/<slug>/
    ├── jobs.sqlite                  # per-project DB (jobs, analytics, chats)
    └── …                            # snapshots, telemetry, terminals, summaries
```

**Highlights under the hood:**

- 🔗 **One WebSocket** multiplexes everything; every project-scoped message carries a `projectId`, injected by a `boundBroadcast` closure — managers need zero changes.
- 🧱 **Per-project isolation** — each project gets its own SQLite, queue manager, and chat manager.
- 🖥️ **Terminals** stream over a *dedicated* WebSocket so PTY throughput can't starve the event stream.
- 🌐 **Embedded browser** via Playwright (CDP capture) for the *"From a website"* flow.
- 📦 **Desktop** via Tauri, with optionally-bundled Node, Git, and Chromium runtimes so it runs fully offline.

> 📖 Want the deep dive? CLAUDE.md and [`docs/internals/`](docs/internals/) document the adapter contract, REST surface, migrations, and the OpenSpec workflow.

---

## 🛠️ Development

```bash
git clone https://github.com/fjpulidop/specrails-desktop.git
cd specrails-desktop
npm install                        # root deps (server + CLI)
cd client && npm install && cd ..  # client deps (separate tree)
npm run dev                        # 🚀 server :4200 + client :4201, hot reload
```

| Script | What it does |
|--------|--------------|
| `npm run dev` | Server (4200) + client (4201) with hot reload |
| `npm run dev:desktop` | Desktop app (Tauri) in dev mode |
| `npm run build` | Production build (server + client + CLI) |
| `npm test` | Vitest suite (server + CLI) + core-compat check |
| `npm run test:coverage` | Server coverage (mirrors the CI gate) |
| `npm run test:client` | Client Vitest suite |
| `npm run ci` | Everything CI runs: typecheck + tests + both coverage gates |

🛡️ **Coverage is a hard gate** — **70 % global**, **80 % server**, **80 % client**. Local runs must clear the same bars before pushing.

- 🌍 `4200` — Express API + WebSocket
- ⚡ `4201` — Vite dev server (proxies `/api` and `/hooks` to 4200)

---

## 🖥️ Desktop app

Desktop builds for **macOS (Apple Silicon)**, **Windows (x64)**, and **Windows (arm64)** are published at:

> 📥 `https://specrails.dev/downloads/specrails-desktop/latest/`

The macOS build is **signed + notarized**. The Windows installers are **unsigned in v1** — SmartScreen flags them, so click **More info → Run anyway**. (Authenticode signing is a planned follow-up.)

`npm run build:desktop` produces the `.app` / `.dmg` / `.exe`, but does **not** assemble the bundled runtimes — that app falls back to your system PATH and downloads a Playwright Chromium on first use. To build a self-contained app the way CI does (**macOS arm64 only**):

```bash
# Bundle Node 22 + a relocatable Git, then build
npm run build:desktop:local

# …and bundle Chromium too, so "Add Spec from a website" works fully offline
# (one-time ~150 MB Playwright Chromium download)
BUNDLE_CHROMIUM=true npm run build:desktop:local
```

> ℹ️ Local builds are **unsigned** — Gatekeeper warns; right-click → Open, or `xattr -dr com.apple.quarantine <App>.app`. Signed + notarized installers come only from the `desktop-release` CI workflow.

---

## 🔒 Security model

- 🏠 Binds to `127.0.0.1` only — **do not expose to a network**.
- 🔑 An app token is **auto-generated on first run** and persisted to `~/.specrails/desktop.token` (mode `0600`). Every `/api/*` route requires it (except `/api/health` and `/api/token`), and WebSocket upgrades carry it as a subprotocol. The browser client fetches it same-origin — there's nothing to configure.
- 🧷 Parameterised SQL everywhere — never string-interpolated.
- 🧬 Reserved files in your project (`.mcp.json`, `.specrails/plugins/state.json`, `.specrails/profiles/.user-preferred.json`) are mutated **surgically** — read → modify only owned keys → atomic temp+rename — so adding plugin N+1 never disturbs plugin N.

---

## 📚 Documentation

**User guides**

| Guide | What it covers |
|-------|----------------|
| 🏁 [Getting started](docs/getting-started.md) | Install, register a project, run your first pipeline |
| 📝 [Creating specs](docs/creating-specs.md) | Quick vs Explore, drafts, SMASH, Compare, Continue Editing |
| 🚀 [Running pipelines](docs/running-pipelines.md) | Rails, jobs, agent profiles, plugins |
| 💰 [Tracking cost](docs/tracking-cost.md) | Analytics, exports, per-ticket spending |
| 🎨 [Customising the app](docs/customizing.md) | Themes, settings, telemetry, kill switches |
| ⌨️ [Terminal panel](docs/terminal.md) | Shortcuts, shell integration, drag-and-drop |
| 🧑‍💻 [CLI reference](docs/cli.md) | Every command grouped by task |
| 🟢 [Codex notes](docs/codex.md) | Auth, sandbox, estimated-cost caveats, rollback |

**Platform notes** — 🍎 [macOS](docs/platforms/macos.md) · 🪟 [Windows](docs/platforms/windows.md)

**Extending** — 🧩 [`docs/internals/`](docs/internals/): architecture, REST reference, ops runbook, adding a provider.

---

## ☕ Support

If specrails-desktop saves you time, you can buy me a coffee on **Ko-fi** — it funds the open-source ecosystem. 💜

[![Donate on Ko-fi](https://img.shields.io/badge/Donate-Ko--fi-FF5E5B?logo=kofi&logoColor=white&style=flat-square)](https://ko-fi.com/D1D81Y002C)

---

## 📄 License

[MIT](LICENSE) © [Javier Pulido](https://github.com/fjpulidop)

<div align="center">
<sub>Built with TypeScript, React, Express & a lot of ☕ — and shipped by the agents it orchestrates. 🚄</sub>
</div>
