Using Flock

MCP tools

These are the tools your agent calls after Flock is wired; they are not user-facing commands or prompt keywords. flk mcp serves MCP over stdio; flk profile wire registers it as server flock in each profile home. Claude registration is written to the profile's Claude state file; Codex registration is written under mcp_servers.flock in config.toml. Gemini CLI registration uses gemini mcp add with user scope under the profile's home. Native tools load at session start. An agent must inspect the tools exposed to its own session before promising to call one; another profile's wiring does not prove this session has loaded the server.

Operator and diagnostic CLI

flk provides CLI commands for agents and operators. State defaults to ~/.flock, with FLOCK_HOME as an override. Requested operations can also write provider homes, project files, the executable and a macOS LaunchAgent plist. The quota LaunchAgent records its FLOCK_HOME in the plist.

Inspect before you dispatch

Illustrative example, not captured output

This sequence checks identity and fleet state, then assigns one bounded task and waits for its recorded result.

flk whoami
flk ls
flk delegate --to claude:auto "Inspect the failing test, propose the smallest fix, and return the file path plus evidence."

Automatic routing prints the profile chosen. A refusal, failure, or clarification request stays visible as task state.

Identity & configuration

Commands shown here are an operator reference. Provider-specific settings and write scopes differ; inspect the installation guide before wiring.

Sessions & workers

A new session uses an account-based name unless explicitly named. Claude sessions can be renamed from transcript slugs. Delegation prefers a live non-desktop session named after the profile, otherwise the most recently updated eligible member. It excludes the caller; if that caller is the only live member, dispatch is refused. With no member it can spawn one, unless a session is awaiting rehome. Worker-role sessions participate in member selection. Leadership does not rename sessions.

Delegation & memory

The lead assignment is stored as a lease file, state/lead.json, recording holder, pane, pid, and the grant chain (rendered publicly as the lead history). 'Lease' in the rest of this reference names that file.

Lead protocol

The lead lease identifies the coordinating session. The operator policy assigns it dispatch, verification and reporting responsibilities; use Flock commands for session operations so outcomes are recorded.

Quota

Worker capacity excludes model-scoped windows from the 98% refusal threshold; lead capacity includes them. Readings must be determinate. Unknown, stale, schema-drift and passed-reset states do not establish exhaustion and remain dispatch-eligible. Codex model buckets and observed provider refusals are reflected in the cached reading. Claude can read credentials from a file or the macOS Keychain; only the latter requires Keychain access.

Rules for agents using these tools

• The worker cannot see your session. A brief must carry the goal, all needed context, the deliverable format, and acceptance criteria. Include executable file paths and commands in the brief.
• claude:auto reports the profile chosen; repeat that to the user.
• Dispatch to a determinately exhausted profile is refused; do not work around the refusal. If any of your own windows reaches 98% while you hold the lead, recuse (see the runbook's capacity section). A worker whose only window at 98% is model-scoped may still accept work on other models.
• On task failure, report the state, error, and log path verbatim.
• Preserve a flock_msg_send deaf-mail warning. The mailbox write succeeds, but a target without a hook or statusline surface can wait silently; do not describe that warning as delivered coordination.

Hook & event contract

flk profile wire installs these. They call flk event … (hidden command; errors go to stderr with exit 0, so a hook failure never fails the agent).

Claude Code: every hook posts its stdin JSON to flk event claude:

Payload fields used: hook_event_name, session_id, transcript_path, cwd, tool_name, message, prompt. Session resolution order: tmux pane → FLOCK_ID env → session_id. Unknown sessions register as external with deterministic id ext-<session_id[:8]>: one record per agent session. On UserPromptSubmit, prompt is recorded as the turn's input for dispatch integrity, and when it carries a delegation wake-up line the hook prints that task's framed brief to stdout, which Claude Code adds to the turn's context: this is how a delegated brief reaches a claude session.

The first Claude SessionStart or UserPromptSubmit event consumes a durable first-contact flag and writes one context notice into Claude's conversation. It names the roster identity and profile, states whether lifecycle surfaces are wired, and, when wired, says that native tools load after restart. It tells the agent to operate Flock on the user's behalf without exposing commands. Silent hook events never consume the flag. Codex receives its context through managed AGENTS.md and MCP; there is no codex hook context channel. A delegated brief reaches a codex session through flock_task_brief or flk task brief <id>, named in the wake-up line. The statusline input (model.id, model.display_name) is recorded on the session whenever it changes; it is what flk ls and model selection read for a claude session.

Codex: notify in the flock-owned config.toml calls flk event codex-notify <json>. Only agent-turn-complete is ingested; it sets idle and records the turn's final message and input for result collection, and the model and effort of the turn from the rollout's turn_context. Codex has no start or working hooks: boot is discovered from the profile home's session files, and death from pane liveness.

State on disk

Flock keeps state as local files under FLOCK_HOME (default ~/.flock). MCP servers and the optional macOS quota watcher can remain running. Requested operations may also write provider homes, project notes/pins/worktrees, the installed executable and installer backups.

~/.flock/
  accounts.toml                 # named accounts: provider, owner, email
  profiles/<name>/
    profile.toml                # agent, account, model, workspace, env
    home/                       # the agent's isolated home (CLAUDE_CONFIG_DIR / CODEX_HOME / GEMINI_CLI_HOME)
  state/
    sessions/<id>.json          # roster records (atomic writes)
    events.jsonl                # append-only log: lifecycle, capacity-transition, succession, message
    lead.json                   # the lease: holder, pane, pid, granted_by, chain
    quota.json                  # quota cache (per profile, timestamped)
    tasks/                      # delegation ledger + per-task logs
    messages/                   # mailboxes, one box per session + lead-pending

Spawned sessions receive FLOCK_ID and FLOCK_PROFILE. The provider home variable is CLAUDE_CONFIG_DIR, CODEX_HOME or GEMINI_CLI_HOME; Flock omits CLAUDE_CONFIG_DIR for Claude's default home to preserve its native identity behavior. Profile environment settings can override defaults. TMUX_PANE is supplied by tmux.

Invariants

• Discovery attaches provider homes without importing credentials. Quota checks read stored credentials; isolated homes and task content can still contain secrets.
• MCP uses stdio. The checked Flock source contains no network listener; the optional macOS quota watcher is a persistent background process.
• Wiring preserves unrelated MCP entries and custom Claude statuslines, but claims the Codex notify setting. Isolated Codex homes auto-approve Flock MCP tools. Profile removal deletes an isolated home; an adopted external home is detached and retained.
• The lease records process identity and checks liveness. Account consistency can be checked when an account declares an email and the provider exposes an identity; API-key authentication mode alone does not identify an owner.