░█░█░█▀▄░█▀█░▀█▀░▀█▀░█░█
░█▄█░█▀▄░█▀█░░█░░░█░░█▀█
░▀░▀░▀░▀░▀░▀░▀▀▀░░▀░░▀░▀

Headless Claude Code runner

wraith — issues
┌─ Issues (triage) ──────────────────────┐
│                                         │
│  ● REG-142  Fix auth token refresh      │
│  ○ REG-143  Add rate limiting to API     │
│  ○ REG-144  Update user onboarding       │
│                                         │
│  [f] Run  [/] Search  [q] Quit          │
└─────────────────────────────────────────┘
  → Spawning Claude run for REG-142...

"Pick an issue. Press f. Claude takes it from here."

wraith — runs
┌─ Runs ──────────────────────────────────┐
│                                         │
│  ● abc1  REG-142  ██████████░  running  │
│  ✓ def2  REG-138  ██████████  completed │
│  ✗ ghi3  REG-140  ██████░░░░  failed    │
│                                         │
└─────────────────────────────────────────┘
  ✓ def2 → github.com/regeno/api/pull/87

"Real-time run tracking. PR link when it's done."

wraith pair
  ▄▄▄▄▄▄▄  ▄▄▄▄  ▄▄▄▄▄▄▄  
  █ ▄▄▄ █ █▀▄▄█  █ ▄▄▄ █  
  █ ███ █ ▄▀█▄▀  █ ███ █  
  █▄▄▄▄▄█ █ █ █  █▄▄▄▄▄█  
   ▄▄▄▄▄ ▄██▀▄▀   ▄ ▄ ▄   
  █▄▄▄▄▄█ ▀▀▀▀▀  █▄▄▄▄▄█  
  Listening on ws://192.168.1.42:7280
  ● Status: Paired!

"Scan. Pair. Control from your pocket."

What it does

◈Linear Issues

Browse triage, search across your workspace, view full details with comments and attachments. Press f to start a Claude run.

◧Projects

View active projects, drill into project issues, track progress. Start runs directly from project context.

▶Headless Runs

Spawn detached Claude Code sessions that work in git worktrees. Each run gets its own branch, creates a PR when done.

⚙Smart Prompts

AI-generated prompts from issue context — title, description, comments, attachments. Anthropic, OpenAI, or Together backends.

◉Pair Mode

Start a WebSocket server, scan a QR code from the Android companion app, and remote-control wraith from your phone.

⊕Notifications

Get Slack or Telegram alerts when runs complete, fail, or crash. Never miss a finished PR.

How it works

  ┌─────────────┐
  │  Linear     │
  │  Issue      │
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │  wraith     │
  │  TUI / CLI  │
  └──┬──────┬───┘
     │      │
     │      │ WebSocket
     ▼      ▼
  ┌──────┐ ┌─────────┐
  │Claude│ │ Android  │
  │ Code │ │ App      │
  └──┬───┘ └─────────┘
     │
     ▼
  ┌──────────┐
  │  GitHub   │
  │  PR       │
  └──────────┘
1

Issue → Prompt

Wraith fetches the full issue from Linear — description, attachments, comments. An AI-powered prompt is generated from the context (or a basic template if no API key).

2

Prompt → Run

A git worktree is created at .wraith/worktrees/ for branch isolation. A detached Claude Code process spawns in the worktree. Run metadata is stored in SQLite, logs stream to .wraith/runs/.

3

Run → PR

When Claude finishes, it pushes the branch and creates a pull request. Wraith updates the Linear issue status and notifies you via Slack or Telegram.

Commands

wraith --help

Wraith — headless Claude Code runner

Usage:

wraithOpen TUI
wraith initCreate wraith.json config
wraith issue <id> --runStart a run for an issue
wraith runsList active runs
wraith runs <prefix>Show run detail
wraith retry <prefix>Retry a failed/crashed run
wraith archive <prefix>Archive a completed/failed run
wraith logs <prefix>Tail logs for a run
wraith watchWatch run state transitions live
wraith pairStart pair mode (WebSocket + QR)

Run prefixes are the first 8 characters of the run ID.

TUI keyboard shortcuts
1-5Jump to screen
j / kNavigate lists
EnterSelect / expand
/Search issues
fFire off run
mMove issue state
RRetry failed run
xArchive run
rRefresh
EscBack
qQuit

Configuration

wraith.json
{
  "linear_token": "lin_api_...",
  "base_branch": "main",
  "workspace": "my-workspace",
  "prompt": {
    "provider": "anthropic",
    "api_key": "sk-ant-..."
  },
  "notifiers": [
    { "type": "slack", "webhook_url": "..." }
  ],
  "pair": { "port": 7280, "tunnel": true }
}

Per-project config — created by wraith init

Wraith looks for wraith.json in your project root, plus any .env variables. Bun auto-loads .env files — no extra setup.

SettingRequired
linear_tokenYes
anthropic_api_keyNo
base_branchNo
prompt.providerNo

If no prompt provider is configured, a basic template is used instead of AI-generated prompts.

Your terminal, your pocket

9:41▂▅▇
◈ wraith
●REG-142

Fix auth refresh

○REG-143

Rate limiting

○REG-144

User onboarding

IssuesRunsEvents

Scan a QR code from wraith pair and your Android phone becomes a remote control.

Browse issues. Start runs. Move statuses. Watch events stream in real time.

Works on LAN out of the box. Add "tunnel": true to wraith.json for access from anywhere via Cloudflare.

{
  "pair": {
    "port": 7280,
    "tunnel": false
  }
}

wraith.json

Headless server setup

Wraith is designed to run headless on a remote server so Claude Code can work autonomously while you monitor from anywhere.

1Provision a server

Ubuntu 24.04 LTS, 8 GB RAM minimum, 2+ vCPUs, 50 GB+ SSD. Claude Code sessions are memory-hungry.

2Harden & create user

Enable UFW firewall (SSH only), install fail2ban, create a dedicated claude user with sudo access.

3Install the stack

Install Bun, Git, and Claude Code CLI. Clone your project, install dependencies, authenticate Claude Code with your Max subscription.

4Run wraith in tmux

Launch wraith in a tmux session so it survives SSH disconnects. Set up Telegram or Slack notifications to monitor runs from anywhere.

claude@vps:~
$ tmux new -s wraith
$ cd ~/my-project
$ bunx wraith-cli

Get started

Prerequisites

Bun

v1.1+

Git

wraith creates worktrees for each run

Linear

account + API key

Claude Code

CLI installed globally

1

Run

$bunx wraith-cli

Run wraith directly with Bun. No install needed.

2

Configure

$wraith init

Walks you through setting up your Linear API key, Anthropic key, and base branch. Creates a wraith.json in your project.

3

Launch

$wraith

Opens the TUI dashboard. Or go headless: wraith issue REG-123 --run

Or install globally: bun install -g wraith-cli