A calm control room for coding agents.
Run a dozen Claude Code or Antigravity agents on your own machines. Fyr tells you only when one needs you.
Install · Features · Docs · Spec · MIT
Running many coding agents at once is easy. Keeping track of them is not: terminal tabs, a question that waited 40 minutes for an answer, a red CI run nobody looked at, a merge you have to remember to press.
Fyr turns that around. It runs Claude Code and Antigravity (agy) sessions on your machines and keeps one list. Threads that need you (a question, a failure, red CI, a merge to approve) rise to Your move. Everything else stays in Moving without you, one live line each, until it is done. Start a thread at your desk and answer its question from your phone. (Fyr is Swedish for lighthouse: it watches everything and lights up only when you have to act.)
-
One inbox for every agent. Each conversation is a thread. Asking, failed, blocked and finished threads come to the top, ordered by what to do: Answer, Approve, Unblock. Snooze, settle, quiet hours and per-project priority keep the list short. Press
?for the keyboard shortcuts. -
Questions become cards. When an agent asks, you get a card with its options. Answer with
12Enter on the desktop or two taps on the phone (skip a question, step back or cancel the card), and the answer goes straight back into the run. Questions from subagents arrive the same way. -
Agents ask, you approve, Fyr acts. An agent never merges or deploys on its own. It requests, and you approve when it suits you (and an optional per-project approval judge can auto-allow routine tool calls and escalate the rest):
- A merge ask reaches you only once CI is green on the commit you will merge.
- A Run card shows the exact command, root included, and runs it on that machine when you press.
- A deploy of a branch builds and switches once you press.
The result goes back to the agent as context.
-
Agents stop reporting CI. Fyr reads branches, multiple PRs per thread, checks and reviews from git and GitHub and shows them on the thread that owns them. It tells the agent when CI fails and can settle the thread when its PRs merge.
-
Agents get tools to work with you. Over MCP an agent can ask you something, request a command or a merge, open a PR, open a change in its own git worktree, wait for a condition (CI green, a PR merged, a quota reset, a time), show you a page or a screenshot, and start or message other threads.
-
Your machine stays usable. Heavy jobs (test suites, builds, e2e runs) are admitted by the CPU and memory they need, and the rest queue. A memory guard pauses runaway work before the kernel's OOM killer acts. On Linux every agent runs in its own cgroup.
-
Agents survive restarts. The launcher holds the agent processes, so a crash, a restart or an update of the daemon does not interrupt a run.
-
Native desktop apps and a full phone client. Run Fyr in a browser, in
Fyr.appon macOS, or infyr-desktopon Linux (window, tray icon and native desktop notifications). Your phone is an installable PWA with push notifications: answer, steer, approve, start a thread with a screenshot, and settle. -
Several machines, one list. Installs find each other on a LAN (mDNS) or over an optional tailnet and pair with an invite code. Every host's threads show in one inbox, a new thread picks which machine runs it, and you can hand a thread over to another provider or another host.
-
Your own agent subscriptions. Fyr drives the
claudeCLI (Claude logins or Anthropic-compatible endpoints) and the Antigravity CLI (agy, Google accounts or Gemini endpoints). Several logins can sit side by side; each thread shows its plan's remaining window and waits cleanly when quota runs out. -
Updates that roll back. Fyr installs only signed CI releases (on the
stablechannel of version tags ormain's green builds). It tests each one on a copy of its database first and goes back to the previous build if the new one is not healthy.
Fyr is v0. Its author uses it every day, and it changes daily. Expect breaking changes, and do not expect database migrations between every pair of builds. It is built for one person who runs many agents in parallel against GitHub. The roadmap is in docs/PLAN.md and the current work in the milestones.
- Linux or macOS. NixOS has a module (and optional
fyr-desktopnative app); macOS hasFyr.appin a DMG (macOS 13+); other Linux (Debian, Ubuntu) has an install script. - Claude Code (
claude, with a Claude account or an Anthropic-compatible endpoint) and/or Antigravity CLI (agy, via ACP, with a Google login or Gemini endpoint). Both sit behind Fyr's CLI adapter seam (decision 0035). - GitHub through
gh, logged in, for the agents' pull requests and change tracking. Projects on other forges still run threads, without it. Installing and updating Fyr need nogh. - Optional: Tailscale, as one route to open Fyr from your phone away from home and to connect machines. Fyr also runs on a single machine or a plain LAN without it.
# flake.nix
inputs.fyr.url = "github:meros/fyr";
# in your NixOS configuration
imports = [ inputs.fyr.nixosModules.fyr ];
services.fyr = {
enable = true;
user = "you"; # agents run as this user, with its logins and repositories
# desktop.enable = true; # optional: native Linux window, tray item and desktop notifications
};Fyr serves http://127.0.0.1:7777. The module also sets up the agents' cgroups and the memory guard. docs/HOST-SETUP.md lists the host settings that help the guard.
Download Fyr.dmg (macOS 13+, Apple Silicon and Intel), drag Fyr into Applications and open it.
First open (Gatekeeper):
Fyr.appis signed with Fyr's own certificate rather than an Apple Developer ID yet. A browser download is quarantined by macOS, so the first launch needs right-click → Open (or System Settings → Privacy & Security → Open Anyway).
Fyr.app registers its background job under Login Items (no admin password needed), opens Fyr in a native window with macOS notifications and a menu-bar icon, walks you through setup in Settings → Setup, and keeps both fyrd and Fyr.app updated automatically. To remove it, choose Uninstall… from the menu-bar icon.
For a terminal or developer install (no Gatekeeper prompt):
git clone https://github.com/meros/fyr && cd fyr
scripts/install-macos.shYou need systemd with cgroup v2, git, curl and claude (gh is for the agents' pull requests; the install needs no login):
sudo apt install git curl gh # gh: see cli.github.com if your release lacks it
git clone https://github.com/meros/fyr && cd fyr
scripts/install-linux.sh --print # shows every file and command, changes nothing
scripts/install-linux.shRun it as yourself, not as root. It downloads the current signed release into ~/.local/share/fyr as you, then asks sudo for the system part, showing each command: the unit fyr.service (it runs as you), the agents' slice, a polkit rule and a small helper. Fyr serves http://127.0.0.1:7777 and updates itself. scripts/install-linux.sh --uninstall removes the unit and the root files. docs/INSTALL.md has the details.
You need Go and Node. The dev shell has both: nix develop.
make build # bin/fyr (the launcher) and bin/fyrd (the daemon, with the web client inside)
make install # puts the build under ~/.local/share/fyr
bin/fyr # starts Fyr on http://127.0.0.1:7777docs/INSTALL.md covers configuration, the phone, more machines and updates.
- Open http://127.0.0.1:7777 (or
Fyr.app/fyr-desktop). Settings → Setup checks your machine and Fyr finds your existingclaudeandagylogins (Settings → Providers). - Press New (or
c), pick a folder, and write what the agent should do. The folder becomes a project. - Go and do something else. When the agent asks, fails or finishes, its thread moves to Your move, and your desktop or phone is notified if you allowed it.
- Answer, steer, or press the card's button. Settle a thread when you are done with it.
fyrd is a Go daemon. It drives the claude CLI (control protocol) and the agy CLI (ACP) behind one adapter interface, keeps every thread as an event log in SQLite, reads git and GitHub, and serves a TypeScript web app with live updates. The browser, the desktop shells (Fyr.app, fyr-desktop) and the phone PWA share that app. A small launcher, fyr, keeps fyrd and the agents running across updates and rollbacks.
Each install is a host (it runs agents), a front (it serves the app and merges the threads of every host it knows), or both. Both is the default.
| Read | For |
|---|---|
docs/INSTALL.md |
Configuration, the phone, more machines, updates |
docs/HOST-SETUP.md |
Host settings for the memory guard (cgroups, swap, oomd) |
docs/SPEC.md |
The full spec: concepts, data model, actions, attention, UX |
docs/API-v0.md |
The HTTP API between fyrd and the web client |
docs/decisions/ |
Architecture decision records |
docs/changes/ |
The change log of the spec, one file per change |
docs/PROCESS.md |
How Fyr is built: spec, red test, code |
design/ |
The design system, brand book and screen mocks |
The screenshots in this README come from the client's mock mode. To make them again, run npm run build && node scripts/readme-shots.mjs in web/.
Issues are welcome. Read docs/PROCESS.md and CLAUDE.md first: every change in behaviour updates the spec and comes with a test.
Pull requests from forks are read, but CI does not run them on its own. The PR gate runs on a self-hosted runner that takes only branches in this repository, so an accepted change is re-run from a branch here.
MIT, see LICENSE. The Geist fonts in web (from the geist package) and in design/settings/fonts are under the SIL Open Font License 1.1 (OFL.txt).
