Flock's MCP server uses stdio and opens no network listener. On macOS, the optional quota LaunchAgent runs a persistent flk quota watch process that refreshes quota on a 15-minute cadence and at known reset deadlines. Ask your agent to obtain consent before installing it; flk quota uninstall-agent or flk uninstall removes it.
Coordinate Claude Code, Codex and Gemini CLI profiles.
Work in Claude Code, Codex or Gemini CLI. Say “delegate,” name a provider when it matters, or ask the flock for a review. Your agent handles routing, handoffs, and the local record through Flock.
Version 0.7.21-alpha. macOS and Linux. Binaries are currently unsigned. Review the install steps.
Preview the install prompt
Install Flock on this machine using the current runbook at https://flk.dev/install.md. Before changing anything, explain what you plan to install, where it will write, and the risk of the unsigned release. Verify the download and wait for my approval before installing. Pause whenever I need to complete a provider login. When you finish, check that my flock is ready and tell me about anything that still needs attention.
Profiles have configured homes; adopted external homes remain in place. Worktree mode creates a separate Git checkout and does not itself restrict filesystem access. Bounded means dispatch and reconciliation timeouts.
Illustrative example · Step through this example yourself
Discovery attaches existing provider homes without importing their credentials into a separate store. Claude quota checks read the home's credential file or macOS Keychain and send its bearer token to Anthropic's usage endpoint.
Delegations that cross a declared owner boundary are refused unless the sender explicitly confirms; the confirmation is recorded on the ledger. Enforcement applies when both profiles' accounts have declared owners.
Delegation refuses profiles whose recorded dispatch capacity is determinately exhausted. Automatic routing uses fresh quota readings when all candidates have them, otherwise transcript usage. Unknown or stale capacity remains eligible.
Delegated tasks are JSON records under ~/.flock/state/tasks by default; FLOCK_HOME relocates that directory. Records include the target profile, routing reason, state and any collected result.
01 / How it works
Delegation workflow
Say what you want in the conversation you already have. Your agent checks who can take the work, assigns it through Flock, and returns one result while the record stays on your machine.
-
Ask normally
Describe the outcome in your own words. Say “flock” or “delegate” when you want other workers involved; the words are optional vocabulary, not command syntax.
You say“Ship the auth refactor. Use the flock where it helps.”
-
Your agent checks and assigns
Your wired agent checks login, declared ownership and available capacity readings through Flock. It assigns the brief to a profile's live session and records which profile was chosen and why.
You say“Delegate the migration to Codex and ask Gemini to review the tests.”
-
Task results and peer messages
Your agent returns the task result in the conversation. Flock keeps routing, status, output and any review verdict in a local ledger. Peer messages let sessions exchange progress without creating another task.
You say“Bring me one reviewed result.”
Text equivalent of the architecture diagram: you talk to the lead agent in your usual session. The lead calls Flock, the local coordinator, which dispatches bounded tasks to worker profiles using Claude Code, Codex or Gemini CLI. Profile homes are separate by default. Every handoff and result is recorded in the local task ledger on your machine.
02 / Walkthrough
One task, from request to record.
A deterministic example based on Flock 0.7.21-alpha. Nothing here runs on or connects to your machine.
-
You ask in the conversation you already have.
RequestOne natural request names the outcome and the review. No command syntax.
YouShip the auth refactor. Use the flock: delegate the implementation, and have a second profile review authorization.
Your agentI will check who can take this before assigning anything.
-
Your agent checks the flock.
InspectLogin, owner, and availability are checked before any work moves.
Your agentThree profiles are signed in and accepting: two Claude, one Codex.
$ flk ls
NAME PROFILE ACCOUNT AGENT STATUS AGE DIR
○ work-main-1 (lead) work anthropic:work@example.com claude accepting 12s /Users/dev/app
○ personal-main-1 personal anthropic:me@example.com claude accepting 8s /Users/dev/app
○ oai-main-1 oai openai:me@example.com codex accepting 6s /Users/dev/app
-
Your agent assigns two bounded tasks.
AssignCodex takes the implementation; a separate Claude profile takes the review.
Your agentCodex is implementing the refactor. The personal Claude profile will review authorization separately.
$ flk delegate --to oai "Implement the auth refactor and report the patch."
task task-1786983715221 → profile oai (codex), routing: explicit
log: /Users/dev/.flock/state/tasks/task-1786983715221.log.jsonl
$ flk delegate --to personal "Review task-1786983715221 for authorization gaps and report a verdict."
task task-1786983716544 → profile personal (claude), routing: explicit
log: /Users/dev/.flock/state/tasks/task-1786983716544.log.jsonl
-
Results come back to your conversation.
ReturnEach task state, route, log, and result is recorded on your machine.
Your agentThe implementation is done: the patch is in and the authorization tests pass. The result is on the local ledger.
$ flk task status task-1786983715221
task-1786983715221: done (to=oai agent=codex routing="explicit" updated=14:32:08)
$ flk task result task-1786983715221
Patch completed; authorization tests pass.
-
Capacity policy can move coordination.
ReassignA determinately exhausted lead hands off to an already-live, eligible Claude session.
Your agentThe lead profile reached its capacity window, so coordination moved to a live Claude session with headroom. Nothing about your tasks changed.
$ flk lead enforce
lead is now personal-main-1 (least-consumed live worker, worst window 1%), demoted work-main-1 on capacity policy — the exhausted lead is now a worker until its reset
Automatic scheduled enforcement uses the optional macOS quota LaunchAgent; elsewhere this command is invoked manually.
-
One reviewed result, and the record if you want it.
CompleteThe reviewed change returns in the conversation; every handoff stays inspectable.
YouWhere did we land?
Your agentThe auth refactor is done and a second profile reviewed authorization. The full record of every handoff is on your machine; ask me to open it any time.
task-1786983716544: done (to=personal agent=claude routing="explicit" updated=14:34:11)
$ flk attach personal-main-1
03 / Where it helps
Four situations where a flock helps.
Delegate bounded work
A focused task can move to another authorized profile while you stay in the same conversation.
You say“Delegate the migration to Codex.”
ResultOne task record on the local ledger: brief, routing, state, and the returned result.
Check eligibility before assigning
Logged-out and determinately exhausted profiles are excluded before dispatch. When both profiles' accounts declare different owners, dispatch requires explicit cross-owner confirmation.
You say“Who in the flock can take this?”
ResultA report of who can take the work and why, before anything moves; a refusal names its reason.
Review across providers
Hand a completed task with a recorded Git worktree to a second profile for review, across providers if you route it there.
You say“Have Claude review the Codex patch.”
ResultA typed verdict recorded on the task, beside the exact diff it judged.
Keep sessions observable
See what a worker is doing without driving it, and inspect what it did after it finishes.
You say“Where is the flock stuck?”
ResultLive status per worker, and the full local record of any task after the fact.
04 / Across providers
A review's verdict returns to the dispatching conversation.
A review sent to a profile on another provider returns its verdict to the conversation that dispatched it, and is metered against the profile that performed it.
The verdict comes back in the calling turn
A review dispatched in the blocking mode returns the reviewer's verdict to the conversation that sent it, if the reviewer finishes within the 15-minute dispatch timeout. After a timeout the sender can check the ledger for the task's status and any recovered result.
Metered against the profile that reviews
Review work is metered against the account of the profile that performs it, so profiles on separate accounts draw on separate limits; profiles sharing an account share its limits. Claude and Codex profiles have a quota reading, Gemini has none, and a profile whose reading is unknown or stale stays eligible for work.
A Codex profile reviewed four rounds of Claude-authored changes to Flock. All four rounds came back marked as needing changes.
The findings included two regressions the author's handoff had described as absent: per-model quota buckets added for lead capacity were also read by worker routing and by reset detection.
During those reviews, provider notification support became explicit. Automatic promotion's reachability check requires a configured notification surface for sessions that do not qualify for its direct-pane delivery path.
A round rejected the author's stated reason for declining an earlier finding, showing that the test failures offered against it came from a fixture that did not establish the point.
Review ran in both directions in the same period: a Claude profile reviewed a Codex-authored deployment-reporting change and returned a commit verdict.
One project's development record on one day. The changes reviewed on that date are included in this release. Each review was routed by the sender. The reviewer was instructed to read only, which the brief asks for and the product does not enforce. Every finding was applied by the author. Flock does not require review, does not pair providers, and this was not measured against single-provider review.
05 / Ownership and safety
Profiles stay separate.
Flock coordinates profiles you control. It does not merge provider credential stores; the local task ledger records target profiles and any collected results.
Network calls
Flock's direct HTTP calls are Claude usage checks at api.anthropic.com/api/oauth/usage and release downloads under flk.dev/dl. Usage checks send that profile's bearer token. The checked source contains no product-telemetry sender or network listener; managed provider CLIs make their own network calls.
Plain local files
Flock writes provider wiring and local state under ~/.flock by default (FLOCK_HOME overrides it). Requested actions can also write the installed binary and backups, a macOS quota LaunchAgent, project pins, .flock/brief.md notes and Git worktrees. Codex wiring replaces the home's notify setting; isolated Codex homes also auto-approve Flock MCP tools.
Documented removal
flk uninstall removes Flock wiring from configured provider homes. The manual runbook covers Claude and Codex; Gemini wiring paths are listed in the installation guide. Uninstall runbook
06 / Install
Install Flock through the agent you already use.
Copy this prompt into Claude Code, Codex or Gemini CLI. Your agent reads the runbook, explains what will change and where, verifies the release checksum, and stops for your approval. You complete any provider login yourself.
Copying the prompt does not install anything.
Install Flock on this machine using the current runbook at https://flk.dev/install.md. Before changing anything, explain what you plan to install, where it will write, and the risk of the unsigned release. Verify the download and wait for my approval before installing. Pause whenever I need to complete a provider login. When you finish, check that my flock is ready and tell me about anything that still needs attention.
Version 0.7.21-alpha · macOS and Linux · binaries are currently unsigned.
07 / Before you install
Common questions.
What problem does Flock solve?
It brings Claude Code, Codex and Gemini CLI profiles into one local roster. Each profile has a configured home and account binding; profiles can share an account and its limits. Delegated tasks have a ledger record.
Why not just subagents, claude -p, or a tmux script?
Flock adds profile and account routing around persistent peer sessions. You can attach to a worker, inspect the task ledger and send a peer an update. Delegation checks a human-driven session's turn boundary and composer before submitting a brief. Claude and Codex have quota readers; a stale or missing reading leaves a profile eligible.
What happens if a peer is already working?
If a live member is still working when the turn-boundary wait ends, Flock parks the task with its brief in the ledger. An idle hook event can redispatch it; an operator can also request redispatch. A draft, login prompt or unrecognized composer is a different problem: it is reported rather than treated as a busy turn. Parking is not a promise of immediate delivery.
Do the three providers behave identically?
All three providers have profile and worker adapters. Claude and Codex can hold the lead lease, subject to admission checks; Gemini cannot. Claude and Codex have quota readers. Gemini has no numerical quota reader; Flock can record observed refusal signals. Gemini API-key mode does not identify the key owner. Its per-profile auto-approval setting is off by default; enabling it removes tool prompts without adding a filesystem sandbox.
Can Flock update without restarting my conversations?
Your agent can install a local Flock build with an atomic replacement and a backup. Known non-descendant builds are refused unless explicitly forced; unavailable ancestry produces a warning and permits installation. Compatible MCP servers adopt the replacement after active requests finish. Busy servers can remain pending, and legacy servers may need one reconnect. The roster and doctor report available build provenance and drift. Hot adoption executes the replacement at the MCP server's executable path without a new approval prompt. Anyone able to replace that file can run code in the affected MCP processes with their existing permissions. The ancestry check applies only when flk install writes the replacement.
Do I need to learn Flock commands?
No. Keep talking to your coding agent in plain language; your agent operates Flock's tools itself. The command reference exists for agents, maintainers, and troubleshooting.
Does Flock copy or share credentials?
Discovery attaches existing provider homes without importing credentials. Claude quota checks use the stored credential file or macOS Keychain and send the token to Anthropic. A mismatched profile login can quarantine credential files and remove a profile-specific Keychain entry. Isolated homes may contain credentials, and task records retain any secrets supplied in briefs or results.
Is the source code available?
Not today. Releases ship as checksummed binaries, and the source repository is not public.
What happens when no worker is eligible?
The dispatch is refused and the reason is reported. Automatic routing stays within the requested provider. If both account owners are recorded and differ, dispatch requires explicit cross-owner confirmation. Unknown or stale capacity does not exclude a profile in advance.
How do I uninstall it?
Ask your agent to remove Flock and show you the plan first. The uninstall reverses the wiring and prints what it will change before doing it. The manual runbook at flk.dev/uninstall.md covers Claude and Codex wiring. For Gemini, also check the profile's .gemini/settings.json and managed GEMINI.md entries listed in the installation guide.