`, the same scheme and port the client dialled), and only requests that actually arrive from a non-loopback address may present one. A loopback caller keeps the loopback-only rule, so a web page served from some other local port can't borrow an allowed hostname to reach the daemon.\n\n`port` and `allowedHosts` are set exactly like the rest of `remoteAccess` — over the loopback API, human-only; no agent tool can change them. The direct remote listener is API-only: the cockpit itself is not served on it (the trusted-proxy listener above is the one that serves it).\n\nStep-by-step instructions live on the landing site's **Remote access** page ([`site/remote-access.html`](site/remote-access.html)).\n\n## Network\n\n- Your agents' own conversations with Anthropic — or, for a session on the opt-in Codex harness, with whichever provider your Codex CLI is set up to use. They carry your code, as any coding agent's do.\n- A plan-usage poll of `api.anthropic.com/api/oauth/usage` every 60s, only when Claude OAuth credentials exist (`LOOM_SUPPRESS_USAGE_POLLER=1` stops it).\n- npm-installed daemons check `registry.npmjs.org` for `loomctl` updates every 6h (none from source; not switchable off, `LOOM_NPM_REGISTRY` only redirects). New worker worktrees run your package manager's install.\n- Opt-in and able to carry session content: the Telegram companion, outbound alert webhooks, Agent Runs completion webhooks (they post the run's id, status, result and error — the result is agent output), and any Connection you bind.\n- Opt-in downloads that carry no session content: a profile with document conversion pip-installs `markitdown` from PyPI into Loom's own Python venv, and the GitHub capability downloads a pinned `github-mcp-server` release from github.com.\n\n## How it works\n\nA single local **daemon** owns everything durable — the sessions, the PTY host that drives `claude`, the Fastify HTTP/WS gateway, an SQLite store, git, and the vault auto-committer. An ordinary project agent gets **no git write on its tool surface**: checkout, commit and push live behind a human-only REST route, or behind one of the deliberate, opt-in grants above (the Elevated Operator, the companion's git lever). Read that as the tool-surface boundary it is rather than a sandbox — a worker still has an ordinary shell inside its own worktree, which is how it commits its work in the first place; what the boundary buys you is that no *agent tool* can push, and no Loom tool or route can reach a repo the session wasn't given. 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.\n\nGive 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.\n\nA run, end to end:\n\n1. **You hand a lead a goal** — say *\"add rate-limit middleware and cover it with tests.\"*\n2. **It decomposes the goal** into cards on the project board and **delegates** each to a worker spawned on its own git worktree branch.\n3. **Workers build in parallel** — each drives a real `claude` session, commits to its branch, and reports back up when it's done or blocked.\n4. **The lead reviews each diff** and merges what passes through a build gate; a failing gate bounces the card back to the worker instead of merging.\n5. **The board and vault stay versioned** with the code, so the whole run stays legible after the fact.\n\nYou watch it live in **Mission Control** — the fleet, context meters, an activity feed, and an attention queue that surfaces a merge the moment it needs your review.\n\n\n ![\"Loom](\"docs/images/architecture.svg\")
\n\nThe monorepo (pnpm + Turbo) is three packages:\n\n- **`packages/shared`** — the contract: types (Project / Topic / Session / Task + the session FSM),\n one config-resolution mechanism, and the ws/REST protocol.\n- **`packages/daemon`** — owns everything durable: SQLite, the PTY host, the gateway, the\n project-scoped task MCP server, git, and the vault auto-committer.\n- **`packages/web`** — the stateless React/Vite viewport.\n\n## Your companion\n\nBeyond the orchestration fleet, Loom can run a **companion** — a single long-lived agent you chat with directly, over **Telegram** or an in-app web chat, on the same daemon-owned real-`claude` runtime. It's a personal assistant rather than a project worker: it stays running across restarts, holds the thread of an ongoing conversation, and reaches you on the channel you started from.\n\nThe companion grows with you. It curates a **durable memory** of what matters — your preferences, ongoing context, things it said it would follow up on — and recalls it silently at the start of each conversation. It sets its own **reminders**, both one-shot (\"remind me in 20 minutes\") and recurring (on a cron schedule), which fire back to your chat as a nudge. It writes its own private **skills** for tasks worth repeating, and — when you enable a cadence — proactively checks in only when there's something genuinely worth surfacing.\n\nWhat it may actually *do* is yours to grant, one lever at a time. Out of the box it talks; grant it more and it can commit and push on your behalf, against either the project's vault or its code repo — the target resolved by the daemon, never a path the agent supplies, and a push always asks you first. If you'd rather not hand out levers one by one, there's an opt-in **lead mode** that gives one companion full capability across every project; the UI states that blast radius plainly before you turn it on.\n\nYou set it up and run it from a single **Companion** page: chat on one side; configuration, channels, memory, reminders, capability grants, and its editable persona on the other. Every inbound message is treated as untrusted input, the bot token is encrypted at rest, senders are allowlisted, enrollment uses one-time DM pairing codes, and all configuration is human-only — never something the chat-reachable agent can change about itself. It can't be driven through a raw terminal either: text pushed at a companion session over the API or a terminal socket is refused outright, so nothing can put words in your mouth for it to act on.\n\n## Screenshots\n\n\n ![\"Loom's](\"docs/images/screenshot-terminals.png\")
The terminal cockpit — a lead orchestrating its worker fleet, every pane a real interactive claude session with its own context meter and branch.
\n\n\n ![\"Loom's](\"docs/images/screenshot-board.png\")
The per-project task board — a kanban you and the agents share. On a multi-repo project each card carries the repo it's routed to, so one board can drive several checkouts.
\n\n\n ![\"Loom's](\"docs/images/screenshot-gates.png\")
The Gates page — every merge, worker self-check, and deploy run across all projects, sharing one concurrency budget, with the failing test named on a rejection.
\n\n\n ![\"A](\"docs/images/screenshot-terminal.png\")
A live session terminal — the real interactive claude, attached over a WebSocket.
\n\n\n ![\"Loom's](\"docs/images/screenshot-companion.png\")
The Companion — chat with a long-lived personal agent over Telegram or in-app web chat, on the same durable runtime.
\n\n\n ![\"Loom's](\"docs/images/screenshot-skills.png\")
The editable skill store — read, edit, and three-way-merge Loom's shipped skills; changes apply on the next session spawn.
\n\n\n ![\"Loom's](\"docs/images/screenshot-platform.png\")
The Platform operator and suggest-only Workspace Auditor — set up your workspace and review your own sessions, on a deliberately narrow tool surface.
\n\n\n ![\"Loom's](\"docs/images/screenshot-projects.png\")
The Projects page — create and manage projects and their agents, each agent carrying an editable startup prompt injected as its first turn.
\n\n## Docs & links\n\n- [`CLAUDE.md`](CLAUDE.md) — architecture, the validated gate-free spawn recipe, and the load-bearing\n invariants (start here to hack on Loom).\n- [`docs/decisions/`](docs/decisions) and [`docs/adr/`](docs/adr) — the decision records the\n `@decision` anchors in the source point at; [`docs/investigations/`](docs/investigations) holds the incident write-ups.\n- [`docs/releasing.md`](docs/releasing.md) — the packaging, versioning, and release runbook.\n- [`CHANGELOG.md`](CHANGELOG.md) — notable changes per version.\n\n## Contributing & community\n\nContributions are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) to get set up and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) for the community standards we hold. To report a security issue, follow the process in [`SECURITY.md`](SECURITY.md) rather than opening a public issue.\n\n## License\n\nLoom is released under the [MIT License](LICENSE).\n","readmeFilename":"README.md"}![\"Loom\"](\"docs/images/logo.svg\"){kind=logo}
\n\n### Orchestrate a fleet of real Claude Code agents — durable, review-gated, and entirely on your machine\n\n![\"License:](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
![\"CI\"](\"https://github.com/DanielC000/loom/actions/workflows/ci.yml/badge.svg\"){kind=icon}
![\"Release\"](\"https://img.shields.io/github/v/release/DanielC000/loom?sort=semver\")
![\"Node](\"https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg\"){kind=icon}
![\"Loom's](\"docs/images/hero.png\")