Ask your agent to install Flock.

Quick start

The full runbook below is the authority; this is the short path through it for a machine with at least two signed-in agent homes. With only one, ask your agent to add a second profile first; discovery and login are both steps it can run.

What your agent checks first

Before proposing any change, your agent runs two read-only checks: uname -sm names the platform (it must appear in the artifact table below), and a listing of ~/.claude* and ~/.codex* shows candidate agent homes for discovery to inspect. After installation, flk doctor checks the setup and can repair missing Claude lifecycle hooks in the profile home or inherited Claude child-session flags in tmux's server environment. Include that repair in the installation approval.

1. Copy the prompt for your agent from this page into Claude Code. The agent reads the runbook, explains what will change and where, verifies the checksum, and stops for your approval.
2. Approve, and the agent runs discovery: existing signed-in homes are adopted as profiles with no new logins. You complete any browser login yourself.
3. Restart or reconnect the agent as the runbook requires, and confirm that its Flock tools have loaded. Then ask: "Ask another profile in your flock to add the first 7 prime numbers and reply with the sum."

You have succeeded when the answer comes back in your conversation and your agent can show you the matching record from the local task ledger.

01

The artifact your agent selects

Your agent detects the platform with uname -sm and selects the matching artifact. This table lets you inspect that choice.

On a minimal Linux image, curl and ca-certificates must be installed first if curl is absent.

02

What the installation changes

The paths below cover the binary, Flock state and provider wiring. Your agent's plan must also identify writes by provider login or startup tools. (Temporary downloads use /tmp; the runbook does not specify their cleanup. Installing tmux touches package-manager paths.) 'Wired' means the provider's hooks and Flock MCP registration have been configured. Additional context files, commands, skills and statuslines depend on the provider.

Quota checks read existing provider credentials without creating a separate credential store. Isolated homes can contain credentials; briefs, results and notes retain supplied content. Mismatched profile logins can quarantine credentials. Flock opens no network listener.

03

What your agent downloads

Your agent fetches the artifact for this machine and the checksum file named checksums.txt from the release directory. Nothing is executed and nothing is installed in this step.

curl -fsSL -o /tmp/flk "https://flk.dev/dl/<artifact>"
curl -fsSL -o /tmp/checksums.txt "https://flk.dev/dl/checksums.txt"
curl -fsSL -o /tmp/checksums.txt.minisig "https://flk.dev/dl/checksums.txt.minisig"

04

Verify the checksum before installation

Your agent compares the artifact's entry in checksums.txt with a SHA-256 digest it computes locally, after checking checksums.txt against its published minisign signature (/dl/checksums.txt.minisig; public key pinned in the runbook and at /dl/minisign.pub). The two values must match. A failed signature, a missing entry, or a mismatch means it stops and reports; it does not install.

Verification completes before the executable write; the runbook enforces this order.

minisign -Vm /tmp/checksums.txt -P RWSyAr20tQVUoGpgA9Zn8hLirHhzlVi7QlP6eR3vUh2Ln2Nt13obiYQx || exit 1
PUB=$(grep "<artifact>" /tmp/checksums.txt | awk '{print $1}')
LOC=$(shasum -a 256 /tmp/flk 2>/dev/null || sha256sum /tmp/flk); LOC=${LOC%% *}
[ -n "$PUB" ] && [ "$PUB" = "$LOC" ] || exit 1

05

Your approval gates the write

The install writes an unsigned executable to ~/.local/bin/flk. The runbook requires your agent to state that and to obtain your approval before the write happens. Nothing before this step has written the executable or initialized Flock state.

mkdir -p ~/.local/bin && install -m 0755 /tmp/flk ~/.local/bin/flk

06

Set up your flock

Your agent runs discovery: it reads four sources (the top of your home directory, the environment of running agent processes, a sweep under ~, and existing profiles' own homes) for signed-in Claude and Codex homes, proposes a binding for each (a new account and profile, or an existing profile), and waits for confirmation. Existing homes are attached where they are: tokens stay in place and are never copied, and removing an adopted profile later detaches the external home while the directory remains on disk. Logged-out and already attached homes are skipped.

flk init --discover
flk profile login <name> --agent <claude|codex|gemini> --owner <owner>
flk quota install-agent    # macOS only, consent-gated; flk quota uninstall-agent removes it

Complete the browser login yourself

Login runs inside tmux so both stdin and stdout are terminals. The human completes the browser OAuth flow and any provider account chooser; an agent must never enter, read, or relay credentials.

Gemini CLI profiles

Ask your agent to create a profile with agent type gemini, then pause while you complete Gemini CLI's own authentication flow. Flock gives the profile a separate home; Gemini stores its settings under .gemini inside that home. Flock also recognizes Gemini's recorded API-key or Vertex AI authentication mode, without claiming to know who owns that key. The existing-home discovery procedure above documents Claude and Codex, not automatic Gemini discovery.

Choose Gemini tool approval deliberately

Gemini profiles leave auto_approve_tools off by default. Enabling that profile setting launches new sessions with --approval-mode yolo, so tool calls no longer ask for permission. It does not add a filesystem sandbox and applies to interactive sessions as well as workers. With it off, a detached worker can pause for a human approval. Flock separately declares the workspace trusted through GEMINI_CLI_TRUST_WORKSPACE=true unless overridden in profile Env.

Optional on macOS

The optional quota LaunchAgent runs a persistent watcher for periodic and reset-time refreshes and lead enforcement. Ask your agent to obtain consent before installing it; an operator can remove it with flk quota uninstall-agent.

07

Ask your agent to check the installation

Your agent verifies the installed version and executable location, each profile's declared account against its logged-in identity, hook and MCP wiring, and the live usage contract, and it reports every warning instead of calling the install complete. Identity matters: consecutive browser logins can reuse the browser's current session, so each result is checked and a mismatched login is repeated with the intended account.

flk --version
command -v flk
flk capabilities
flk whoami
flk doctor --deep

Identity consistency needs a declared email and an exposed login identity. doctor can repair hooks and tmux flags and refresh local quota state even without --heal; --deep also probes network contracts. Keychain-backed Claude credentials require access to that store.

08

Update Flock

flk upgrade downloads the platform binary, compares its digest with the published checksum file and runs the candidate with --version before replacement. Even --check writes and executes that temporary binary, then removes it; it does not replace the installed executable. Obtain approval for that execution as part of the update plan.

flk upgrade --check
flk upgrade

09

Remove Flock

Without --yes, uninstall prints a plan and makes no removals. After confirmation it removes recognized Flock wiring. Statuslines whose command ends in ' statusline' can be ambiguous; review the plan and use --keep-statusline where needed. Outside the optional state purge, credentials, homes and conversations are retained.

flk uninstall
# after reviewing the printed plan:
flk uninstall --yes

State purge is separate

Purging state deletes the roster, task ledger, event history, and every isolated profile home, including in-home credential files and, on macOS, each isolated claude home's Keychain token. Deleting the binary is a further explicit choice. Nothing is revoked server-side; sessions using an isolated home require login again. A removal plan must distinguish these choices explicitly.

Manual path

When flk cannot run, the removal runbook covers manual cleanup of Claude and Codex wiring. For Gemini, also inspect the .gemini/settings.json and managed GEMINI.md paths listed above.

Removal runbook