A local-first cockpit for real Claude Code sessions

Loom is a local-first AI project workspace that drives the real interactive claude — the same terminal session you'd run by hand, not a headless one-shot — and keeps it durable. Sessions are owned by a daemon on your machine, so closing the window never kills the work. Around those sessions Loom binds your Obsidian vault and a per-project task board into a single view, and lets one lead agent decompose a goal, delegate to workers on isolated branches, review their diffs, and merge. It even self-hosts: Loom is built using Loom.

• 🖥️ Real Claude Code sessions, not headless. Loom drives the genuine interactive claude over a PTY (node-pty) — never claude -p / headless one-shots. Sessions are resumable and outlive any viewer, so a closed tab or a reboot doesn't lose the thread.
• ⛓️ Multi-agent orchestration. A lead session plans, delegates to worker sessions on isolated git worktree branches, reviews each diff, and merges through a gate. Workers report up; the lead holds the whole picture. Loom even orchestrates its own development with this loop.
• 🔒 Local-first by design. Everything durable lives on your machine: a daemon bound to loopback only (127.0.0.1), an SQLite store, your git checkouts, and your vault. No cloud service sits between you and your work.
• ✦ Vault-backed knowledge. Design notes, decisions, and session logs live in an Obsidian vault woven alongside the code, and Loom auto-commits vault writes so the knowledge layer stays versioned with the work.
• ◧ A task board agents can use. Tasks are a first-class, project-scoped surface backed by an MCP server, so agents read the board, create cards, and move work through columns as part of the same loop you watch — rendered as a per-project kanban.
• ❯ The terminal cockpit. A stateless React/Vite web viewport attaches over WebSockets and detaches freely: Mission Control, the task board, live terminals, runs, and git — one phosphor-on-dark instrument panel.
• 🌐 Opt-in per-worker browser testing. A worker profile can be granted its own isolated headless Playwright browser, so QA-style sessions can drive a running app and verify UI before reporting back.
• 🚀 Guided onboarding. A built-in Setup Assistant greets you on first run and stays one click away ("Set up Loom"). It helps you create and configure your projects, agents, and profiles, pick your skills and workflow, and can set them up on your behalf — confirming the big moves first, on a deliberately narrow, safe tool surface.

You need Node 22+ and a working claude CLI on your machine. Install Loom globally from npm (published as loomctl) — that gives you the loom command:

npm i -g loomctl
loom            # boots the daemon (loopback only) and opens the cockpit in your browser

loom with no arguments starts the daemon in the foreground and opens your browser; press Ctrl-C to stop. To manage a background daemon, use the subcommands:

loom start --detach   # run the daemon in the background (writes a PID file under ~/.loom)
loom status           # is it running? — prints version, URL and PID (exit non-zero if stopped)
loom stop             # stop it gracefully and clean up
loom restart          # stop, then start (honors --detach/--port/--no-open)
loom open             # open the browser to a running daemon
loom update           # update to the latest release (npm i -g loomctl@…), then restart

loom update upgrades the global install and restarts the daemon; loom update --channel beta switches to (and remembers) the beta track. When a newer release is available the cockpit also shows an "update available" banner you can act on from the UI.

To have Loom autostart in the background on login, register it with your OS service manager:

loom service install     # register autostart (systemd --user / launchd / Task Scheduler)
loom service status      # is it registered? + is the daemon running?
loom service uninstall   # remove the autostart registration

install runs loom start --no-open under the OS service manager, which owns keep-alive/restart — a systemd --user unit on Linux, a launchd LaunchAgent on macOS, and a per-user Task Scheduler logon task on Windows (no admin required). It is idempotent (re-installing replaces cleanly) and honors --port. So far only the Windows path has been verified end-to-end on real hardware; the macOS and Linux artifacts are generated to spec and structurally tested but still need a live check on a Mac/Linux host.

Common flags: -p, --port <n> (default 4317, or LOOM_PORT), --no-open, -d, --detach, -v, --version, -h, --help. Prefer not to install? Run it once with no install via npx loomctl (same flags and subcommands, e.g. npx loomctl status).

For a hands-off setup, the repo ships two installer scripts (install.sh for macOS/Linux/WSL, install.ps1 for Windows). They check for Node 22+ (and print a guide if it's missing — they do not download Node for you), run npm i -g loomctl, optionally register autostart, and launch Loom — all idempotent (safe to re-run; npm i -g upgrades in place):

# macOS / Linux / WSL
curl -fsSL https://raw.githubusercontent.com/DanielC000/loom/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/DanielC000/loom/main/install.ps1 | iex

Because curl … | sh and irm … | iex have no interactive prompt, drive optional steps with flags (local-file runs) or env vars (piped runs):

⚠ Piping a script straight to a shell runs unreviewed code. The one-liners above fetch the installers from this repo over HTTPS (raw GitHub) and execute them. If you'd rather inspect first, clone the repo and run them by local path (sh install.sh / pwsh -ExecutionPolicy Bypass -File install.ps1), or download the script, verify its SHA-256 checksum, then run it. (A vanity/Pages URL may front these raw links later; the raw-GitHub URLs above resolve today.)

pnpm is the contributor toolchain. From a clone of the repo:

pnpm install
pnpm build          # builds the shared contract first
pnpm daemon         # the daemon on http://127.0.0.1:4317 (loopback only)
pnpm web            # the viewport on http://127.0.0.1:5317

Open http://127.0.0.1:5317 and you're in the cockpit. See docs/releasing.md for the packaging and release flow.

A single local daemon owns everything durable — the sessions, the PTY host that drives claude, the Fastify HTTP/WS gateway, an SQLite store, read-only git, and the vault auto-committer. The web viewport is stateless: it attaches to a session over a WebSocket and detaches freely, while the session keeps running on the daemon whether or not anyone is watching.

Give a lead agent a goal and it decomposes the goal into tasks, spawns workers — each on its own worktree branch, each driving a real Claude Code session — then reviews each diff, merges what passes, and keeps the vault and board versioned alongside the code. Plan, delegate, review, merge.

The monorepo (pnpm + Turbo) is three packages:

• packages/shared — the contract: types (Project / Topic / Session / Task + the session FSM), one config-resolution mechanism, and the ws/REST protocol.
• packages/daemon — owns everything durable: SQLite, the PTY host, the gateway, the project-scoped task MCP server, read-only git, and the vault auto-committer.
• packages/web — the stateless React/Vite viewport.

The per-project task board — a kanban you and the agents share, with live worker status and branch on each card.

A live session terminal — the real interactive claude, attached over a WebSocket.

• CLAUDE.md — architecture, the validated gate-free spawn recipe, and the load-bearing invariants (start here to hack on Loom).
• docs/releasing.md — the packaging, versioning, and release runbook.
• CHANGELOG.md — notable changes per version.

Contributions are welcome. Please read CONTRIBUTING.md to get set up and CODE_OF_CONDUCT.md for the community standards we hold. To report a security issue, follow the process in SECURITY.md rather than opening a public issue.

Loom is released under the MIT License.