Agent 007

Manage your coding agents by talking to them, from your phone.

The operations layer for Claude Code and Codex: agents take work from a board, one manager agent reviews and merges what they ship, and you hear about it on a call.

A Talk to Billion call, from the request to the merged PR: watch the 38s video with sound. Scripted demo with stand-in agents, sped up; voices are text-to-speech (scripts/demo/phone-call.mjs).

• A job board your agents work from. Each card gets its own git worktree, a Claude Code or Codex worker and a real terminal you can type into, and ends as a pull request (or a summary, for work that isn't code).
• One manager agent, Billion. Give it a goal: it posts the cards, reviews the diffs, merges the PRs, and brings you only what needs a person (money, access, security, anything irreversible) in a briefing twice a day.
• Agents that find the right skill. Claude Code fits every installed skill's description into about 1% of its context window; past a hundred or so skills most show as a bare name and get missed. Agent 007 groups them into skill families: its agents see one line per family, and each card lists in full the families its job needs.
• Talk to it from your phone. Open it in your phone's browser over Tailscale (agent007 install --remote), tap Talk to Billion, and hear progress spoken back. One command installs it as a service; Settings has an Update button, with a What's new window listing the changes first.

The Billion tab

Recorded from the running app, with stand-in agents so the run is repeatable (scripts/demo/record.mjs) -- full 43s video. If the capture does not load, there is a still screenshot.

From web terminals for your coding agents to a self-running agent company. Use it as far along as you need:

1. One task: one agent in a web terminal. Start Claude Code, Codex or any CLI agent in the browser. Add a repo once; every agent gets its own git worktree and branch, so you never set one up by hand.

2. Many tasks across projects: many terminals, one window. Every repo and every agent in one place, with live terminals, a file explorer, inline diffs, and a pixel office where each agent faces its screen while it works and turns to you when it needs you.

   

3. Stop watching them: a job board. Put tasks on the board and Claude Code or Codex workers pick them up, each in its own worktree, and move them To do -> In progress -> Review on their own, landing as a pull request (or a summary, for work that isn't code). Cards can run Now, be Scheduled for a chosen time, or be Recurring on a cron schedule, and pick their model (strong for hard code, fast for docs), from the models the board finds installed, and agents can post cards and message each other.

4. Stop posting jobs: give Billion a goal. Billion is one always-on agent that plans, posts the jobs, reviews what comes back and merges the PRs. It only asks you about money, access or anything irreversible.

Claude Code, Codex, any terminal agent is supported -- use your existing subscriptions, no extra charge.

It runs locally on your machine, so agents work while it is on and awake. Billion's plan and memory live in a git repo, so it picks up where it left off after a restart. Every worker is a real terminal you can open and type into, from your phone too (remote access).

If you already run your agents this way with Claude Code and a few scripts, great: tell us what you'd do better. If you're tired of being the one who operates them, try this.

Quick Start

To try it:

npx @bill10/agent-007

For daily use, install it and run it as a service, so it starts at login and keeps running after you close the terminal:

npm i -g @bill10/agent-007
agent007 install

Or run agent007 in a terminal (agent-007, the older name, works too). See Run it as a service.

To reach it from your phone or another machine, with Tailscale installed and logged in:

agent007 install --remote   # then open https://<this machine>.<tailnet>.ts.net on any device in your tailnet

On a VM behind Cloudflare Tunnel + Access, caddy or nginx instead: agent007 install --public-url https://agent.example.com. See remote access.

Or run it from a clone:

git clone https://github.com/bill10/agent-007.git && cd agent-007
npm install
npm start

Open http://localhost:7007. It opens on the Billion tab's chat, where Billion, the agent that runs the board, introduces itself and asks for your mission and where new repos should go; answer in the chat. Billion runs on Claude Code, so install it and log in first (claude auth login); if it is missing or logged out, the chat says so. Its questions show as it asks them until its first round (08:30 or 15:30), then come twice a day.

Add a repo with the + in the left panel's Repos header (or ask Billion to), then click + Job to queue work on the board, or + Agent to start one by hand -- preset buttons (Claude Code, Codex, Gemini, Bash; PowerShell on a Windows server) fill in the command, or type your own under Advanced. A card that ends in a pull request needs a GitHub remote on the repo, gh signed in, and gstack's ship skill; the card says when one is missing. Needs Node.js 20.12+ and Git (full requirements).

To check what it needs, at any time:

npx @bill10/agent-007 doctor   # or agent007 doctor, or npm start -- doctor

One line per check (Node and node-pty, claude and codex installed and logged in, gh and which account reaches each repo on the board, each repo's path and remote, the port, the settings files and config.json, the version against npm, Telegram, stray local plugin registrations), ✓, ✗ or – (not needed), with a fix under each ✗. It changes nothing, and exits 1 when anything is ✗. Every start runs the quick, offline part of it and prints only what failed.

Run it as a service

In a terminal, Agent 007 and every agent it runs stop when the terminal closes. On macOS and Linux, agent007 install (npm start -- install in a clone) registers a per-user service that starts it at login and brings it back if it stops: a LaunchAgent in ~/Library/LaunchAgents on macOS, a systemd --user unit on Linux. It runs the copy you installed from, with the absolute path of your node and the PATH of your login shell captured at install time. --dry-run prints what it would write. In a terminal, install then asks whether to set up voice too, and remote access when Tailscale is installed.

agent007 install           # the service, then asks: set up voice too? remote access? [y/N] (no question without a terminal)
agent007 install --voice   # voice only: never touches the service; works on Windows too
agent007 install --remote  # remote access over Tailscale only (see docs/REMOTE.md); --dry-run prints what it would do
agent007 install --public-url https://agent.example.com  # the service behind your own reverse proxy or tunnel, no Tailscale
agent007 install --all     # the service, voice and remote access (--yes also accepts the default model's download)

Voice is whisper.cpp, ffmpeg and a speech model, so Talk to Billion and Telegram voice notes are transcribed on your machine. install --voice runs brew install whisper-cpp ffmpeg on macOS (Linux and Windows: it prints the steps), asks which model (ggml-base.en, about 150 MB, or ggml-small, about 500 MB), downloads it to ~/.agent-007/whisper/ after you confirm, sets WHISPER_MODEL in ~/.agent-007/.env and checks it by transcribing a test clip. Steps already done are skipped. From a clone, npm start -- install --voice.

agent007 status      # running or not, as a service or in a terminal, pid, version, port, uptime, workers, remote access
agent007 restart     # waits for board workers mid-step to finish it (--now: don't wait)
agent007 logs -f     # ~/.agent-007/logs/server.log, kept to 5 MB plus one older copy
agent007 update      # git pull --ff-only in a clone, npm install -g in an install; then restart
agent007 uninstall   # removes the service; ~/.agent-007 is kept

status, restart and update work on a server started in a terminal too: restart asks it to restart itself in the same terminal. Workers come back after a restart, but lose the step they were on. Windows has no service yet; run it in a terminal there.

Settings

It works with no configuration. To change something, create a settings file:

npx @bill10/agent-007 init    # writes ~/.agent-007/.env, every line commented out

Uncomment what you want, then restart. The ones people change:

Highest wins: command-line flags (--port), then environment variables, then
a .env in the directory you start it from, then ~/.agent-007/.env. The full
list is in Configuration and --help.
The service from agent007 install reads only ~/.agent-007/.env (install
copies over what the current folder's .env has and that file lacks).

The details and caveats of every feature -- phone layout, voice input, themes and more -- are in docs/FEATURES.md.

Not technical? The Solo Founder Field Guide covers what AI agents still leave to a one-person company, and just enough of the technical side to judge their work.

Keyboard Shortcuts

How It Works

Each agent runs in its own git worktree, so multiple agents can work on the same repo without stepping on each other. The server manages PTY processes via node-pty and communicates with the browser over WebSocket. The pixel office is rendered on an HTML canvas with a day/night cycle that follows your local time.

Every agent's branch starts from your repository's base branch as it exists on
the remote, fetched just before the worktree is created, so an agent never picks
up a stale local base or whatever unrelated branch you happen to have checked
out. Override it per agent with Advanced -> Start from when you want to
branch off work in progress.

The job board reuses that same machinery: a dispatched job is an ordinary agent, with a real terminal you can type into and take over at any point. Each job gets its own worktree and branch, so a job maps one-to-one onto a branch and a pull request. When the agent finishes it calls the board's finish_job tool (a card that requires a pull request hands over the PR it opened; one that does not hands over a summary), and the card moves to Review with the agent still running, so you can click straight into it to ask about the work. When the card reaches Done the board closes the agent and releases its worktree and local branch; the PR itself is untouched, and work that is on neither its remote branch nor the base branch is kept as an orphan rather than deleted (a squash-merged PR counts as on the base branch once every file it changed is there as the branch left it). Restart is the one way back for any agent that is not running: one whose CLI quit by itself (a crash, a stray /exit) shows it across the bottom of its terminal and on its left-panel row, and comes back in place, same tab, same card, resuming its own conversation (codex resume <its session id> or claude --resume <its conversation id>, with the model and permission flags it was started with). Codex's own in-terminal update prompt, which installs and then exits, is turned off for every agent Agent 007 starts (-c check_for_update_on_startup=false, never written to your ~/.codex/config.toml); Settings shows the installed and latest Claude Code and Codex instead, with an Update that runs the CLI's own update, which running agents pick up on their next Restart. Restart on an orphan picks that conversation back up with the CLI it ran, codex resume <session-id> (the newest Codex session recorded in that exact worktree) or claude --continue, under the permission mode its job card was dispatched with (a board agent whose card is already finished or deleted follows the board's current setting), or, for an agent you spawned by hand, under the permission flags you started it with. A board worker re-spawned after a restart is its card's worker again: it counts toward the cap, sends its approvals where the card says, is told once to carry on if its card is still In progress, and leaves like any other board worker when the card is filed. Workers on Billion's own cards still In progress come back by themselves after a restart, one every couple of seconds within the per-repo cap (RESPAWN_BOARD_WORKERS=0 turns that off), and Billion can bring back an orphan on one of its cards with its respawn_agent tool. A card sent back to To do (from the board or by Billion) waits a minute before it is dispatched again, so its text can be edited first; Dispatch now on the card skips the wait. A Scheduled card is the same kind of card with a start time: it waits in To do showing its date and is dispatched when that time comes (Run now starts it early), one card from start to finish. When the PR merges the job is filed away as finished -- the record is kept, the card is not.

Skill families: every agent sees a short index, and a card picks what it needs

Every Claude Code session lists every installed skill with its description, and Claude Code caps that listing at about 1% of the context window (skillListingBudgetFraction). With a hundred or more skills (gstack, a marketing pack, a video pack, your own) it goes over: most descriptions are cut, the agent sees bare names, and the skill that fits the job goes unused.

For the Claude Code agents it starts, Agent 007 groups the installed skills into families and lists one line per family instead:

• Families are built for you. At every spawn it reads ~/.claude/skills: a skill installed with npx skills is grouped by the source recorded in ~/.agents/.skill-lock.json (marketingskills is marketing, hyperframes is hyperframes), a gstack skill by gstack's folder, and the engineering ones (ship, review, investigate, qa, code-review, land-and-deploy, careful, guard, ...) are carved out into engineering. A skill that fits no family stays fully listed, and Billion gets a board notice so it can file it.
• Built-in skills are a family too. Claude Code's own skills (dataviz, claude-api, loop, schedule, update-config, the artifact ones, ...) and the ones synced from your claude.ai account (anthropic-skills:pdf, docx, deep-research, ...) form built-in, name-only unless a card asks for ["built-in"]. There is no fixed list: at server start, and whenever claude --version changes, Agent 007 runs claude -p once against a stand-in API on 127.0.0.1 (a dummy key, request headers dropped, nothing reaches Anthropic and no usage is spent) and reads the skill listing out of the request, cached in ~/.agent-007/skill-listing.json. Built-in is what that listing has minus your installed skills, plugin skills and the engineering ones. Skills Claude Code lists only in an interactive session (the artifact ones, claude-in-chrome) are taken from the newest session transcript of the same version. If the probe fails, there's no built-in family on that machine (those skills stay fully listed) and Billion is told why. {"sources": {"anthropic-skills": null}} or {"sources": {"claude-code": null}} keeps either kind fully listed.
• One index skill per family. families:marketing and the rest have a one-line description and a body that catalogs every member with a line on when to use it. Members are set to name-only: still invocable by name, full instructions loaded on use, just without their description in the listing.
• Cards name the families they need. The card form's Skills field, post_job's and edit_job's skills and POST /api/jobs' skills take family names (["hyperframes"]); those stay fully listed for that card's worker. A card that ends in a pull request always gets engineering; an agent you start in a repo does too. Billion gets marketing plus the review skills.
• Marketplace plugins are switched per card. A plugin named under "plugins" in the map (Vanta by default: {"plugins": {"vanta": "vanta-mcp-plugin@claude-plugins-official"}}) is off for every agent Agent 007 starts, and on only for a card whose skills names it (["vanta"]), through enabledPlugins in the spawn's --settings. Plugins not in the map stay as you set them. If the plugin isn't installed, the worker starts anyway and the card says so.
• Nothing is locked. Any agent can still run any skill by name.
• Your own sessions are untouched. It all goes in per spawn (--settings with skillOverrides, and the family skills as a session-only --plugin-dir), never in ~/.claude/settings.json, and no skill file is moved. A skill you set in your own skillOverrides keeps your setting.

To change the grouping, write ~/.agent-007/skill-families.json (Billion may edit it): {"skills": {"my-skill": "data"}, "sources": {"owner/repo": "family"}, "summaries": {"data": "one line"}, "billion": ["marketing", "review"]}. A skill or source mapped to null stays fully listed. Plugin skills from a marketplace are always listed in full: Claude Code applies no skillOverrides to them. Codex workers keep today's listing. SKILL_FAMILIES=0 turns it all off.

Billion also gets one board notice per finding, per server run, for duplicate or superseded skills: the same name in ~/.claude/skills, ~/.agents/skills, a board repo's .claude/skills or a plugin; byte-identical folders under different names; or a skill whose description says it replaces, supersedes or deprecates another installed one. It names both paths and suggests the removal (a PR for a repo copy, the skills installer for a global one) but deletes nothing. gstack's _gstack-command and connect-chrome / gstack-connect-chrome aliases are left out.

On the machine this was built on (189 skills, a 30,000-character budget), a no-PR worker's listing went from over budget (75,831 characters wanted, 99 descriptions shown) to 22,977 characters with nothing cut; a pull-request worker fits too.

Families read ~/.claude/skills and follow links, so a skill linked in from the one skill store is grouped exactly like a real folder.

One skill store: every skill installed once, for both CLIs

Claude Code reads ~/.claude/skills; Codex reads ~/.codex/skills and ~/.agents/skills. A skill installed for one is invisible to the other, and installing it for both leaves two copies to drift apart. Turn on Settings → One skill store and every skill lives once, in ~/.agents/skills/<name>: Codex reads it there, and Claude Code gets a link ~/.claude/skills/<name> → ~/.agents/skills/<name>.

• Off until you turn it on. Only the owner sees the switch (it is hidden, and its routes refused, with user accounts on). Ticking Keep every skill in one store first shows a dry run of what it would do; Turn on runs it. agent007 skills sync --dry-run prints the same from a terminal, and agent007 skills sync runs it once whether the switch is on or not.
• It keeps itself up to date. While on, it runs at server start and before every agent starts, so a skill installed later, for either CLI, reaches both before the next agent. Settings shows the last sync that changed something.
• What it does. A real skill folder in ~/.claude/skills or ~/.codex/skills is moved into the store; in ~/.claude/skills a link takes its place. ~/.codex/skills gets no link back, because Codex already reads the store and would list the skill twice. A skill already in the store that Claude Code can't see gets its link.
• Never deletes. The first copy is renamed into the store and copied to ~/.agent-007/skill-backup/<time>/<claude|codex>/<name>; every other folder it replaces is moved there. A step that fails puts everything back. Identical copies in two or three places keep one. Left alone, with a board notice to Billion naming the paths: one name with different contents in two places, folder names that differ only in case, a name the store already holds as a link or a file, and a skill whose SKILL.md gives it the name of another installed skill (both CLIs would list that name twice). One sync runs at a time, the server's or the command's.
• Left alone: anything already a link (gstack's skills, npx skills installs), a folder whose SKILL.md is a link (gstack's per-skill folders), gstack itself, its aliases (_gstack-command, connect-chrome, gstack-connect-chrome), any folder with a .git or a .gstack-owned marker (gstack's copies on Windows), a folder holding a relative link that points outside it (it would point elsewhere from the store), a skills folder that is already a link to ~/.agents/skills, ~/.claude/skills/synced (claude.ai's skills), Codex's .system, plugin skills and every repo's own .claude/skills. ~/.claude/settings.json is never written.
• Running Codex sessions keep their skills. A Codex session reads each skill from the path it started with, so nothing in ~/.codex/skills moves while Codex is running: an agent the app started, and, for Settings and agent007 skills sync, any codex process on the machine (its background server aside). It moves at the next sync with none running.
• npx skills keeps working. ~/.agents/.skill-lock.json is never written. npx skills update rewrites the store folder and finds the Claude link already pointing at it; a copy-mode install that puts a real folder back in ~/.claude/skills is identical, so the next sync folds it in again.
• Claude only or Codex only. In ~/.agent-007/skill-families.json, "claudeOnly": ["name"] leaves that skill where it is, and "codexOnly": ["name"] moves it into the store without a Claude link (a link that already exists is yours to remove).
• CLAUDE_CONFIG_DIR and CODEX_HOME are followed. On Windows the link is a junction, which needs no admin rights.

Repo skills stay in their repo, versioned with it; Agent 007 never moves or edits anything in a checkout. Where each CLI looks inside a repo:

• Claude Code reads <repo>/.claude/skills.
• Codex (0.162) reads .agents/skills and .codex/skills in every folder from its working directory up to the repository root, not above it, and never .claude/skills. It follows a linked skill folder, and the project need not be trusted. Source: its app-server's skills/list (codex app-server generate-ts has the protocol), run on a stub repo with an empty CODEX_HOME, no login. OpenAI's skills docs say the same for .agents/skills and do not mention .codex/skills, which works but is undocumented, so new skills go in .agents/skills.

So a repo skill both CLIs can use is a real folder in .agents/skills with a committed relative link in .claude/skills:

<repo>/.agents/skills/qa-browser/SKILL.md                    the skill, edited here
<repo>/.claude/skills/qa-browser -> ../../.agents/skills/qa-browser

To convert one, from the repo root: git mv .claude/skills/qa-browser .agents/skills/qa-browser && ln -s ../../.agents/skills/qa-browser .claude/skills/qa-browser, then commit both. On Windows, git checks a link out as a link only with core.symlinks on (Developer Mode, or an admin shell, lets it make one). Otherwise it writes a small text file holding the path, so Claude Code on that checkout finds no folder and loses the skill, while Codex still reads .agents/skills. Turn it on and re-check out the link: git config core.symlinks true && git checkout -- .claude/skills.

Agent 007 tells Billion, once per skill per server run, about a skill on the board's repos that only one CLI can see (a folder in .claude/skills with no .agents/skills or .codex/skills counterpart, or the reverse), naming the repo, the skill and the commands above (or, for a link checked out as a file, the core.symlinks fix). It changes nothing; a claudeOnly or codexOnly entry in skill-families.json silences it. This runs whether or not the store is on.

┌─────────────┬──────────────┬────────────────────┐
│  Explorer   │  Pixel       │  Jobs + Terminals   │
│  (repos,    │  Office      │  (job board and     │
│   files,    │  (canvas,    │   Billion chat      │
│   diffs)    │   agents)    │   tabs, xterm.js,   │
│             │              │   one tab per agent)│
└─────────────┴──────────────┴────────────────────┘

FAQ

Can't Claude Code (or Codex) do this on its own?

Much of it, with enough setup: Claude Code can loop, run subagents in their own worktrees, resume a session and even call Codex. Agent 007 is that setup already built and running: a board of workers you can watch and type into, a manager that reviews and merges their pull requests, and one place where their questions reach you. Use as much of it as you need.

How is this different from Munder Difflin?

Munder Difflin is a great, much bigger desktop app that builds many abilities in: memory, dictation, meetings, Slack, an editor. Agent 007 stays thin. It is a web app you start with one command and can open from any browser, even your phone, and it does only the operations: terminals, a job board, a manager, reviews, and a line to you. What your company can do comes from the agents themselves (Claude Code, Codex, and whatever tools, APIs and MCP servers they can reach), so it gets better every time they do. Free, with no paid tier.

Is it safe to let agents merge on their own?

Workers never merge their own work. Billion reads each diff, waits for CI and then merges or sends the card back. Anything that spends money, needs your credentials, can't be undone, or touches payments, security or secrets comes to you first, in the Billion tab (your chat with Billion) or on your phone. Before each merge Billion checks whether it would set off a deploy (a GitHub Actions workflow on the base branch that deploys or publishes) and asks you first when it would; tell Billion in its first-run chat (or any time) if you'd rather it never ask, or ask only for production. Paste a screenshot or drop a file into the Billion tab and Billion gets its path to read. Open questions group by project in a panel you work through from the tab's strip. Workers on Billion's cards, Claude Code and Codex alike, ask Billion for permissions before they ask you.

Does it cost anything?

No. It is free and open source, and it runs the CLIs you already have, on your existing subscriptions. Board workers use your subscription's usage like any session you start yourself.

Where does it run?

On your machine. Agents work while it is on and awake; a sleeping laptop pauses them. You can reach it from your phone (see remote access).

Which agents does it support?

Any terminal agent runs in its web terminals. The job board and Billion work with Claude Code and Codex, and each card can pick its model from the ones the board finds installed.

Do I have to use Billion?

No. Each step of the list above works on its own: stop at web terminals, or at the job board, and post the cards yourself.

What happens when I hit a usage limit?

Cards on that model wait for the reset unless you enable account rotation for that CLI. Billion itself warns as it nears its limit and can hand over between Claude Code and Codex, or rotate through selected Claude or Codex accounts first (see Rotating accounts).

Configuration

Settings are environment variables. Set them inline, in ~/.agent-007/.env
(npx @bill10/agent-007 init creates it from .env.example,
every setting explained and commented out), or in a .env in the directory you
start from. npx @bill10/agent-007, a global agent-007 and npm start in a
clone all read both files, and the startup log names the ones it loaded. Highest
wins: flags (--port 8080 overrides PORT), then the environment, then
./.env, then ~/.agent-007/.env. --help lists them all. Everything the app
saves lives in ~/.agent-007 (AGENT007_CONFIG_DIR moves it, and the settings
file with it). These settings are the server's own: the agents it starts do not
inherit them, so a worker cannot read your Telegram bot token.

PORT=8080 npm start                       # Custom port (default: 7007)
HOST=0.0.0.0 npm start                    # Bind all interfaces (default: 127.0.0.1)
ALLOWED_ORIGINS=mac-mini.tailXXXX.ts.net npm start   # Allow a remote browser origin

Running remotely? The server spawns real shells, so never expose it to the
open internet. See docs/REMOTE.md for Tailscale, Cloudflare
Tunnel + Access, and WireGuard.

Rotating accounts

Settings → Accounts is one list of every login on this machine, each row tagged with its CLI.
Every logged-in Claude Code and Codex login the scan finds joins the switch list (at start, and on Refresh).
Each Claude account must have its own Claude Code login folder (for example,
sign in with CLAUDE_CONFIG_DIR=~/.claude-work claude, then /login); each
Codex account its own Codex home with an auth.json (for example
CODEX_HOME=~/.codex-work codex login). You can also add a
folder under Add an account folder manually, picking Claude or Codex next to it. Automatic rotation turns on by default once two accounts
are added. Arrange their order and click Save settings to apply changes. An explicitly saved off
setting stays off, including after a restart or another account discovery. Switch now selects an account manually.

At a hard usage limit on Billion or a Claude worker, the app selects the next
eligible account. It saves refreshed credentials, switches only authentication
and account metadata, and restarts its Claude sessions on their exact
conversations. The same Claude config directory keeps settings, skills,
plugins, MCP configuration, trusted folders, and history. This affects all
Claude sessions managed by the app because they share the default login.
If any session's exact conversation ID is unknown or its startup flags cannot
be preserved, the switch stops before any session is interrupted. Stop that
session before trying again.

Limited accounts become eligible after an explicit reset time or a 30-minute
retry delay when the notice's reset time is ambiguous. If all accounts are
unavailable, workers wait; Billion can hand over to Codex when the list has a
selected Codex account and BILLION_AUTO_SWITCH is not 0. CLI changes use
HANDOVER.md for recent conversation and tool activity; Billion's existing
Git folder already holds its state and pending work. Returning from Codex
also selects an eligible Claude account and writes a handover.

Credentials are saved locally under ~/.agent-007/account-logins/ with
owner-only file permissions on macOS/Linux. Stop Claude processes outside
this app before rotating; the app refuses to switch while it detects one.
Avoid using a source login folder concurrently: its copied refresh token can
become stale. Discovery does not overwrite a maintained login with that stale
copy. An interrupted switch offers Restore previous login, which leaves
automatic rotation off until you enable it again. If a conversation fails to
restart, fix the reported startup problem, then choose Settings → Accounts →
Retry paused Claude conversations. Queued messages are retained
for that retry; it restarts the app's Claude sessions without changing the login.
Nothing is retired or deleted. Rotation controls require Billion enabled and app user
accounts disabled. Details in FEATURES.md.

Codex works the same way, in the same list: Claude and Codex accounts share
one Settings list, tagged by CLI, whose order is the switch order. A saved Codex login is a copy of that folder's
auth.json, keyed by the ChatGPT account and user in its token. Switching
writes the saved auth.json over the one in your default Codex home (~/.codex,
or CODEX_HOME), atomically and 0600; config.toml, sessions, skills and
history stay put. Before every switch the outgoing account's refreshed
auth.json is saved back, so its refresh token stays current. At a hard limit
on Billion or a Codex worker the app stops its Codex sessions, stops Codex's
shared background server (codex app-server daemon stop, then checks it is
gone, so it reloads the new login when the next codex starts it), activates
the next login and resumes each session with codex resume <id>. It refuses
before interrupting anything if a session's conversation id is unknown, two app Codex sessions share a
folder, or a codex process outside the app is running. Limited accounts
become eligible again at the time the notice gives ("try again at Oct 25th,
3:15 PM", read in this machine's time zone), otherwise after 30 minutes. Only
when every selected Codex account is unavailable does Billion hand over to Claude Code
(when the list has a selected Claude account, with BILLION_AUTO_SWITCH on). Anything else
that reads ~/.codex/auth.json follows the switch (a tool that symlinks its
Codex login to that file, the Codex IDE extension), just as if you had switched
accounts yourself.

Multiplayer & login

By default there are no user accounts and no login — the app runs open on
localhost, exactly as before. To turn on per-user login (for shared/remote use),
create a user:

npm run adduser -- "Alice"     # prints a one-time login token
npx @bill10/agent-007 adduser "Alice"  # the same, without a clone

The moment the first user exists, the server requires a token for every
/api call and WebSocket connection. Log in by opening the app and pasting the
token, or visit http://<host>:7007/?token=<token> once (the token is stored in
your browser and stripped from the URL). Add a user per person; each gets a
distinct color and shows up in the presence indicator.

Login establishes identity, not isolation — every logged-in user can still
spawn their own shells on the host. Only issue tokens to people you'd give an
SSH login, and keep the server behind Tailscale, an authenticating proxy or a
trusted network.

Each agent is owned by the user who spawned it. You have full control of your
own agents and are read-only on everyone else's — you see their live
terminal but can't type into, resize, kill, rename, or upload to it (enforced
server-side). The dimmed-tile / read-only-terminal UI polish is still to come
(see docs/designs/multiplayer.md).

Caveat: agents you spawned before creating the first user are unowned, so
once auth is on anyone can still control them. Spawn agents after enabling auth
(or restart them) if you want them owned.

Job board HTTP API

A script that cannot run an MCP client (a poller, a cron job) posts and follows
cards over plain HTTP. Send a user token as Authorization: Bearer <token>, or
nothing on a board with no users. Every route but the first answers only the
caller that posted the card (403 for anyone else, 404 for an unknown id). With
no users, every tokenless caller counts as the same poster.

The poster is recorded with the card, so it survives a restart for a user token
or a tokenless caller. An agent session's token dies with its terminal, and so
does its hold on the cards it posted.

Requirements

• Node.js 20.12+
• Git
• A modern browser (three panels at 900px+, explorer hidden below that, one panel at a time on a phone)
• A CLI to run as the agent (defaults to claude, but works with any command)
• For Billion: Claude Code, logged in (or Codex, with BILLION_AGENT=codex)
• For cards that open a pull request: a GitHub remote on the repo, gh signed in, and gstack's ship skill for the card's CLI

Agent 007 runs on macOS, Linux, and Windows -- spawning agents, adding repos, and browsing paths all handle Windows natively, and CI runs the test suite on both Ubuntu and Windows. One Windows caveat: the per-agent MCP config file protects its token with POSIX file permissions, which Windows doesn't have, so on a shared Windows machine other local users can read it.

Troubleshooting

Start with agent007 doctor (npx @bill10/agent-007 doctor, or npm start -- doctor in a clone): it checks everything below and prints the fix for each problem it finds.

doctor says no working ship skill, or N skills in ~/.codex/skills are broken links. Required: gstack, whose ship skill is how a card that needs a pull request finishes. Install it, or re-run its setup after moving or deleting its folder: ~/.claude/skills/gstack/setup --host claude (or --host codex). doctor only reports; it never deletes a link. Recommended: agent-browser (cards use it for screenshots of UI changes); impeccable UI design skill, for claude and codex; whisper.cpp (transcribes your Telegram voice notes on this machine). doctor lists them but never fails on them.

npm install fails building node-pty. node-pty ships prebuilt binaries for macOS, Linux and Windows on x64 and arm64, so normally nothing compiles. Only if the install tries to build it from source and fails, install a C++ toolchain and run npm install again:

• macOS: Xcode Command Line Tools (xcode-select --install)
• Linux: build-essential and python3 (sudo apt install build-essential python3)
• Windows: Visual Studio Build Tools with the C++ workload

An agent will not start: "claude" is not installed, or not on the PATH Agent 007 was started with. The CLI the agent runs (claude, codex or gemini) was not found, and the message says how to install it. If it is installed, Agent 007 was started from somewhere with a shorter PATH than your shell (a launcher or a service manager, say); start it from a terminal where which claude finds it. Billion runs on Claude Code too, so without it the Billion chat says what to do instead: install Claude Code and press Start Billion, or restart with BILLION=0 to turn Billion off. Installed but not logged in, Claude Code opens on its sign-in in Billion's terminal, and the chat says so with a button that opens it; your messages reach Billion once you have signed in there.

Running as a service, an agent cannot find claude, codex, gh or node. A service does not start from your shell, so it gets none of what .zshrc or .bashrc adds to PATH (nvm, ~/.local/bin, Homebrew). agent007 install captures your login shell's PATH into the service when it runs, so a CLI installed or moved since, or a new nvm node, is not on it. agent007 doctor says so (✗ the service cannot find ...); run agent007 install again to capture it anew.

Where are the logs? As a service: ~/.agent-007/logs/server.log (agent007 logs -f); it is cut back to empty past 5 MB, with the previous 5 MB kept as server.log.1. In a terminal: that terminal. agent007 status says which.

A job card says "gh" is not installed. The board finds pull requests with the GitHub CLI: install it from https://cli.github.com and run gh auth login. A job that ends in a pull request also needs a repo with a GitHub remote to push to.

gh is signed in to several GitHub accounts. Leave the active one alone: each board worker gets the account that owns its repo in GH_TOKEN (see BILLION.md), and board workers are not allowed to run gh auth switch.

A repo's local plugin (e.g. Telegram) shows up in every board worker's worktree. If a repo's .claude/settings.local.json enables a local-scope plugin, Claude Code registers it for every git worktree or subfolder a session starts in, including board workers' worktrees. Board workers themselves run with channel plugins disabled, so they don't act on it, but the registrations pile up in ~/.claude/plugins/installed_plugins.json, and a plain claude started by hand in one of those worktrees will load the plugin (for Telegram: it steals the bot's updates from your real session). Fix: register such plugins outside any repo you run board cards in, or uninstall the local registration (claude plugin uninstall <plugin> --scope local) in the repo and in each worktree that got one.

Architecture

server.js          Entry point + orchestrators (createSession, killSession)
server/
  state.js         Shared mutable state (sessions, orphans, pools, config)
  settings.js      Config dir and the settings files (./.env, ~/.agent-007/.env)
  doctor.js        `agent007 doctor` and the start's quick check (report only, never changes anything)
  service.js       `agent007 install/uninstall/status/restart/logs/update`: the LaunchAgent / systemd unit
  control.js       server.json and the token-checked /control routes status and restart call
  config.js        Config persistence (load, save, crash recovery)
  direct-run.js    Entry-point detection (symlink/space-safe `npm start` guard)
  git.js           Git operations (worktree, file tree, diff)
  jobs.js          Job board dispatcher (scan, spawn, PR watch, schedule firing, attachment files)
  command-path.js  Checks a CLI is installed before a spawn; resolves commands to spawnable files on Windows (PATHEXT)
  pty.js           PTY lifecycle (spawn, handlers, state detection; closing a session kills every process group under it, detached background jobs included)
  ws.js            WebSocket (message routing, broadcast, origin check, shared terminal sizing)
  http.js          HTTP routes (/api/browse, /api/jobs, /api/agent-accounts, job attachment and Billion chat file downloads, /mcp, origin + auth gates)
  proxy.js         What a reverse proxy sends (X-Forwarded-Proto/For, the Cloudflare Access email), for status, doctor and Settings
  agent-accounts.js  Installed agent CLIs and the accounts each is logged in with (Settings panel; read-only)
  cli-update.js    Settings' Claude Code and Codex versions against npm's latest, and Update (runs the CLI's own `update`)
  mcp.js           The board's MCP server (post_job, list_jobs, read_job, edit_job, finish_job, list_agents, send_message, withdraw_message; Billion also gets billion_ready, add_repo, close_job, answer_permission, read_approval, notify_owner, read_agent_screen)
  messages.js      Agent-to-agent messages and board notices (who can reach whom, rate limit, queued until the recipient rests at its prompt)
  billion.js       Billion's folder (git repo, templates, charter refresh) and whether it runs
  account-rotation.js   Persistent account pool, cooldowns, refreshed logins and recovery
  account-migration.js  Platform credential stores, selective account writes and legacy rollback
  codex-login.js   The Codex side of rotation: capture and activate auth.json, stop Codex's background server
  claude-rotation-sessions.js  Resume exact Claude or Codex conversations after a shared login switch
  claude-processes.js  Detect Claude or Codex processes outside the app before a login switch
  talk.js          Talk to Billion: an utterance's audio transcribed (whisper.cpp) and sent once, a voice reply spoken (say), /api/talk routes
  approvals.js     Hands a worker's permission request to Billion and waits for its answer
  permission-hook.js  PermissionRequest hook (Claude Code and Codex) a worker on Billion's cards runs
  agent-mcp.js     Per-session MCP config + the flags that connect Claude Code and Codex to it
  agent-mcp-bridge.js  Codex stdio bridge to the board's HTTP endpoint
  agent-transcripts.js  Which CLI last ran in a worktree, read off its transcripts (re-spawn fallback)
  auth.js          Login tokens, user accounts, agent session tokens
bin/
  agent-007.js     The `agent-007` command (`npx @bill10/agent-007`): flags, .env, start
  adduser.js       Create a login user (`npm run adduser`)
public/
  index.html       Three-panel layout, plus the phone's bottom nav
  style.css        Dark/light themes via CSS custom properties
  app.js           Main entry point
  assets/          Pixel art sprites (characters/ MIT with vendored LICENSE; furniture/ mixes Antea CC-BY 4.0 and pixel-agents MIT, see Acknowledgements)
  modules/
    office.js      Canvas pixel art (workstations, characters, job boards, day/night)
    terminal.js    xterm.js terminals, clipboard paste, tab management
    explorer.js    File tree, diff viewer, repo management
    jobs.js        Job board UI (columns, cards, the job form)
    waiting.js     The Billion tab: your chat with Billion (its replies and questions, your messages, a text box, its mic, pasted/dropped files)
    readaloud.js   Read aloud in the Billion tab (speechSynthesis: a speaker button per message, read new messages aloud)
    talk.js        Talk to Billion: hands-free voice turns in the Billion tab (VAD, utterance upload, spoken replies)
    ws.js          WebSocket client: reconnects in place, reloads on a server restart
    state.js       Shared client state (agents, repos, viewer identity, server platform, the panel a phone shows)
    shortcuts.js   Keyboard shortcuts
    voice.js       Voice input (Web Speech API dictation into the terminal or the Billion tab's text box)
    auth.js        Login tokens, presence, HTML escaping
    settings.js    The Settings panel behind the terminal header's gear (Accounts: every login with its CLI, account switching, one line per agent CLI)
    account.js     Claude and Codex account rotation settings (one list: discovery, inclusion, order, recovery)
lib/
  helpers.js       State detection (dialog patterns per CLI, the synchronized-output frames Codex paints in), git parsing, codename/cocktail pools, the file-name sanitiser
  jobs.js          Pure job-board logic (states, prompts, dispatch selection)
  cron.js          Five-field cron parser (schedules for scheduled jobs)
templates/
  billion/         Billion's starting files (charter, owner rules, STATE.md, COMPANY.md)

Acknowledgements

• Inspired by pixel-agents, the VS Code extension that put AI agents in a pixel office first.
• Character sprites and the ambient decor sprites (furniture/cactus.png, plant_2.png, sofa_side.png, sofa_front.png, coffee_table.png, coffee.png, table_front.png, chair_side.png, chair_back.png -- the two chairs recolored, and chair_front.png drawn for this project in the same style) from pixel-agents (MIT, © Pablo De Lucca — license vendored at public/assets/characters/LICENSE), character bases by JIK-A-4's "Metro City" free top-down character pack (CC0)
• Desk and bookshelf.png sprites from the Free Furniture Office Equipment Set by Antea (CC-BY 4.0)

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup instructions and guidelines.

License

MIT

If this is useful, a ⭐ helps others find it.