tab

Run any AI agent on a FlockTab tab. Needs Node 22 or newer; nothing else.

npm i -g @hanamorilabs/tab
tab login          # once per machine: opens the console, approve this machine
cd my-project
tab claude         # first run here asks which Agent this folder runs as (or makes one)
tab codex          # same Agent: it is in ./.flocktab
tab grok           # Grok, routed to xAI through the tab
tab kimi           # Kimi, routed to Moonshot through the tab
tab aider --model gpt-4.1   # anything else: both APIs pointed at the tab

Login is per machine, the Agent is per folder. tab login approves the machine for your flock and stores a session in ~/.flocktab/config.json (owner-only). The first tab claude or tab codex in a folder lists your Agents, lets you pick one or create one ($50 cap, change it in the console), mints that Agent's key for this machine, and writes .flocktab with the Agent's name. No secrets in .flocktab, so commit it if you like; a teammate's first run mints their own key. tab use changes the folder's Agent. A new Agent takes the name and project of the folder's Agent under another harness (so tab claude after tab codex in one folder gives dash-f4f twice, slugs dash-f4f-codex and dash-f4f-claude); otherwise the folder's name, linked to the project it is named like or that Jev judges it belongs to.

tab <agent> sets the variables that agent reads and runs it with your terminal attached. Claude Code reads ANTHROPIC_BASE_URL; everything else reads OPENAI_BASE_URL. Codex is special: a ChatGPT login or a custom provider in ~/.codex would beat the environment, so tab codex gives it its own home under ~/.flocktab/codex pinned to the tab, and never touches ~/.codex. The proxy serves the OpenAI chat and Responses APIs and the Anthropic Messages API, so the same tab, cap and kill switch apply whichever one the agent speaks.

The key the agent presents is ft_live_<secret>.<unlock>. On a hosted flock the unlock decrypts your provider key on the proxy for that one request and is never stored on the server; tab asks for it once, when the first Agent is keyed, and keeps it in the config file so tab claude is one command. Set FLOCKTAB_PROXY_URL, FLOCKTAB_KEY and FLOCKTAB_UNLOCK instead when you would rather not have a file or a folder, for example in CI.

On a subscription (Claude Max, ChatGPT, SuperGrok, Kimi)

An Agent is api (the flock's provider key, metered) or subscription (the harnesses' own logins), chosen when it is made: the first tab claude in a folder asks, or

tab agent create "[email protected]" --subscription
tab use              # this folder runs as it
tab claude           # your own Claude login through the tab
tab codex            # your own ChatGPT login (codex login once, inside tab codex)
tab grok             # your SuperGrok login
tab kimi             # your Kimi Code login
tab accounts         # accounts seen: plan, seat price, 30 days at list, how much is used
tab pool add claude work   # another Claude login in its own folder; tab claude then runs as the one with most room
tab pool             # the logins, and how used each is; tab pool at 80 sets when to move
tab agent kind [email protected] api   # back to the meter

The plan pays for the tokens; the tab still gates every call (kill switch, velocity, model and tool policy) and records it at list price as a SUBSCRIPTION row that never touches the cap. The account is not declared: the vendor names it on every reply (Anthropic's organization id, ChatGPT's account id, the login token for xAI and Kimi), FlockTab files the call under it, learns the email and plan tier, and prices the seat from the tier. Four Max accounts are four accounts; claude /login to another one mid-session and the next call lands on it. Claude Code gets ANTHROPIC_BASE_URL=<proxy>/t/<key>/anthropic and no API key; Codex a home whose chatgpt_base_url is the passthrough; Grok Build GROK_XAI_API_BASE_URL; Kimi Code KIMI_BASE_URL. docs/subscriptions.md has the wire.

Self-hosted

The proxy runs on your box and holds the provider keys; the ledger, tabs and kill switch stay on flocktab.com. It is one small Rust binary. tab up asks for the keys once (typed without echo, saved owner-only to ~/.flocktab/proxy.env), fetches flocktab-proxy for this machine into ~/.flocktab/bin, and starts it in the background (log: ~/.flocktab/proxy.log). tab down stops it; tab update installs the newest tab, which brings the newest proxy, and restarts it; tab claude starts it when it is down. No Docker, no Rust, no checkout: the binary comes with tab as the @hanamorilabs/flocktab-proxy-<platform> package for your machine. Then tab login, pick 2 Self-hosted: the proxy says which console it settles through, so the device code lands on flocktab.com. No unlock in this mode; Codex shows FlockTab - Self-hosted as its provider.

Commands

tab help lists every command by group. tab help <command> (or tab <command> --help) explains one in full: what it does, its options, examples. tab help glossary says what is what, tab help errors lists every refusal and what to do. The same reference, with how the system works, is in the console under Docs (console.flocktab.com/docs).

tab login            approve this machine in the console, once
tab <agent> [args]   claude, codex, grok, kimi, gemini, or any command, on the tab
tab use              pick or change the Agent this folder runs as (.flocktab)
tab agent create <name> --subscription|--api   a new Agent of that kind (--cap 50)
tab agent kind <agent> api|subscription        change it
tab accounts         accounts your subscription Agents were seen on: plan, price, quota used
tab pool             several logins of one vendor: add claude|codex|grok|kimi <name>, at [vendor] <percent>, swap auto|launch
tab alias setup <name>...   make plain `codex` run `tab codex` (shims in ~/.flocktab/bin)
tab alias remove <name>...  undo that; `tab alias list` shows them
tab status           flock, folder Agent, proxy health, provider key state
tab log [-f] [--all] everything through the tab for this machine's Agents, one line per call
tab log --proxy [-f] self-hosted: the local proxy's own log (cached tokens, milliseconds)
tab version          tab and proxy versions
tab up | down        self-hosted: start or stop the local proxy
tab update           the newest tab and proxy from npm; restarts a running local proxy
tab logout           forget the session and keys on this machine
tab help             this list

The console from the terminal

Everything the console does to a tab, tab does too, with the machine session from tab login. An Agent is named by slug or name; left out, it is this folder's Agent. Every read takes --json.

tab list                                 every Agent: kind, state, spent of cap, window, project
tab close my-project        tab open my-project   the kill switch (402 tab_closed on the next call)
tab cap my-project 25 --window week         cap in dollars, and the window
tab rename my-project "My project (nightly)"     the slug stays
tab policy my-project --velocity 60 --models gpt-5,claude-sonnet-5 --allow email.send
tab project my-project Foley --create       attribute to a project (--repo owner/name; none clears)
tab projects add Foley                   projects
tab key rotate my-project [--show]          new key, kept on this machine; --show prints it once
tab archive my-project                      closes for good, leaves the bill (asks first; -y skips)
tab ledger [my-project] --limit 20 --blocked   one row per call: settled of held, status, reason
tab spend [agent|project|day] --since 7d    meter and outside spend, the console's numbers
tab outside                              connections, per-project outside spend, unattributed
tab live --watch 4                       who is working now, refreshed every 4 seconds
tab web [my-project]                        the Agent's console page in the browser

Aliases: plain codex on the tab

tab alias setup codex claude
export PATH="$HOME/.flocktab/bin:$PATH"   # once, in your shell rc
codex                                     # now runs: tab codex
tab alias remove codex                    # back to the plain codex

tab alias setup writes a shim named after the command into ~/.flocktab/bin (codex.cmd on Windows). With that folder first on PATH, the plain command runs on the tab. When tab spawns the real agent it removes its own shim folder from the child's PATH, so nothing loops. tab alias list shows them; tab alias remove <name> deletes the shim, and the plain command is the real one again. Prefer a shell alias? alias codex='tab codex' in your rc does the same for that shell only.

Secrets and colour

The unlock and provider keys are typed with echo off (raw mode); the unlock is checked against the proxy before saving; a wrong unlock is refused, and tab status says unlock ok or unlock is WRONG. The check is GET /v1/whoami with the unlock, which decrypts the envelope in memory and answers ok/wrong, never the key. Output is coloured on a terminal; NO_COLOR turns it off, FORCE_COLOR turns it on for pipes.

Status

tab status
proxy   http://127.0.0.1:8787  (self-hosted)  up
flock   Hanamori Labs
folder  flocktab-codex
plan    team
kind    api (the flock's provider key, metered on the tab)
byok    provider keys on this box

Trying a change before it is released

tabdev is this checkout's CLI run from source, beside the tab npm installed. It keeps everything of its own: ~/.flocktabdev for the login, keys, pool and proxy files, and .flocktabdev as the per-folder file. Nothing it does touches the production tab. Log it in once with tabdev login, and give its folders Agents of their own: choosing an Agent that production already holds a key for would replace that key (it asks first).

node apps/tab/scripts/link-dev.mjs            # writes ~/.local/bin/tabdev
tabdev version                                # "0.1.x + dev (this checkout's source)"
tabdev claude                                 # exactly what the next release would do
node apps/tab/scripts/link-dev.mjs --remove