Docs

tab CLI

tab runs the agent you already use on a FlockTab tab, and does everything this console does from the terminal. This page and tab help are written from one source.

Install

npm i -g @hanamorilabs/tab
tab login          # once per machine
cd my-project
tab claude         # first run here picks this folder's Agent
tab help           # every command;  tab help <command> for one in full

Leave the Agent out of any command and it acts on this folder's. Add --json to any read command for scripts and agents. tab <command> --help explains that command; after an agent's name (tab claude --help) everything belongs to the agent.

Get started

Once per machine, then once per project folder.

tab login

Approve this machine in the console, once.

tab login

Asks whether this machine uses the hosted proxy (proxy.flocktab.com) or a self-hosted one on this machine, then prints a short code and opens the console. Approve the code there and the machine receives its session. Nothing is typed into the terminal except that choice, and no Agent is chosen here.

Login is per machine. Which Agent a project runs as is per folder: see tab use.

A command that needs a login starts this one by itself only at a terminal. In a script, a pipe or CI it says Not logged in and exits 2 instead; run tab login there yourself.

Whoever approves the code needs to manage Agents and keys for the whole flock. The machine acts on their word: if they later lose that (a narrower role, suspended, removed), its next call is refused and it has to log in again.

On a hosted flock with a saved provider key, login also asks for the flock's unlock, checks that it opens the key, and keeps it in the machine's config (owner-only). The unlock is never stored on FlockTab.

ExampleWhat it does
tab loginapprove this machine

See also: tab use · tab logout · tab status

tab use

Pick or change the Agent this folder runs a harness as.

tab use
tab use claude|codex|grok|kimi

An Agent is one harness on one project. tab claude and tab codex in the same folder are two Agents (that is what the plan counts), each asked for once: the first run of a harness in a folder lists the flock's Agents of that harness (and untied ones it can tie), or makes a new one and asks its kind. The new Agent's default name is that of the folder's Agent under another harness (from .flocktab, or the one the console last saw in this folder or repo), in its project; otherwise the console links it to the project it is named like or, failing that, the one TypeSafe's model judges it belongs to, and names it after the folder. One dim line says why. The slug adds the harness (dash-f4f-claude). The choice goes into .flocktab at the git root, one entry per harness, and a key for that Agent is minted and kept on this machine. A git worktree of the project (git worktree add, or Claude Code's .claude/worktrees) runs as the main checkout's Agent: .flocktab is not committed, so tab reads the main checkout's.

tab use codex changes the answer for one harness; bare tab use sets the folder's default, which every other command (tab python …) runs as. An older .flocktab with a single Agent applies to every harness until one is set apart.

An Agent that already holds a key on another machine can be used here too, but minting a key here replaces the one there. tab asks before doing it.

ExampleWhat it does
tab usepick this folder's Agent again, from a list
tab use codexpick the Agent tab codex runs as here
tab agent create api-test --api --cap 5 --harness claude && tab usetry an API-key Agent in this folder; tab use again to go back

See also: tab agent · tab key · tab list

tab setup

Make this machine and folder ready for a harness, in one check list.

tab setup
tab setup claude|codex|grok|kimi
tab setup remove claude|codex|grok|kimi

Checks each part and does what is missing, after asking: tab is the latest (tab update), this machine is logged in (tab login), this folder has its Agent (tab use), the harness is installed, plain claude, codex, grok or kimi runs through tab (tab alias setup), and the status line (tab statusline install for Grok and Kimi; Claude Code gets it from tab claude). Each line says done (✓), changed now (→) or still to do (·); a second run changes nothing. Bare, it offers each harness installed here.

For Claude Code 2.1.287 or later it also offers FlockTab's plugin, which draws the tab's line above the prompt in a plain claude and the Desktop app's Code tab too, not only in tab claude. It is installed for your user through Claude Code's own claude plugin install, from a marketplace tab keeps in its home, and only after you say yes; in a folder that is not on the tab it draws nothing. A newer tab updates it on the next tab setup claude. An older Claude Code keeps the status line, and setup says so.

tab setup remove takes back what setup added for that harness (the plugin, tab's status line in a harness config, putting yours back, and the alias), each after asking. It never logs you out or forgets the folder's Agent.

ExampleWhat it does
tab setupcheck every harness installed here
tab setup claudeClaude Code: login, Agent, alias, status line and FlockTab's plugin
tab setup remove claudetake the plugin and the alias back out

See also: tab login · tab use · tab alias · tab statusline · tab update

Run an agent on the tab

Prefix the agent you already use. Its calls are gated, recorded and, on an API-key Agent, charged to the cap.

tab claude | codex | grok | kimi | <cmd>

Run an agent on this folder's tab. Everything after the name goes to the agent untouched (Codex also gets --no-daemon; see below).

tab claude [args]
tab codex [args]
tab grok [args]
tab kimi [args]
tab <any command> [args]

tab sets the environment that agent reads (its base URL and key, or for Codex a home folder of its own) and starts it. It does not wrap or parse the agent's traffic; the proxy does the gating.

Codex's tab home starts from your own ~/.codex/config.toml: approval policy, sandbox mode, model and effort, MCP servers, profiles and trusted folders all apply under tab codex. Only the tab's keys (where the calls go, the flocktab provider) are layered on top. Your global instructions (~/.codex/AGENTS.md, and AGENTS.override.md) are linked in, so Codex under tab follows the same rules and an edit to yours applies at once.

A plain tab codex (no arguments) runs Codex's app-server itself, in your folder, on a socket in a folder of tab's that only you can open (~/.flocktab/codex-sockets), and opens the Codex window on it. That lets tab codex send put a message into the session's running turn. The server stops when the window closes, however it closes. When tab cannot give a socket (an older Codex, or FlockTab's Agent Guard hooks not yet trusted in Codex), it says so and runs Codex as before. Anything else (resume, fork, a subcommand, any flag or prompt) runs as before, with --no-daemon added so it stays off Codex's shared background server: that server keeps the environment it started with, so every session on it would run as the first one. Resume stays this way because a resumed thread on a socket takes the home's default permissions (Full Access, when that is your config's default), not the thread's own, and Codex refuses -s and -a there.

On an API-key Agent every call is held, settled and charged to the cap, and a call that would pass the cap is refused before the provider with 402 tab_closed. The key is the one the agent already has: a harness set up with its own vendor key (ANTHROPIC_API_KEY, OPENROUTER_API_KEY, ...) keeps it, and tab only moves where it is sent (the proxy's /t/<key>/<vendor>/v1 route, which forwards the key untouched). A vendor the agent has no key for uses the flock's key, if the flock has one.

On a Subscription Agent the agent keeps its own login (Claude Max, ChatGPT, SuperGrok, Kimi). On an API-key Agent, Grok Build runs through the tab on its own XAI_API_KEY when it has one, else the flock's xAI key (refused when a self-hosted proxy has none), in a Grok home of tab's own with no SuperGrok login in it (your Grok settings are not carried there). On an API-key Agent, Kimi Code runs on Moonshot's API through the tab (kimi-k2.7-code), from a Kimi home of tab's own with no Kimi login in it: on its own MOONSHOT_API_KEY when it has one, else the flock's. The tab key rides in the base URL, the same kill switch and policies apply before the vendor is reached, the call is recorded at list price under the account the vendor names, and nothing is charged to the cap.

OpenCode (tab opencode) is given an inline config that points its openai, anthropic and openrouter providers at the tab and switches every other provider off, since OpenCode would otherwise use any key it finds in the environment and go straight to the vendor. Your own OPENCODE_CONFIG_CONTENT is kept; only the providers are taken over. Pick a model as usual: -m openai/..., anthropic/... or openrouter/.... OpenCode runs metered: it has no plan login FlockTab can pass through.

Pi, Goose, Aider and Copilot CLI are set up the same way, each in the form it reads: Pi loads a FlockTab extension (pi -e) that moves its providers; Goose gets its hosts and runs its openai or anthropic provider; Aider gets its Anthropic and OpenRouter bases; Copilot CLI runs its own-key provider against the tab, never GitHub's models. A model named vendor/model (GOOSE_MODEL, COPILOT_MODEL) goes to OpenRouter. OpenCode, Pi, Goose and Copilot turn on any provider they find a key for, so keys for vendors the tab cannot route (KIMI_API_KEY, GEMINI_API_KEY, ...) are hidden from them. tab says at launch which of the agent's own keys it is using.

With no Anthropic key, Anthropic's API goes to OpenRouter's Messages endpoint instead: with the agent's own OPENROUTER_API_KEY if it has one, else (self-hosted) the flock's OpenRouter key on the box. Claude Code included.

OpenClaw gets a config of tab's own (OPENCLAW_CONFIG_PATH) that includes yours and replaces only its model providers with ones through the tab (flocktab/<openrouter model>, flocktab-openai/..., flocktab-anthropic/...); it needs Node 24.16 or later. Cline gets a --config folder of tab's own with an OpenAI-compatible provider on the tab, on your own Cline model when you have one. A key a harness keeps in its own files (Codex's API-key login in ~/.codex/auth.json, OpenCode's auth.json) counts as its own like one in the environment.

Gemini CLI (tab gemini) and Antigravity (tab agy) speak Google's own API: tab gives them GEMINI_API_KEY and GOOGLE_GEMINI_BASE_URL on the tab (their own Gemini key through the own-key lane), drops what would send them to Vertex or Code Assist around it, and gives Gemini CLI a home of its own whose settings choose the API-key sign-in (yours are copied, not touched). A GEMINI_API_KEY in the .env files Gemini CLI reads (the folder and its parents, ~/.gemini, ~) counts as its own. Antigravity reads its settings only from your home, so tab agy runs it with a home of tab's own (~/.flocktab/agy-home): every entry links to yours, and only its settings.json is a copy of yours that adds modelProvider gemini. Your own settings stay as they are, so plain agy keeps your Google login. Folders you trust in tab agy are added to your trusted list when it exits. Its MCP list (.gemini/config/mcp_config.json) is also a copy of yours, with the flock's tools added (see tab mcp). A server agy adds in tab agy is added to your list when it exits. Its plugin list (.gemini/config/plugins.json) is a copy too, with tab's inbox hook added, which hands agy the flock's messages (see tab agy send). A plugin agy adds is added to your list when it exits. A change to one of your servers or plugins stays in tab agy's home, and tab names it. A file agy makes at the top of that home stays there, and tab names it.

Any other command works too: tab points both the OpenAI and the Anthropic variables at the proxy and runs it. An agent with no consumer plan on a Subscription Agent runs metered on the flock's key, and tab says so.

With logins in the pool for that vendor, a Subscription Agent runs as the login with most room. See tab pool.

--observe (Claude Code 2.1.278 or later and Codex 0.155.1 or later, on macOS and Linux, after tab login) adds hooks that report when a session or a subagent starts and stops, and when one agent sends another a message: identifiers and outcomes only, never the prompt, the message or any tool output. Observability's map draws the links between Agents from these reports, and its Agents reporting line counts the Agents that sent them in the last 24 hours. Codex asks once to trust the hooks; a hook the harness skips leaves links missing, not proof that nothing happened.

OptionWhat it does
--observeClaude Code and Codex: report sessions, subagents and messages between agents to Observability (metadata only)
--as <login>run as one pool login and never move off it
--no-poolignore the pool and use the agent's usual login
--poolrequire the pool; fail rather than fall back when it cannot be used
ExampleWhat it does
tab claudeClaude Code on this folder's tab
tab codex resume <id>arguments pass straight through; Codex sees the conversations in ~/.codex
tab claude --as workpin the pool login named work
tab claude --observeClaude Code, with its sessions and messages drawn on Observability's map
tab opencode run -m openrouter/anthropic/claude-sonnet-4.5 "fix the tests"OpenCode on the tab, through the flock's OpenRouter key
tab python agent.pyany script, with OPENAI_* and ANTHROPIC_* pointed at the tab

See also: tab use · tab pool · tab alias · tab log

tab alias setup | remove | list

Make the plain command (codex) run through the tab (tab codex).

tab alias setup <name>...
tab alias remove <name>...
tab alias list

Writes a small shim named like the agent into ~/.flocktab/bin. With that folder first on your PATH, typing codex runs tab codex. tab removes that folder from the PATH of the agent it starts, so the shim never calls itself.

tab alias setup prints the PATH line to add to your shell if it is not there yet.

ExampleWhat it does
tab alias setup claude codexplain claude and codex now run on the tab
tab alias remove codexundo one

Agents, caps and policy

Everything the console's Agent page does, from the terminal. Leave the Agent out and the command acts on this folder's.

tab agent create | kind

Make an Agent, or change its kind or harness.

tab agent create <name> --subscription|--api [--harness claude|codex|grok|kimi] [--cap <dollars>]
tab agent kind <agent> api|subscription
tab agent harness <agent> claude|codex|grok|kimi|any

An Agent is one harness on one project, with one tab. Two things are declared: its kind (api: the cap is the meter, paid by the agent's own vendor key or else the flock's; subscription: your own plan logins, nothing charged) and its harness (claude, codex, grok, kimi, or any for scripts). The proxies enforce the harness: a Claude Agent's key cannot pass a Codex login through (403 wrong_harness), so Claude and Codex on one folder are two Agents and count as two.

A subscription Agent's plan calls never touch its cap; its tab is the kill switch. Only its own key on a vendor with no plan login, such as Antigravity on Gemini, is charged to the cap.

Changing the kind applies to the next launch. tab claude reads it fresh every time. It also applies at once to sessions already running: a subscription session is refused with 403 not_subscription on its next call once its Agent is api. To try an API-key Agent in a folder that has sessions running, make a new one and tab use it there instead, then tab use the original again.

OptionWhat it does
--subscription | --apithe kind of the new Agent (api when neither is given)
--cap <dollars>the new Agent's cap; 50 when left out
--harness claude|codex|grok|kimiwhich harness this Agent is; any when left out
ExampleWhat it does
tab agent create billing-api --api --cap 20a metered Agent with a $20 cap
tab agent create dash-f4f-codex --subscription --harness codexa Codex Agent for the dash folder
tab agent harness dash-f4f codextie an untied Agent to Codex
tab agent create my-laptop --subscriptionan Agent for your own plan logins
tab agent kind billing-api subscriptionswitch an existing Agent

See also: tab use · tab cap · tab accounts

tab list

Every Agent: kind, state, spent of cap, window, project.

tab list

One row per Agent in the flock. The same list tab use chooses from.

A closed tab says who closed it: closed (cap), closed (cap, for good), closed (by a person) or closed (loop watch). tab status shows the loop watch's reason.

OptionWhat it does
--jsonthe rows as JSON
ExampleWhat it does
tab listevery Agent in the flock
tab list --jsonthe same, for a script

See also: tab status · tab live

tab close | open [agent]

The kill switch. Close stops the next call; open lets calls through again.

tab close [agent]
tab open [agent]

Closing a tab takes effect on the next call: it is refused before the provider or vendor with 402 tab_closed. Calls already in flight finish. This works the same on API-key and Subscription Agents.

A tab that closed itself by reaching its cap reopens by itself when its window rolls over (unless its reopen rule says manual or never), or now with tab open.

ExampleWhat it does
tab closestop this folder's Agent
tab open billing-apilet a named Agent run again

See also: tab cap · tab policy

tab cap

Set the hard cap, its window, and what happens at the cap.

tab cap [agent] <dollars>
tab cap [agent] --on-cap close|pause --reopen window|manual|never

The cap is a hard dollar limit on one Agent for one window. Before every call the proxy holds the call's worst case against it (its input, counted a quarter high, plus its whole output limit), so a call cannot start unless it fits. What is charged is the vendor's own count: if that comes in above the estimate (a long system prompt, tool schemas, images), the call is settled at it and the tab closes, and nothing runs after it.

A call whose worst case does not fit what is left (a harness that asks for 64,000 output tokens on a $1 tab) is fitted instead: its output limit is lowered to what the remaining budget pays for, and the provider is asked for that; the reply says so in x-flocktab-fitted-max-tokens, and the decision log reads fitted to N of M output tokens. Below 2,048 output tokens (8,192 for a call with a reasoning effort or a thinking budget, which spends output before it answers) the call is refused instead (this call could cost up to $X; $Y left on the tab), and the tab stays open. The tab closes when its spend reaches the cap.

The window is how often the spent amount starts again: hour, day, week or month, from the start of each in the flock's time zone (Settings); run and lifetime never reset. Changing the window starts the new one from now.

--on-cap close (the default) closes the tab at the cap, the same as tab close. --on-cap pause refuses calls over the cap but leaves the tab open: the next window, or a higher cap, carries on by itself.

--reopen says when a tab its cap closed opens again: window (at the next window), manual (tab open, the default) or never (only after you change this). A tab you closed yourself is never reopened for you.

OptionWhat it does
--window run|hour|day|week|month|lifetimewhen spent starts again
--on-cap close|pauseclose the tab at the cap, or only refuse until the next window
--reopen window|manual|neverwhen a tab its cap closed opens again
ExampleWhat it does
tab cap 25 --window week$25 a week for this folder's Agent
tab cap nightly-bot 10 --window day --reopen window$10 a day, back on its own each morning
tab cap --on-cap pausestop at the cap without closing the tab

See also: tab close · tab policy · tab spend

tab policy

Show or set the rules checked before every call.

tab policy [agent]
tab policy [agent] --velocity N|none --models a,b|none --allow tool,tool|none
tab policy [agent] --guard off|watch|ask|deny --loops off|watch|pause
tab policy --all --guard off|watch|ask|deny --guard-level ... --loops ...
tab policy --default-guard off|watch|ask|deny
tab policy [agent] --guard-level relaxed|balanced|strict --reach on|off --flag <pattern>|none --trust <pattern>|none --forget <pattern>

Checked in this order, first refusal wins: tab state, cap, velocity (calls per minute, 429), model allowlist (403 model_blocked), irreversible tools (403 risk_blocked), per-tool caps (402 tool_cap).

A tool FlockTab does not know is treated as a write, not a read. Irreversible tools (payments, sending email, deletes, production deploys) are denied unless named in --allow, and even then only while at least $25.00 of the cap remains.

--guard turns on Agent Guard and --loops the loop watch for tab claude, tab codex, tab gemini, tab agy, tab opencode, tab goose, tab cline, tab grok, tab kimi and tab pi, from the next launch. Agent Guard judges each tool call before the harness runs it: known irreversible commands (a force-push, DROP TABLE, a production deploy, a payment) by rule, the rest by TypeSafe's judgment model. watch records, ask has you confirm in the terminal (Codex, OpenCode, Goose, Cline and Kimi Code have no way to ask from a hook, and nobody can answer a headless run such as -p: the agent is told to ask you), deny refuses. In Cline a refused call is not held open (Cline gives a plugin three seconds): it is refused at once and stays in the review queue, so you can allow it there or with tab guard allow and the agent retries. Goose on Windows is not covered yet: its commands run unchecked, and tab says so at launch. Read-only tools, agents messaging each other (SendMessage, the task tools) and questions an agent asks you (AskUserQuestion) are never judged. A plainly read-only shell command (readers such as ls, cat, grep, find, sed -n …p, sort, tree, diff, git status or git log, piped into each other or after a cd into another folder, with nothing redirected and none of their writing options; git after a cd is judged, since another repo's config can run code) and a call already allowed earlier in the same session go ahead at once and are recorded afterwards. An agent rewriting Claude's or Codex's own permission settings always asks. A call that would send a secret off the machine is refused at once, by rule, in every mode but off, without a judgment or asking you: a live API key, token or password pasted into curl, wget or any program not known to stay local, a web fetch, an email, Slack or any MCP tool, or a git push whose new commits add an .env file, a private key file or a line holding a key. It is held for you like any refusal, with the secret hidden even on the machine that ran it. Run tab guard allow <id> on that machine and confirm it in the console: exactly that call then runs once. A call carrying a secret is never allowed always. The refusal names the kind of secret and where it was going, never the value, and tells the agent to use it by name (an environment variable or a file). Writing a secret to a local file (echo >> .env, the Write tool) is fine, and so is searching for one with a local reader (grep, rg, sed, awk, jq, find, git grep, git show REV:PATH, even behind rtk, env, nice or timeout, inside if, while or for, or in a $( ) of them; text in quotes or a quoted here-document is data, never a command); a password in an address on this machine (postgres://…@localhost) never counts; test keys (sk_test_, ft_test_), placeholders, fixture values (public-fixture-key) and unsigned emulator tokens never count; a local browser opening a page on this machine (http://localhost…) with a token in its address stays on the machine, and it is a guard rail, not a guarantee: a secret encoded or split to hide it is not found. If flocktab.com cannot answer in time, the rules decide alone. Your answers in Claude Code's own prompt teach it: a no flags that exact command on the Agent at once (at most 40 learned rules, kept apart from your own patterns and never replacing them); a yes trusts nothing until you confirm it on the console's Agent Guard page.

--guard-level sets how sensitive the guard is (balanced unless set). relaxed stops only what surely cannot be undone, by rule, has TypeSafe's model flag a call only when it is 80% sure, and never checks reach. balanced adds calls the model is 50% sure cannot be undone, and reach. strict also stops any git push, any delete, a web request that sends data, a database or cloud write, and an MCP tool that creates, changes or sends, and has the model flag from 30%.

With the guard on, reach (on unless --reach off) also stops calls outside the project by rule: ssh, scp or rsync to another machine, sudo, kubectl exec, a database client pointed at another host, reading private keys or credentials files, and Claude Code turning its own sandbox off (dangerouslyDisableSandbox). A plainly read-only command, such as reading a file in another folder, may leave the sandbox without asking; reading keys or credentials (however the path is written, in any case, globbed, after a cd into their folder, or by a recursive grep, rg or diff over any folder they sit under, such as ~/.config or your home folder) or anything under /etc, /var or /private other than listing it still asks. Codex does not tell hooks when it asks to leave its sandbox, so there the guard judges the command itself. When only the model thinks a call reaches past the folder (a grep or a cd elsewhere), it asks only if the call may also be hard to undo or carries some risk.

Tune it with your own patterns; case and repeated spaces do not matter. --flag adds one the guard always stops: it matches when the command, or the tool's name, starts with it, and * matches anything ("*prod*", "mcp__linear__delete*"). --trust adds one it always lets through, before every rule, and trusts exactly what it names: without * only that command; with *, anything it matches except text that chains or redirects (; && || | ` $( > <), so "npm test*" never trusts "npm test; rm -rf ~" ("ssh staging-bastion*"): keep those narrow. --forget removes a pattern; none clears a list. Up to 40 of each. The same settings are in the console, on Policies and on the Agent's page.

The loop watch looks at the last ten tool calls every three calls and records an agent that keeps repeating itself, or that has spent half an hour or more only waking up to re-run the same check. In Claude Code it also counts each reply that ends a turn, so an agent that gives the same reply three times in a row with no tool call and no prompt of yours between (a goal check that keeps saying continue) is stuck by rule; your prompts are counted, never their words; only the reply's first 120 characters are kept, with keys, tokens and passwords removed, and they go to the judgment model with the tool calls when no rule decides. Pause also closes its tab, the same as tab close, once it has been stuck that many checks in a row (two unless --pause-after says otherwise). Each tool call (the command and its arguments, including the text of a file write) goes to TypeSafe's judgment model with keys, tokens and passwords removed, and only a 200-character summary is kept; tool output never leaves the machine. Codex asks once to review FlockTab's hooks: choose Trust all and continue. codex exec never asks: until that one-time answer it skips the hook and its commands run unchecked, and tab says so.

OptionWhat it does
--velocity N|nonemost calls per minute (a new Agent starts at 120); none removes the limit
--models a,b|nonethe only models allowed; none allows any
--allow tool,tool|noneirreversible tools this Agent may call
--guard off|watch|ask|denyAgent Guard judges tool calls before they run; ask or deny stops irreversible ones
--loops off|watch|pausethe loop watch spots an agent stuck repeating itself; pause closes its tab
--pause-after 1-5how many checks in a row (one every 3 tool calls) must find no progress before pause closes the tab; default 2, since one stuck check can just be a slow step
--allevery Agent at once: takes --guard, --guard-level, --reach, --loops and --pause-after; prints each Agent and a total
--default-guard off|watch|ask|denythe Agent Guard mode new Agents start with (Settings in the console)
--guard-level relaxed|balanced|stricthow sensitive the guard is; strict also stops pushes, deletes and writes outside the folder
--reach on|offthe guard also stops ssh, sudo, remote databases, reading keys and the sandbox off
--flag <pattern>|nonea command or tool the guard always stops; * matches anything
--trust <pattern>|nonea command or tool the guard always lets through
--forget <pattern>remove one of your patterns
ExampleWhat it does
tab policy --velocity 60 --models claude-sonnet-5,gpt-5slow it down and pin its models
tab policy --guard ask --loops watchconfirm irreversible calls, record stuck sessions
tab policy --all --guard watch --default-guard watchevery Agent, and every new one, on watch
tab policy --guard ask --guard-level strictask before any push, delete or write outside the folder
tab policy nightly-bot --guard deny --loops pausean unattended Agent: refuse and stop
tab policy --trust "ssh staging-bastion*"one machine this Agent may reach without asking
tab policy --flag "*prod*"stop anything that names production

See also: tab cap · tab ledger · tab guard

tab guard [allow|deny <id>]

Review what Agent Guard held or blocked: keep it blocked, or propose an allow to confirm in the console.

tab guard [--agent slug] [--filter pending|blocked|allowed|all]
tab guard allow <id> [--always [--pattern <p>]]
tab guard deny <id>

When Agent Guard refuses a call (deny, or ask under Codex), the call waits for a person, 45 seconds unless the Agent says otherwise. Allow it in that time and it runs there and then; otherwise it is refused and stays in the list.

deny keeps it blocked, there and then. allow only proposes: it prints a link and a code, and the call is allowed when you confirm it in the console, signed in. The agent can reach the terminal it runs in, and so tab's login, but not your browser session. Confirmed, the exact call runs if it is still waiting, else its next try within 10 minutes passes; --always also trusts one narrow rule on that Agent, the exact command by default (never a bare * or a shell by name). Other unanswered requests for that exact command on the same Agent are answered together, including expired requests; earlier answers are kept. Every decision is final and recorded with who made it.

tab guard allow and deny also refuse inside an agent tab launched, under a harness process (claude, codex and the rest), and without a terminal. The full command is read from this machine, where the agent ran, so what you propose is what you saw; the console's Agent Guard page can also decide, but not a call it could not show in full.

OptionWhat it does
--agent <slug>only this Agent's calls
--filter pending|blocked|allowed|allwhich calls to list (all by default)
--alwayswith allow: also trust that exact command on this Agent from now on
--pattern <p>with --always: the rule to trust instead of the exact command
ExampleWhat it does
tab guardwhat is waiting, and what was blocked
tab guard allow <id>propose letting that exact call run once; confirm in the console
tab guard allow <id> --alwayspropose trusting that exact command on its Agent
tab guard deny <id>keep it blocked

See also: tab policy · tab top

tab rename

Rename an Agent. Its slug, and so its console URL and .flocktab files, stay.

tab rename <agent> <name>

The display name changes everywhere. The slug is permanent so folders and links keep working.

ExampleWhat it does
tab rename landing-page "Landing page"change how the Agent is shown; its slug stays landing-page

tab key rotate [agent]

Mint a new key for an Agent, kept on this machine. The old one stops working.

tab key rotate [agent]

Keys look like ft_live_... and are stored hashed; FlockTab cannot show one again. The old key is refused (401 key_revoked) from the next call, on every machine that still holds it.

OptionWhat it does
--showprint the new key once, for a machine without tab
ExampleWhat it does
tab key rotatea new key for this folder's Agent; the old one stops working
tab key rotate landing-page --showprint the new key once, for a machine without tab

See also: tab use

tab project | projects

Group Agents under a project for chargeback (Team plan and up).

tab projects
tab projects add <name>
tab project [agent] <project>|none [--create] [--repo owner/name]

A project is a label on FlockTab's own meter: what these Agents spent, together. --repo links a GitHub repository so outside spend (Actions, storage) can be attributed to the same project.

With one word, tab project puts this folder's Agent in that project. With two, the first is the Agent (its name or slug, as tab list shows) and the rest is the project. Quote a project name with spaces. tab project help, like tab <command> help for every command, prints this page.

OptionWhat it does
--createmake the project if it does not exist
--repo owner/namelink a GitHub repository
ExampleWhat it does
tab projectsevery project in the flock
tab projects add "Landing page"make a project
tab project "Landing page"put this folder's Agent in it
tab project landing-page "Landing page"put another Agent in it: the first word is the Agent
tab project "Landing page" --create --repo acme/landingmake it if it is new, and link its GitHub repository
tab project nonetake this folder's Agent out of its project

See also: tab spend · tab outside

tab archive

Archive an Agent: it stops for good and its seat frees 24 hours later. Its history stays.

tab archive [agent]

The tab closes for good and the Agent leaves the lists. Its ledger rows stay.

Its seat frees 24 hours after archiving: until then it still counts towards the plan's Agents, and towards the Agents a Team flock pays for. The console's Archive agent (on the Agents page, and on the tab's page) does the same.

Changed your mind? tab restore brings it back (or Restore under Archived on the console's Agents page): within 24 hours it just comes back, keys and all; after that it needs a free seat.

Its keys stop working everywhere (the proxies answer key_revoked). A folder still bound to it asks for an Agent again on the next launch.

OptionWhat it does
--yesdo not ask
ExampleWhat it does
tab archive old-experimentclose it for good; asks first
tab archive old-experiment --yeswithout asking

See also: tab restore

tab restore

Bring an archived Agent back, with its tab, keys and history.

tab restore
tab restore <agent>

Without an Agent it lists the archived ones: when each was archived and when its seat frees, on your flock's clock.

With one (its name or slug) it comes back as it was: its tab opens again unless its own cap setting keeps it closed, its keys work again, and its history never left. The same as Restore under Archived on the console's Agents page.

Within 24 hours of archiving its seat never left, so it just comes back. After that it needs a free seat, as a new Agent would; when every seat is in use it says so, with when the next one frees, and nothing changes.

OptionWhat it does
--jsonthe list, or the restored tab, as JSON
ExampleWhat it does
tab restorelist the archived Agents
tab restore old-experimentbring it back

See also: tab archive

tab flock [<name>]

Names a live Claude Code, Codex or Antigravity session, so other agents can message it by that name.

tab flock
tab flock <name>
tab flock [<name>] --id <id>
tab flock --forget <name>
tab flock --json

tab flock <name> names the live session in this folder: a tab claude session (its band must be on), a Codex thread open in a Codex window, or an Antigravity (agy) conversation. With more than one in the folder, tab asks which in a terminal; elsewhere give --id with the session's id (Claude Code's conversation id, the Codex thread id, or agy's conversation id; the short id tab shows is enough). A short id is the first 8 characters, or more when another session starts the same way: Codex's thread ids begin with the time, so threads made minutes apart share their first 8. Inside Claude Code, /flock <name> names the session you type in. Inside tab codex or tab agy, ask the agent in plain words, such as "name this session reviewer": it names its own session with the flock tools (tab mcp flock). Codex has no /flock command, and its prompt refuses anything it does not know after a slash.

An agy session in tab agy can send and receive messages (see tab agy send). An idle agy reads a message only when you next type there.

Without a name, a Claude session takes the name you gave it with /rename, and a Codex thread its own name, so both names match. A name is letters, digits, dot, dash or underscore, up to 48; a name from /rename has its spaces made dashes.

One name names one session. A name another session holds is refused: pick another, or free it with tab flock --forget <name>. Naming a session again renames it, and its earlier names are kept. A session that ends keeps its name, shown as not live, until you forget it.

tab flock lists every named session: its name, Claude, Codex or agy, live or not, since when, and its folder. A live session also shows what it is doing: how long its current turn has run (Codex) and how many messages wait for it (Claude Code, Codex and agy), such as "busy for 45 min, 9 messages waiting". --json gives the same for scripts (waiting, busySince). The names live in ~/.flocktab/flock.json on this machine only. tab reads the sessions where Claude Code and Codex keep them and never changes them.

OptionWhat it does
--id <id>name this session, not the one in this folder
--forget <name>free a name; the session keeps running
--jsonthe list as JSON
ExampleWhat it does
tab flock reviewername the session in this folder reviewer
tab flockevery named session, live first
tab flock --forget reviewerfree the name

See also: tab claude · tab pool · tab codex send · tab claude send · tab agy send · tab mcp

tab codex send <name> <message>

Sends a message to a named Codex session and prints its reply.

tab codex send <name> <message>
tab codex send <name> <message> --wait <seconds>

The name is one tab flock gave a Codex session. The session must be open in a Codex window: Codex starts the message as that thread's next turn, at once when it is waiting, else when its current turn ends. Codex starts one waiting message each time a turn ends, so before it queues yours, tab says how long the current turn has run and how many messages go first. tab waits for that turn's reply and prints it. A message to a session that is not open is refused, since nothing would start it.

When the session runs from a plain tab codex and is busy, a message from a named session of the flock goes into its running turn instead of waiting (Codex's turn/steer), with the same words and framing. That turn's reply then ends the turn, so it can include the work the turn was already doing. When no turn runs, such a message starts a turn of its own (Codex's turn/start): Codex starts a queued message only when a turn ends normally, so after an interrupt the queue would wait until someone typed. tab starts a turn only while none runs, never into a running one. A message from a terminal or script, or one Codex refuses (a turn began just then, the turn just changed, a review or compaction, no answer in 5 s), is queued as above. When Codex was sent the message but did not answer in 5 s, it may have taken it, so tab does not queue it again (steer=unanswered): it runs at most once. bridge.log says which (steer=steered, steer=started, steer=unanswered, or steer=queued with the reason).

The message reaches the Codex agent as a message from you, or from the Claude, Codex or agy session you send it from (by its flock name), like anything a person types. tab runs nothing the message says. Every message is logged in ~/.flocktab/bridge.log with who sent it, to whom, its size and the time, never its words.

Inside tab claude and tab agy, the agent sends with the send_to_codex tool (tab mcp flock): ask it in words, such as "ask reviewer to check the diff". tab waits 10 minutes unless --wait says otherwise; --wait 0 sends without waiting. When no reply comes in time, the message stays queued and runs when the session is free.

OptionWhat it does
--wait <seconds>how long to wait for the reply (default 600; 0 sends and returns)
ExampleWhat it does
tab codex send reviewer "Check the diff in src/auth.ts and say what breaks"ask the Codex session named reviewer, and print its answer
tab codex send reviewer "Start on the next item when you can" --wait 0send without waiting for the reply

See also: tab flock · tab claude send

tab claude send <name> <message>

Sends a message to a named Claude Code session and prints its reply.

tab claude send <name> <message>
tab claude send <name> <message> --wait <seconds>

The name is one /flock or tab flock gave a Claude Code session. The session must run in tab claude with its band on: tab leaves the message in that session's inbox, and FlockTab's band in the session submits it once the session is idle, at once when it is waiting, else when its current turn ends. When messages already wait in the inbox, tab says how many go first. tab waits for that turn's answer and prints it.

A session takes messages only while it has a flock name: forget the name and its inbox stays shut. The message reaches Claude as a message from you, or from the session you send it from (by its flock name), framed as sent by FlockTab's plugin and never as a command. tab runs nothing the message says. Every message is logged in ~/.flocktab/bridge.log with who sent it, to whom, its size and the time, never its words.

Codex sends with the send_to_claude tool (tab mcp flock), and so do another Claude Code session in tab claude and agy in tab agy: ask any of them in words. tab waits 10 minutes unless --wait says otherwise; --wait 0 sends without waiting. When no reply comes in time, the message stays in the inbox and runs when the session is free.

OptionWhat it does
--wait <seconds>how long to wait for the reply (default 600; 0 sends and returns)
ExampleWhat it does
tab claude send lead "The review is done: 2 findings in src/auth.ts"tell the Claude session named lead, and print its answer
tab claude send lead "Build is green" --wait 0send without waiting for the reply

See also: tab flock · tab codex send · tab agy send · tab mcp

tab agy send <name> <message>

Leaves a message for a named Antigravity (agy) session.

tab agy send <name> <message>
tab agy send <name> <message> --wait <seconds>

The name is one tab flock gave an agy session. The session must run in tab agy, whose hook hands agy each waiting message before its next model call. A busy agy reads it between its steps. An idle agy reads it only when you next type there: agy has no way to start a turn from outside.

Only a session the flock names can send, so agy always knows who wrote: a Codex thread, a Claude Code session in tab claude, or another agy session. A plain terminal is refused. Messages go up to 20,000 characters.

The message reaches agy framed as one from that session, not from you, and never as a command. It cannot give agy any permission you have not given it. agy answers with its own flock tools, so its answer reaches the sender as a message. tab runs nothing the message says. Every message is logged in ~/.flocktab/bridge.log with who sent it, to whom, its size and the time, never its words.

Inside tab codex, tab claude and tab agy, the agent sends with the send_to_agy tool (tab mcp flock): ask it in words. tab returns at once unless --wait says how long to wait for agy to read it.

OptionWhat it does
--wait <seconds>how long to wait for agy to read it (default 0: leave it and return)
ExampleWhat it does
tab agy send designer "The header colours changed: check the new tokens"leave a message for the agy session named designer

See also: tab flock · tab codex send · tab claude send · tab mcp

tab mcp flock

The flock's MCP server, which tab codex, tab claude and tab agy give their agent: message a session by name.

tab mcp flock

tab codex adds it to its Codex config as flock, unless your own Codex config already has an MCP server named flock. tab claude gives it to Claude Code as flocktab-flock for that session only (with its band on), a name your own servers will not have. tab agy adds it as flocktab-flock to agy's MCP list in tab agy's own home, so your own list never has it. You do not run it yourself: the agent starts it.

Its tools: send_to_claude sends a message to a named Claude Code session and returns its reply (as tab claude send). In Claude Code and agy, send_to_codex does the same for a Codex session (as tab codex send). send_to_agy leaves a message for an agy session (as tab agy send), whose answer comes back later as a message. flock_name names this session (as /flock does in Claude Code). flock_list lists the named sessions. So you ask the agent in words, such as "ask reviewer to check the diff", and it sends the message and gives you the reply.

Two tools answer comments on tab pages: pages_threads reads the comment threads (those still waiting on an agent, or every thread on one page), and pages_reply answers one with this session's flock name. A reply shows on the open page at once.

A tool always acts for the session that calls it: Codex says which thread calls, tab claude's band file says which Claude session, and in tab agy the conversation lock agy holds says which agy conversation. When none says, the send, name and reply tools do nothing, so a message never goes out as you. The tools only write a message, a name or a reply. They run nothing a message says.

Codex asks you before each send_to_claude, since it reaches another agent; you can approve it for the session there. To never be asked, add [mcp_servers.flock.tools.send_to_claude] with approval_mode = "approve" to your own ~/.codex/config.toml. Naming and listing are never asked in Codex. Claude Code asks before a flock tool as before any MCP tool, unless your permission mode or settings allow it.

ExampleWhat it does
tab codexstart Codex with the flock tools; then type: name this session reviewer
tab claudestart Claude Code with the flock tools; then type: ask reviewer to check the diff
tab agystart Antigravity with the flock tools; then type: name this session designer

See also: tab flock · tab claude send · tab codex send · tab pages

tab pages [--to <name>]

Serves your agents' report pages on this machine, with a comment box on every item. Each comment can go to a flock session, and its reply shows on the page.

tab pages
tab pages --root <folder> --port <port>
tab pages --to <name>
tab pages --link <label>=<url>
tab pages import <folder> [--replace]

tab pages serves the HTML pages in docs/reports, docs/design, docs/roadmap and docs/manual folders under the root (this folder, or --root), on 127.0.0.1 only. It never serves another folder, a dot folder, or a link that leads out of them. It never changes a page. The index at / lists every page, newest first, with what each one asks of you and whether it changed since you opened it. A page asks with <meta name="needs-you" content="..."> in its head.

Each item on a page gets a Comment button: you write a comment, and paste or drop images into it. Your comments are blue, and an agent's replies are green. Each thread says who it waits on: the agent, you, or nobody. A new comment or reply shows on the open page at once. Links on the pages open in a new tab.

With --to <name>, each new comment goes to that flock session as a FlockTab message (a Claude Code or Codex session; tab flock lists them). A Claude Code session reads it when it is idle: at once when it waits, else when its current turn ends. The agent answers in the thread with its pages_reply tool (tab mcp flock). At most 20 comments are sent in 10 minutes. More are kept on the page, not sent.

Any program on this machine can post a comment, so the message says it came from tab pages and is never your approval for anything. Only the server's own pages can post: another site open in your browser cannot, and a site that points its own name at 127.0.0.1 gets nothing.

Comments, opens and images are kept in ~/.flocktab/pages. tab pages import <folder> copies another pages server's comments.jsonl, opens.jsonl and uploads in, and only reads that folder. If tab pages already has comments, add --replace: the ones there are kept aside, not deleted.

OptionWhat it does
--root <folder>serve the pages under this folder (default: this folder)
--port <port>the port on 127.0.0.1 (default 4748)
--to <name>send each new comment to this flock session
--link <label>=<url>a link at the top of the index; repeat for more
--no-comments <path>serve the pages under this path without the comment box, such as pages shown on video; repeat for more
--replacewith import: keep the comments there aside and import over them
ExampleWhat it does
tab pages --root ~/Development --to Orchestratorserve every page under ~/Development; comments go to Orchestrator
tab pages import ~/old-pages-servercopy the old server's comments in

See also: tab mcp · tab flock · tab claude send

Subscriptions and the pool

Agents that run on your own Claude, ChatGPT, SuperGrok or Kimi plan, and choosing between several logins of one vendor.

tab accounts

Every plan login your Subscription Agents were seen on, and how used it is.

tab accounts

Accounts are discovered, never typed in: the vendor names the login on every reply, and FlockTab files the call under it. Each row shows the plan, the seat price taken from the plan tier, what the last 30 days would have cost at list price, the number of calls, and the usage the vendor last reported per window. A ChatGPT login that has rate-limit resets banked says how many (2 resets banked).

The console shows the same under Setup, Subscriptions, where a label or a seat price of your own is set.

ExampleWhat it does
tab accountseach login, its plan, and how used each window is

See also: tab pool · tab agent

tab pool [add | pause | login | at | swap]

Several logins of one vendor on this machine; the agent runs as the one with most room.

tab pool
tab pool add claude|codex|grok|kimi <name> [--email <address>] [--dir <folder>]
tab pool login [claude|codex|grok|kimi] <name>
tab pool remove claude|codex|grok|kimi <name>
tab pool pause [claude|codex|grok|kimi] <name>
tab pool resume [claude|codex|grok|kimi] <name>
tab pool next [claude|codex|grok|kimi] <name>|off
tab pool spread [claude|codex|grok|kimi]
tab pool at [claude|codex|grok|kimi] [7d] <percent>|default
tab pool rebalance <points>|off
tab pool swap auto|launch

pool login <name> signs a login in again, in its own folder, with the vendor's own browser sign-in: for one whose sign-in expired (Claude says Not logged in). Name the vendor first when the same name is in more than one pool; in a terminal tab asks which. Windows already running on that login pick it up on their next call. On macOS tab reads when Claude Code last refreshed each login (the keychain entry's date, never the login): one not refreshed for three days is marked in tab pool as last refreshed N days ago, and the pool does not move onto it while another login has room.

A pool member is a folder the agent signs in to itself (CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME, KIMI_CODE_HOME). tab never reads, copies or forwards a login, and neither proxy holds one: tab only chooses which folder a launch uses. pool add opens the vendor's own browser sign-in and finishes by itself. The login then shows in the console under Subscriptions at once, before its first call: tab tells the console the account's id, email and plan tier as the agent's own files state them, never the login itself.

Usage is what the vendor last reported for that account. The short window (Claude's 5 hours, Codex's primary) decides: at or over the threshold, the login gives way. The long window (the week) is ignored until it reaches its guard, 95% unless set, and then the login gives way whatever the short window says. Among the logins under both, a new session goes to the one whose week most needs using: the room left under the guard per hour until that week resets, shared by the sessions already on it (any call in the last hour). A week that resets sooner, or is emptier, goes first, since what it has left expires unused at its reset; Claude's Fable week counts on its own. A week that has reset since the vendor last reported it (a login nobody used for over a week) counts as empty, with its whole length left. Where the vendor has not said when a week resets, the login with least of its five hours used goes first, then the emptier week. A login with less than 10 points of its week left under the guard (more than 85% used at a 95% guard) goes after every login with more room, for a launch and a move alike, since one busy agent spends a few points within minutes; it still runs when it is the only one under its limits. A login never seen through FlockTab counts as unused.

At launch tab takes the login that gives each session the most of a week: its room left per hour to its reset, split by the sessions on it, those on any machine that called in the last hour or those this machine started, counted at once. So sessions started one after another split across the logins in proportion to their room, rather than all going to the emptiest. A week running out at the pace of its last 6 hours (red in tab top) does not keep a login out: that pace counts the sessions on it, or just gone from it. A login added to the pool is used by sessions already running too, at their next look. While running (swap auto) it looks once a minute. When the login in use is over a limit and another is not, it waits until the agent is between two turns, never in the middle of one: Claude Code's conversation ends in a reply that finished (not one that asked for a tool), or a Codex started by a plain tab codex has no turn in progress, checked every 3 seconds, and this session has no call in flight and began none in the last 20 seconds. A move stops its background shells and Monitors too, so it also waits until none is running, however long that is, and tab pool shows holding: background job meanwhile. Only a login that is fully spent does not wait for them: they stop with the move, and a session still working 10 minutes after it had to move off that login, with Agent Guard on, moves between two tool calls instead (its next tool call is stopped with a note to run it again after the move). Other harnesses, and sessions where tab cannot tell, wait for a quiet moment instead (this session has no call in flight and began none in the last 20 seconds; other sessions do not hold it back). Then tab stops the agent and starts it again as the other login in the same conversation (Claude Code: with a first message saying it moved, to which login and when, and that its background jobs, Monitors, session crons and wake-ups from before the move are gone, so an agent re-arms what it still needs; the launch's own prompt is not sent again), reopened by its own id, so two sessions in one folder each come back as themselves (Claude Code: the conversation the window is in at that moment, as its status line last said, so after a /clear or /resume too; one where nothing was said yet starts again under the same id. Codex: when tab can tell which conversation was this run's; otherwise the folder's most recent, and tab says so). Windows move onto one login one at a time, about 90 seconds apart, so they do not all refresh its sign-in at once. When the harness ends at once on the new login, tab goes back to the one it came from, in the same conversation, and does not try that login again in this run. The vendor's prompt cache does not carry over, and anything typed but not sent is lost. Rebalance (30 points unless set) also moves a running agent off a login that is fine: once it has run 30 minutes where it is and another login would give it at least 1.5 times its share of a week (room left per hour to its reset, split by the sessions on it), as long as that login's five hours are at least that many points under the threshold. Where the vendor has not said when the weeks reset, a week at least that many points emptier. The margins keep two logins from trading places, and a move for balance waits for the same moment between two turns. Each move is written to pool-moves.log in tab's folder: when, from and to which login, why, and whether it was at the end of a turn, at a tool call or at a quiet moment. A running agent reads the pool's settings at every check, so changing them moves it within a minute. When every login is over, nothing moves (tab says so once), and at launch a login with a banked rate-limit reset (ChatGPT) runs first, else the least used.

pool pause <name> keeps a login in the pool, signed in, but takes it out of the choice: no launch picks it, and an agent already running on it moves to another login between two of its turns (swap auto). Use it for a login the vendor is refusing, or one you want to save. pool resume <name> brings it back. pool pause <name> --until-reset pauses it only until its week resets (for Claude, the general week and Fable's): then it comes back by itself, as a fresh login the pool can move load onto, and tab pool and tab top say paused until its week resets. A plain pause never ends by itself. Without a vendor, a name that is in more than one pool is paused or resumed in all of them. --as <login> still runs a paused login when you ask for it by name. When every login is paused, the launch says so instead of running. A login whose subscription has run out is also filed as full, with its reset, as soon as the vendor refuses a call, so the pool leaves it by itself.

pool next <name> forces a login next: every new launch for that vendor takes it first, whatever the others have left, as long as it is not paused and is under its limits (over one, the pool picks as usual until it is back under). Agents already running stay where they are. pool next off (or pool next <vendor> off) goes back to the pool's own pick; removing the login forgets it too. tab pool and tab top show the arrow on it.

pool spread (or pool spread claude) spreads out the agents already running: for the next 30 minutes, each session started before you asked moves once, at the end of its reply, when another login would give it 1.25 times its share of a week where it is (the share as under Rebalance, with the same margin on the five hours), without the 30 minutes it otherwise waits. Moves still go one per login every 90 seconds, and a session started since is placed by the pool's own pick. Without a vendor it spreads every pool with more than one login. In tab top, s does the same for the chosen login's pool (Claude's when none is chosen). Sessions started with an older tab do not take part: pause their login instead.

Members share your own conversations (~/.claude, ~/.codex, ~/.grok, ~/.kimi-code), so a conversation continues under another login and can be resumed with or without the pool. They also follow your global instructions: Claude's ~/.claude/CLAUDE.md, and the AGENTS.md in ~/.codex, ~/.grok or ~/.kimi-code, linked into each folder tab made (never copied, never over a file the folder has), checked at every launch. The pool lives in ~/.flocktab/pool.json on this machine only.

OptionWhat it does
--email <address>pool add: prefill the sign-in page (a name that is an email does this by itself)
--dir <folder>pool add: use a config folder you already have instead of making one
--pathspool: also show each login's folder
at <percent>the short-window threshold for every vendor (default 80)
at <vendor> <percent>one vendor's own threshold; default clears it
at [vendor] 7d <percent>the weekly guard (default 95)
rebalance <points>|offalso move a running agent for balance: to a login that would give it at least 1.5 times the share of a week it has now, once it has run 30 minutes where it is, and only to one whose five hours are that many points under the threshold (default 30). off: move only when a login is over a limit
swap auto|launchauto also moves a running agent when idle; launch only chooses at start
ExampleWhat it does
tab pool add claude me@example.comsign a Claude login in; the email is prefilled
tab poolevery login: plan, usage bar, each window and its reset, and which runs next
tab pool pause me@example.comkeep the login but run nothing on it until tab pool resume me@example.com
tab pool at claude 70Claude logins give way at 70% of the 5-hour window
tab pool at 7d 90any login gives way once 90% of its week is used (for Claude, the general week or Fable's own, whichever is fuller)
tab pool rebalance 20balance running agents too, onto logins whose five hours are at least 20 points under the threshold
tab claude --as me@example.compin one login for this run

See also: tab accounts · tab claude

See what happened

Read commands. Add --json to any of them for scripts and agents.

tab status

Which flock, which Agent this folder runs as, its tab's state, its kind, and whether the proxy answers.

tab status

The first thing to run when something is off. Exit code 0 only when the machine is logged in, the folder has an Agent with a key here, its tab is open, and the proxy is healthy.

A closed tab says who closed it; when the loop watch closed it, the row gives its verdict, such as "closed (loop watch): Stuck: repeating itself, no progress · stuck 2 of 2 in a row".

ExampleWhat it does
tab statusis this machine logged in, which Agent is this folder, does the proxy answer

See also: tab login · tab use · tab up · tab whoami

tab whoami

Which Agent this folder runs each harness as, and whether this machine's key for it works.

tab whoami

Only reads: it never asks, and never creates or keys an Agent. A folder with no Agent says so; a key the proxy refuses (key_revoked) is shown with the command that fixes it.

A launch whose key is refused stops the same way instead of starting the harness, and tab never creates an Agent from closed input: with nobody to answer (an agent's shell tool, a closed pipe) the picker stops and says so.

ExampleWhat it does
tab whoamithis folder's Agent per harness, and whether each key works here

See also: tab status · tab key · tab use

tab top [--every <seconds>] [--once]

The flock live in a scrolling screen: Agents, the leaderboard, subscriptions and their windows, the pool, outside spend, the ledger.

tab top
tab top --every 5
tab top --once
tab top --streamer

An always-on dashboard in the terminal, redrawn every 2 seconds (--every sets it): who is working and the Agents are read on every redraw, the logins, the pool and Agent Guard every 10 seconds, outside spend every 30, and r reads everything at once. When npm has a newer tab (asked every half hour), a line above everything says so: q, then tab update. At the top: the flock, its plan, Agents used of the plan's limit, whether the proxy answers. Then who is working right now, calls per minute, calls blocked and spend in the last 5 minutes (5m), with their trend; every Agent with its harness, project, spent of cap, calls per minute, calls blocked in the last 5 minutes and its last decision (an Agent run from two terminals at once, two `tab claude` launches in one folder, reads ×2, and the working count adds the sessions), and ctx, each of its sessions' context: for a Claude Code session on this machine, what its own status line last said (the harness's figure for the conversation); for one elsewhere, its largest call in the two minutes before its latest, cached input included, which can be a subagent's or a compaction's rather than the conversation's: amber to compact soon from 400k, red to /compact now from 800k, with how many sessions need one beside the Agents title (Claude Code's 1M window; a Codex, Grok or Kimi session shows its figure without colour), and a [compact] button beside the ctx when the Agent has a session on this machine due for one: a click runs /compact in each of those sessions, as if you typed it, once that session is idle, and the button reads compacting until it has (tab claude sessions started by this tab or newer), and polling: 9 of 12 loop checks stuck in 1h, in yellow, when the loop watch found an Agent stuck 3 or more times in the last hour, re-running the same check with its whole context each time (with the count beside the Agents title); every subscription login, grouped under the harness that runs on it (Claude, Codex, Grok, Kimi, each with its plan when its logins share one, how many logins it has and how many are in the pool, and with two or more pooled, whether the pool lasts: its logins' room up to the weekly guard, drawn down at their 6-hour paces together, the room of the week that resets soonest first, and filled again as each week resets, so pool lasts, or pool runs short in 6h 00m in red, then the next fresh week, the login that resets soonest and when; a login paused until its reset counts from then, when it comes back by itself, and its row says paused · back in 1d 16h, while a plain pause never counts), one line each: its week (for Claude, the worse of the general 7d and Fable's own week) and how long until it resets, in green, yellow or red by its pace, then at this pace in words: ok · ends at 70% (green, it lasts), tight · ends at 93% (yellow, 90% or more) or out in 1d 02h (red, it runs out before it resets; a pool login that runs out alone while its pool lasts reads out in 1d 02h · pool covers, in yellow), with a green ↓ when the last 3 hours rose slower than the 3 before and a red ↑ when they rose faster, by 2 points or more (no arrow: steady, or no reading from 6 hours ago), so you can see whether things are getting better, and not in use, in grey, for a paused pool login no Agent called in 10 minutes, where the pace is the last 6 hours only, a trailing check, so a week spent fast early on does not count once the flock slows down (no 6h data yet, in grey, until the console has a reading from 6 hours ago; the pool treats it as lasting), then its 5h figure in the same colours, the rate-limit resets a ChatGPT login has banked, a limit the vendor trimmed (5h limit ↓22%, while the console's Subscriptions page marks it), and the pool's next pick marked, with the Agents that called on that login in the last hour named under it and how many more are idle there (no line when none called; an Agent whose sessions run on several logins shows under each of them, at its latest call there) (an Agent shows only under its own vendor's login: a Claude Agent under Claude, a Codex Agent under ChatGPT, even when both logins share an email), and a warning when a pool login is signed in as another account than the one it is named for, with the tab pool login command that fixes it; outside spend by project over the last 30 days with the unattributed share; and the ledger's latest decisions as they happen. Under the Agents, Branches today, in your flock's time zone (Settings), not this machine's: each branch a tab session was on (with its pull request number in front when the GitHub CLI, gh, is signed in on your machine), with what went on the tab, subscription use at list price and the share of each login's week it took (≈), the minutes with calls and the sessions (the Projects page has the last 30 days). Branches are read every 30 seconds. Then the Leaderboard for your flock's day (midnight in the flock's timezone), with the week's biggest token user beside its title: Token hogs (most tokens in and out per Agent), Speed demons (the fastest models by median output tokens per second, once a model has 5 timed calls), Peak pace (each Agent's busiest minute and the flock's, with when), Big spender (the single priciest call at list price) and Cache champ (the biggest share of input read from cache, once an Agent has 5 calls). When one of them is broken while you watch (a new first place, a busier minute, a pricier call), a line reads 🏆 new record for 30 seconds. The boards are read every 30 seconds. Calls settled by a proxy older than the boards have no timing or cache count and are left out of those two. Tally, FlockTab's sheepdog, sits beside the header in a colour terminal at least 24 rows tall: he trots while Agents work, barks when calls are blocked or the proxy is down, and wags when all is quiet. On a dark background he wears a lighter coat so he does not vanish: tab top asks the terminal for its background colour (or reads COLORFGBG), and t switches his coat by hand and keeps the choice.

The header (Tally and the totals) stays put and everything under it scrolls: every Agent, every login, every outside project and the whole ledger tape are there, never cut to fit. ↑/↓ or j/k move a line, PgUp/PgDn or space/b a page, g or Home the top, G or End the bottom, and the mouse wheel three lines. A dim footer says which lines you are looking at when there is more than the screen holds, and a refresh keeps your place.

--streamer draws the same screen for showing to others: every login, email, Agent, project, branch and pull request title is drawn under a made-up name (amber-fox, amber-fox@example.com), wherever it appears. Free text that could name a folder, a file or a client is hidden: the tape shows the verb and the file's extension (edit .rb) or the harness's own tool names, Agent Guard shows the tool and its scores but not its summary or reasons, and errors read as a fixed phrase. Each real name always gets the same made-up one, so viewers can still follow who is who. The flock's name, models, harnesses and numbers stay. The keys and buttons still act on the real logins. Works with --once too.

On a Mac the Agents table also says what each Agent's sessions cost this machine: cpu (one core is 100%, so a busy Agent goes past it, in yellow), mem and proc. An Agent's sessions are the harness tab started and every process under it: MCP servers, language servers, dev servers, tool shells, and one left running after its shell ended. tab top finds them by the Agent tab named when it launched the harness, which each of them inherits. mem is each process's memory footprint (top's MEM, the Memory column of Activity Monitor), which counts what macOS compressed or swapped out of it too, not the resident size alone. Processes are read every 10 seconds and memory every 30, at the lowest priority; an Agent with nothing running here shows -. The screen never waits for the memory read (several seconds on a busy Mac), so mem shows - for its first few seconds; tab top --once waits for it. The section line adds up the flock's Agents on this Mac, and Agents of another flock running here get a line of their own.

Each pooled login in Subscriptions has two buttons, [pause] and [next]: click one, or press Tab (Shift-Tab back) to choose a login, then p to pause or resume it, u to pause it until its week resets (a paused login too, so its pause ends then), and n to force it next for new launches or clear that (tab pool pause, tab pool next). The login shows paused or forced next, and the arrow moves to the pool's new pick at once. Running agents stay where they are, except one on a login you pause, which moves between two of its turns. s spreads the running sessions of the chosen login's pool (Claude's when none is chosen) across its logins, as tab pool spread does.

It opens at once on the screen from your last run (kept in tab's folder, for the same flock), with a line saying how old it is, until its first read lands a moment later; the first time, the panels are empty until then. q, Escape or Ctrl-C leaves at once, even in the middle of a read, and the terminal is as it was, mouse included; r redraws at once. --once prints everything once and returns, for a pipe or a quick look. A panel the console cannot answer on a tick is a line above the footer, and the last good read stays on screen. Everything but cpu, mem, proc and this machine's sessions' ctx comes from the console the other commands read, so nothing here disagrees with tab list, tab pool, tab accounts or the Console.

OptionWhat it does
--every <seconds>how often to redraw (default 2, 1 to 3600)
--onceprint everything once, then return
ExampleWhat it does
tab topthe live screen; q quits
tab top --every 5redraw every 5 seconds
tab top --streamerthe same screen with made-up names, to show on a stream
tab top --onceprint it once, for a script or a screenshot

See also: tab list · tab pool · tab accounts · tab live · tab status

tab statusline [harness]

One line for a harness's status bar: the Agent and its tab, or the plan's windows.

tab statusline [claude|codex|grok|kimi]
tab statusline claude --only-tab
tab statusline install grok|kimi

Prints what this folder runs the harness as, then either spent of cap for an API-key Agent or, for a subscription, the login in use and each window's usage as the vendor last reported it (5h 36% · 7d 29%). On a pooled run it names the pool login the run is on and how many logins the pool has (pool me@x.com (4)). Read from the console at most once a minute, so a status bar that refreshes every few seconds costs nothing.

In Claude Code it also says when to compact, from the context the last call sent (Claude Code reports it on every refresh): ctx 517k · compact soon in amber from 400k tokens (the same line the console's Overview tip uses, because cost and a subscription's usage follow what every call sends) or when the window is 60% full, and ctx 850k · /compact now in red only when the window is 80% full, just before Claude Code compacts on its own. Nothing below that. NO_COLOR drops the colour.

Auto-compact, in a tab claude session with FlockTab's band: when the context crosses 400k, tab asks the session for /compact, as [compact] in tab top does, but only while the session is quiet: its last message a finished reply (not busy, not waiting on a permission prompt or a question) and no background job or Monitor running. It asks once per crossing, never again until the context has fallen under 300k (as a /compact does) and crossed again, and writes each ask to auto-compact.log in tab's folder with the Agent, the session and the time. FLOCKTAB_AUTO_COMPACT=off turns it off. It cannot see a background subagent or a Workflow still running in the session (they are not shells), so turn it off for long background work until that is tested.

Your own status line stays. tab runs it first (Claude Code's from settings.local.json or settings.json, Grok's and Kimi's from their config, with the same stdin the harness gives) and adds its own line after it, every line of yours kept. When yours takes over 4 seconds, as it can under load, tab shows the last line it gave in that conversation, for up to a minute, instead of none. Claude Code shows the pair on every tab claude, passed on the command line so no file of yours is touched (your own --settings wins). Grok Build and Kimi Code read a status line only from their config; a pool member gets it (that home is tab's), and tab statusline install grok|kimi puts it in your own config after asking: the file is backed up next to it first and a command already there is set aside and keeps running first. Codex takes no command and already shows its own limits.

On Claude Code 2.1.287 or later, tab claude also loads FlockTab's own band: a Claude Code mod (flocktab-tab) that draws this line above the prompt, beside the lines of any other mods. Your own status line under the prompt stays as it is, in tab claude and in plain claude: only FlockTab's part moves to the band. The band leaves one blank row above itself when it has a row to spare; in a short window its rows come first. FlockTab always shows in exactly one place: when the band cannot draw it (its tab cannot be asked), the status line keeps it. In a folder on no tab, the band says not on a tab, with tab use claude to fix it. FlockTab's row reads like the other mods' rows: FlockTab, then the numbers (spend, or the plan's windows), then the rest dim; the notifications tip shows only when a number is at 80% or more. Where the band draws, FlockTab's line and tip are the band's alone: tab's status line never adds them, from the first render on. That holds for tab claude and for plain claude with the plugin from tab setup claude, even when an older setup left tab's status line in your settings. With Claude Code's mods turned off, or on Claude Code before 2.1.287, the status line keeps FlockTab's part as before. A fullscreen window too short for all of FlockTab's lines shows the first ones, which it draws first. The band draws in the terminal and the Desktop app, not in VS Code's chat panel or claude -p. Nothing to install: it comes with tab and loads for that session only; tab setup claude can also install it for plain claude and the Desktop app.

--only-tab prints FlockTab's part alone, reading no stdin and running nothing of yours: what FlockTab's Claude Code plugin shows outside tab claude. It prints nothing in a folder that is not on the tab.

ExampleWhat it does
tab statusline claudethe line, as Claude Code's status bar would show it
tab statusline install grokadd it to ~/.grok/config.toml

See also: tab status · tab accounts

tab log [-f] | log --proxy

Everything that went through the tab, one line per call.

tab log [-f] [--all] [--lines N]
tab log --proxy [-f]

tab log reads the flock's ledger and shows the calls of the Agents keyed on this machine: time, Agent, what was called, tokens in and out, the amount, and the outcome (settled, subscription, refunded, blocked and why). It works the same on hosted and self-hosted.

tab log --proxy (also tab logs) is the self-hosted proxy's own log on this machine: one line per call with the vendor, model, status, cached tokens and milliseconds. Neither log ever contains a key, a login, a prompt, an email or an IP address.

OptionWhat it does
-ffollow: keep printing new calls
--allevery Agent in the flock, not only this machine's
--lines Nhow many to start with (30)
--proxythe local proxy's log instead
ExampleWhat it does
tab log -ffollow the calls as they happen
tab log --all --lines 50the last 50 calls of every Agent in the flock
tab log --proxy -ffollow the self-hosted proxy's own log

See also: tab ledger · tab live

tab ledger

One row per call, with the hold and what it settled at.

tab ledger [agent]

SETTLED $0.08 of $0.14 held means $0.14 was held before the call and $0.08 was the real cost; the rest went back. REFUNDED means the provider failed and nothing was charged. SUBSCRIPTION is a call on your own plan, priced at list and not charged. BLOCKED names the rule that refused it.

OptionWhat it does
--limit Nhow many rows
--blockedonly refused calls
ExampleWhat it does
tab ledgerthis folder's Agent, one row per call
tab ledger landing-page --blockedonly the calls refused for that Agent
tab ledger --limit 100more rows

See also: tab log · tab spend

tab spend

What was spent through the tab, and outside it, grouped: by Agent, project, day, or model and effort.

tab spend [agent|project|day|model]

Meter spend is what went through FlockTab. Outside spend is what the connected billing sources report (Team plan and up), so the two can be told apart.

tab spend project is the last 30 days for every figure, as the Projects page: each project's meter (committed calls), its outside spend and the unattributed outside; --since does not change it.

tab spend model lists each model with the reasoning effort the requests asked for (OpenAI's reasoning effort, Anthropic's effort or thinking budget), how many calls, what they cost and how they were paid: charged to a tab, or priced at list on a plan. The console shows the same under Spend, Models.

OptionWhat it does
--by agent|project|day|modelhow to group
--since 7dhow far back
--agent <agent>only one Agent
ExampleWhat it does
tab spend model --since 30da month per model and effort

See also: tab outside · tab ledger

tab outside

The outside-spend connections and their totals per project.

tab outside

Connections are made in the console (Spend, Outside spend): provider admin APIs and cloud billing. They answer whether a dollar went through a tab or around it.

The console pulls every connected source on its own, once an hour; the last sync shows per connection.

ExampleWhat it does
tab outsideeach connection and its spend per project

See also: tab spend · tab project

tab live

Who is active right now.

tab live

Each Agent's pulse (active, quiet, idle, stopped), calls per minute and last decision. Active means a call was admitted in the last minute. Quiet means calls in the last five minutes, but not the last minute.

OptionWhat it does
--watch Nrefresh every N seconds
ExampleWhat it does
tab livewho is active right now
tab live --watch 5refresh every 5 seconds

tab web

Open the Agent's page in the console.

tab web [agent]

Opens this folder's Agent when none is named.

ExampleWhat it does
tab webthis folder's Agent in the console
tab web landing-pageanother Agent's page

Self-hosted proxy

Provider keys stay on your machine; the ledger stays on flocktab.com.

tab up | down

Start or stop the self-hosted proxy on this machine.

tab up
tab down

The self-hosted proxy is one binary (flocktab-proxy). Your provider keys live in ~/.flocktab/proxy.env on this machine, owner-only, and never reach FlockTab. The proxy asks flocktab.com to hold, settle or refund each call with the Agent's own key, so caps, policies, the kill switch and the ledger work exactly as on hosted.

tab up offers to add provider keys while the machine has none (typed without echo, each one can be left blank), starts the proxy on 127.0.0.1:8787 and waits until it answers. tab claude on a self-hosted machine starts it by itself when it is down, and never asks for keys.

A self-hosted machine needs no provider keys for subscription Agents (your Claude, ChatGPT, Grok or Kimi logins): their calls pass your own login through the proxy. With no key for a provider, an API-key Agent's call to it is refused with "no <provider> key on this machine", before any hold; add the key with tab up.

A hosted machine that only runs subscription Agents needs no tab up at all: its calls go through flocktab.com. There tab up says so instead of asking for keys.

When FlockTab can't be reached, tab claude says which part is down (the proxy, all of FlockTab, or this machine's own connection) and links flocktab.com/status. Self-hosting doesn't help then: the proxy still settles every call with flocktab.com, which is what keeps the cap and the kill switch working.

tab down stops the proxy that tab started. Anything running through it is cut, so stop your agents first.

ExampleWhat it does
tab upstart the self-hosted proxy; offers to add provider keys while it has none
tab downstop it

See also: tab log · tab update · tab status

This machine

The CLI itself.

tab update

Install the newest tab from npm, and with it the newest proxy.

tab update
tab update --quiet

Restarts a self-hosted proxy that was running, so it runs the new version. Stop your agents first on a self-hosted machine. A proxy started with provider keys in its environment (not saved in proxy.env) is left running instead, with the keys a restart would drop named: restart it yourself with them set.

In a colour terminal, Tally asks npm for the newest version first, trots beside the install (in the coat tab top gives him: the one t chose, else lighter on a dark background), and ends with the new versions and two or three lines on what is new. Already on the newest, nothing is installed. If npm does not answer, nothing changes and tab exits non-zero.

--quiet (or -q), a pipe or NO_COLOR prints plain lines and always reinstalls from npm.

Then the new tab brings FlockTab's Claude Code plugin to its own version wherever it is installed (tab plugin update), in one line.

ExampleWhat it does
tab updatethe newest tab and proxy
tab update --quietplain lines, for a script

See also: tab version · tab plugin

tab plugin

Bring FlockTab's Claude Code plugin to this tab's version, in every scope it is installed in.

tab plugin update

tab update runs it after an update. It does nothing when the plugin is not installed (tab setup claude installs it), and says so in one line when claude is not on PATH.

A copy installed at project scope for your home folder (Claude Desktop puts one there) is left alone: removing it also turns the user install off, so tab prints the two commands instead.

ExampleWhat it does
tab plugin updateupdate the plugin now

See also: tab update · tab setup

tab config [list|get|set|unset]

See and change tab's settings on this machine, like desktop notifications.

tab config [list] [--json]
tab config get <key>
tab config set <key> <value>
tab config unset <key>

tab config lists every setting with its value (default when you never set it), then what this machine is logged in as: the flock, the mode, the proxy and the console. It never shows the session, the unlock or a key. set refuses a key that does not exist or a value its key cannot take, and changes nothing then; unset puts a setting back to its default. Settings live in ~/.flocktab/settings.json, apart from the login, so tab logout keeps them.

notifications (off by default): a desktop notification when tab claude waits for your answer or permission, when Agent Guard holds a call for your review or blocks one (any harness), and when the conversation is close to compacting. Each names the Agent, the folder and what happened, never what the agent wrote or ran. On a Mac it uses terminal-notifier when installed, else the Mac's own notifications; notify-send on Linux; none on Windows yet. Claude Code's notices come from hooks in a plugin folder of tab's own, added to each tab claude started after you turn them on: no file of yours is changed.

notifications.waiting, notifications.guard and notifications.compaction turn each kind off on its own (all on by default). notifications.contextPercent (85) is how full the context is before the compaction notice, once per conversation. While notifications are off the status line says how to turn them on; tips.notifications false hides that tip.

ExampleWhat it does
tab configevery setting and this machine's login
tab config set notifications ondesktop notifications from the next tab claude
tab config set notifications.contextPercent 90the compaction notice at 90% instead of 85%
tab config set tips.notifications offhide the status line tip without turning notifications on

See also: tab notify · tab statusline

tab notify

What tab claude's notification hooks run; you do not need to.

tab notify waiting|compacting

Shows one desktop notification of that kind for the folder Claude Code names on stdin, if notifications are on (tab config). It reads nothing else from the hook and prints nothing.

ExampleWhat it does
tab notify waiting < /dev/nulltry it: one notification for this folder, when they are on

See also: tab config

tab version

The versions of tab and of the proxy it carries.

tab version

A proxy that is older than tab can miss features; tab says so when it notices.

ExampleWhat it does
tab versiontab's version and the proxy's

tab logout

End this machine's session on FlockTab and forget it here, with its Agent keys.

tab logout

Ends this machine's session on FlockTab first, so the links its launches put in the proxy path stop working at once; other machines stay signed in. That call waits at most 3 seconds: if the console cannot be reached, tab still signs out here and says so, and you can revoke the machine in the console.

Removes ~/.flocktab/config.json. The pool, the proxy's provider keys, your tab config settings and each folder's .flocktab are left alone. The Agents and their history are untouched on FlockTab.

ExampleWhat it does
tab logoutforget this machine's session and keys; tab login brings them back

See also: tab login

Environment

For CI and scripts, where there is no folder to ask and nobody to approve a login.

VariableWhat it does
FLOCKTAB_KEYThe Agent's virtual key. With it set, no folder or login is consulted.
FLOCKTAB_UNLOCKThe flock's unlock, for a hosted API-key Agent.
FLOCKTAB_PROXY_URLThe proxy to use; tab login does not ask when it is set.
FLOCKTAB_HOMEWhere tab keeps its files, instead of ~/.flocktab.
FLOCKTAB_CALL_LOG=0Self-hosted proxy: turn the per-call log line off.