GitHub - j-asefa/loop: Loop: your coding agents, from your phone

Your coding agents run in a terminal on your computer. Loop puts their work on your phone: a feed of finished results you can read and reply to, questions they need answered, and approvals they're waiting on — what needs you always on top. No account, no server, no app store. Loop runs on your own machine, pairs with a QR scan, and connects to the harnesses you already use — Codex, Claude Code, Pi, OpenCode, Antigravity, Muse Code, Grok Build, or any ACP agent. Your agents keep working while your phone is away.

Needs you: approve, answer or continue	Feed: finished work as results

Result: read and reply	Saved: results worth keeping, labelled

Agent profile: one agent's work	Your profile: a history of your prompts

Screenshots use illustrative sample data, captured from Loop’s UI. Regenerate them with node scripts/readme-screenshots.mjs after building the UI.

Why Loop

🗂️ A record of results, not a chat log. Finished answers arrive as cards in one Feed (what needs you on top, then Done, Working, Queued, Threads, Replies); plans, diffs, command output and traces stay one tap away. Run several agents and conversations at once and follow them through the Feed, Projects and Search. Phone notifications arrive when a result is ready, not for every tool call. See workspace and notifications.
🔌 The harnesses you already have. loop discovers Codex, Claude Code, Pi, OpenCode, Antigravity, Muse Code and Grok Build on your computer and connects their native adapters in one workspace; custom ACP agents can be added too. Each keeps its own context, tools, sign-in and model configuration, including local models through Pi or OpenCode. Loop verifies the harness billing policy and never switches billing methods after a failure. See harnesses.
🏠 On your own computer: no account, no server. Agents run on your machine and keep working after your phone disconnects. Scan a QR code, pair in your phone's browser and add Loop to your home screen: no app store and no account signup, on iPhone and Android. loop start launches a Cloudflare Quick Tunnel through a pinned, hash-verified cloudflared, so your phone reaches your computer from anywhere without port forwarding, a domain, a VPN or a Cloudflare account. Restarts and upgrades keep the address and your paired phone; if it changes (after loop stop or a reboot), run loop pair and scan again. Only paired devices can sign in, and you can revoke them. Traffic is HTTPS but not end-to-end encrypted: with the default Quick Tunnel, Cloudflare terminates TLS, so use --public-url with your own TLS proxy if that matters to you. See pairing and SECURITY.md.
🔖 Save what matters. Save any result or message from its Feed card or inside its thread; saving a reply keeps the result card it produced with it. Saved, under Your profile, is one searchable list, newest first, with optional short labels such as "Chosen approach". Reply to a saved item to quote it back into its thread, so it is the latest thing the agent reads. See Saved.
↩️ Reply to any message, or just part of it. Loop quotes the message you picked, or only the lines you highlight, in front of your reply, so that exact update is back in front of the agent even if the harness's own history no longer has it. Mid-run, API, Codex, Claude Code, Pi and Muse Code agents support live replies; OpenCode, Antigravity, Grok Build and ACP queue replies for the next turn.
⏱️ Built for checking in, not sitting in. Each Feed card offers the one action its thread is waiting for (approve, answer, continue a draft or review a result) and opens at that message. A "while you were away" card sums up what finished, failed or needs you. Remind me, Send later and Queue after this task pick work up when the agent is free, and scheduled sends reuse their idempotency key, so a retry after a crash never sends twice.
🤝 Teams. A manager agent delegates to worker agents. Presets cover Review code changes, Ask an LLM council, Build a feature and Investigate a bug, and you can build a custom team from existing agents. Review and merge your GitHub pull requests in the Pull requests tab. See teams.
📶 Built for flaky phone connections. Loop records each send before dispatching it, never automatically replays an uncertain one, and catches up on missed updates after a reconnect. See architecture.
🧪 Several computers, one workspace (experimental). Fleets connect companion machines and are off unless you start Loop with --fleet. See fleets.

Setup

Loop runs on macOS and Linux. You need:

Node.js 24. The package accepts Node 22.19 or newer, but CI tests Node 24.
Python 3.8+ on Linux, for command supervision.
At least one coding harness installed and signed in.
A persistent disk, and a computer that stays awake while you use Loop from your phone.

Git is used for agents working in Git repositories, and Docker only for container execution. Loop downloads cloudflared for the phone connection itself.

npm install -g @j-asefa/loop
loop start

To update an npm installation later, run loop upgrade --from @j-asefa/loop@latest; see Pair your phone for what an upgrade keeps.

To work on Loop itself, build from source instead.

loop start prints a single-use pairing code. Scan it with your phone's camera:

The terminal screenshot uses an isolated fixture tunnel; its pairing link is no longer active.

Install on your phone

On your computer, run loop start. It starts the workspace and displays a pairing QR code.
Scan the QR code with your phone's camera. The link opens Loop's pairing page in your default mobile browser. Tap Pair and open Loop.
In the browser, open Share and choose Add to Home Screen. On Android browsers, this may appear as Install app or Add to Home screen in the browser menu.
Open Loop from the new home screen icon.

The computer must stay awake for phone access. Pairing links are single use and expire after two minutes; run loop pair for a fresh code. loop restart and loop upgrade keep the Quick Tunnel address; after loop stop or a reboot it can change, so scan a new code and add the new page to your home screen. See pairing and recovery.

Use a coding harness

Install Codex, Claude Code, Pi, OpenCode, Antigravity, Muse Code or Grok Build on your computer, configure its model provider (or sign in for a cloud account), then run loop in your project directory. Loop discovers supported installed harnesses and connects their direct native adapters. Each harness uses your existing model configuration and credential home; cloud accounts only need a fresh sign-in if they cannot be verified. Sign-in and runtime status are also available in Settings → Provider connections.

loop
loop start --project /absolute/path/to/project

Each harness keeps its native tools and context. Agents owned by the same user in one Loop workspace can discover, message and hand work to one another across harnesses, with shared file references and durable delivery receipts. Team managers can also delegate work. Antigravity currently supports individual conversations; see its setup and limitations. Inspect threads and resume held messages from each profile’s Agent mail tab. Codex, Claude Code, Pi and Muse Code support live steering; OpenCode, Antigravity, Grok Build and ACP queue follow-ups.

The workspace and pairing are available while each harness is verified independently. Missing harnesses are not installed automatically. A failed account check leaves that harness unavailable without blocking the others.

Manage OpenCode and Pi provider credentials from Settings → Provider connections → Harnesses → Manage providers. Add an OpenRouter or OpenAI key, or use a provider's sign-in flow, and Loop refreshes that harness's model choices. Keys stay in each harness's native store. See model provider settings.

Use local models

Use Pi or OpenCode connected to a local model server, such as Ollama, LM Studio or llama.cpp. Loop uses the harness's existing model configuration, so a local-model agent does not require a paid model API or subscription.

Start your local model server and load a model suitable for tool use and coding.
Configure and select that model in Pi or OpenCode. Confirm it works in the harness's CLI first.
From your project directory, connect that harness to Loop:
```
loop pi
# Or, if you use OpenCode:
loop opencode
```
In Loop, create an agent using that harness's connection. Select your local model from its model catalog, or use native-default to follow the harness's default.

Keep the model server running and reachable from the computer or container running the harness. Pi and OpenCode retain their native tools and conversation context; Loop provides the same phone workspace and result feed.

Pair your phone

Start a laptop workspace with loop start and scan its QR code with your phone's camera.
Create an agent with an enabled connection and project. The computer must stay awake; work continues when the phone disconnects.
If the Quick Tunnel address changes (after loop stop or a reboot, not after loop restart), run loop pair and scan again with your phone’s camera.

loop status
loop pair
loop logs --follow
loop stop

The paired app shows agents and conversations from your computer and enrolled fleet companions in one Feed. Choose each new agent's destination in Model & connection; every agent shows where it runs. See unified agents and Feed.

To update a source checkout, run git pull and bash install while Loop keeps running, then loop restart. loop restart replaces only the application: a separate connection service keeps cloudflared, the Quick Tunnel address and your paired phone, and the restarted application uses the same project, harness, provider and billing settings. It refuses while runs are active unless you pass --force. With the login service installed, loop restart restarts the application service the same way.

loop upgrade does this in one command from any directory: it installs the package from the repository's remote main (or --from PACKAGE; npm installs use loop upgrade --from @j-asefa/loop@latest) while Loop keeps running, then restarts into the new build at the same address. A failed install leaves the running workspace alone. It does not use or modify a local Loop checkout. loop stop stops everything, including the tunnel; the next start can get a new address.

The laptop and Docker companion both use device pairing. See pairing and recovery.

Develop and contribute

npm run build
npm run test:all

See development and verification for browser, packaging and container checks. Automated harness fixtures verify Loop's behavior; they do not establish authenticated provider compatibility or physical-phone acceptance.

Try an experiment before merging with loop preview create NAME. It creates a separate branch and paired design workspace with sample data. Use loop preview rebuild NAME as you iterate, or --mode working for a full runtime preview. See experiment previews.

Use the documentation index for detailed guides and AGENTS.md for task-specific contributor context.

Security

Pairing is how a device signs in; the tunnel address alone grants nothing. Treat pairing links and QR codes like passwords, and revoke unfamiliar devices with loop devices revoke ID. SECURITY.md covers the security model, device access and how to report a vulnerability.

Build from source

The CLI supports macOS/Linux and declares Node >=22.19. The build produces the web app and dist/cli.js.

git clone https://github.com/j-asefa/loop.git loop
cd loop
npm ci
npm run build

Run bash install from the checkout to build and create the loop command. The installer runs npm ci, builds Loop and links loop into a writable directory on your PATH. If none is writable, it uses ~/.local/bin and prints the PATH command needed for your shell. Keep the checkout in place while using this installation. For a portable installation instead, run npm pack and install the resulting tarball with npm install -g /path/to/j-asefa-loop-0.1.0.tgz. Without linking or installing, invoke the CLI directly as node dist/cli.js <command>.

Run with Docker and pair your phone

Use docker compose -f compose.companion.yaml up --build -d, then docker compose -f compose.companion.yaml exec loop-companion loop pair. No host Node installation or server .env is needed. See Docker companion pairing for persistent state, runtime scope and management commands.

License

Loop is licensed under the Apache License 2.0. Dependencies retain their upstream licenses.