Installation

Requirements

Node.js ≥ 20 (or Bun)
Claude Code installed and signed in on each machine

Install

npm install -g ccpool

Or run it once without installing:

npx ccpool@latest

First run

ccpool

The first run walks you through onboarding, then opens the live view. From then on, ccpool opens straight to the live view.

Onboarding asks for three things:

a name — your identity in the group. Usage on this machine is credited to this name.
a group password — shared by everyone in the group. It’s what lets a machine join at all.
a member password — yours alone. It stops anyone else from reporting usage under your name.

ccpool detects which Claude account you’re on and starts the background daemon for you.

Creating vs joining a group

The first person to run ccpool creates the group. Everyone after that joins it with the same group password. The group is tied to a single Claude account — every machine must be signed into the same account.

Scripted setup

Every prompt has a flag, so onboarding works in CI too:

ccpool init --name sam --yes
# with CCPOOL_GROUP_PASSWORD and CCPOOL_MEMBER_PASSWORD set in the environment

Reading the usage

# the live shared view (opens onboarding if not set up yet)
ccpool

# print a one-shot snapshot and exit
ccpool status

# compact one-liner for Claude Code's status bar
ccpool statusline

# list everyone in the group
ccpool users

# hand this machine off to another person
ccpool config set name alex

ccpool and ccpool status show the same thing — the overall account tank on top and each person’s slice below it:

 ▐▛███▜▌   ccpool · status  ·  you are sam
▝▜█████▛▘  account sam@example.com  ·  3 members (2 active)
  ▘▘ ▝▝    shared db · synced 12s ago · daemon running

overall
  5h      ██████████████████░░░░░░░░░░░░   60%  · resets 4h 02m
  weekly  █████████░░░░░░░░░░░░░░░░░░░░░   30%  · resets 6d 4h

members
   # member    usage                          5h   wk  state
   1 sam ◂     ███████████████░░░░░░░░░░░░░  45%  23%  active
   2 alex      █████░░░░░░░░░░░░░░░░░░░░░░░  15%   8%  active
   3 unknown   ░░░░░░░░░░░░░░░░░░░░░░░░░░░░   0%   0%  idle

Usage is credited to whatever name the machine is set to, so switching the name switches who gets credited. The switch asks for that person’s member password.

Self-hosting the server

By default ccpool uses the hosted server, so there’s nothing to deploy. If your group would rather run its own, the server ships as its own package, ccpool-server — open source, multi-tenant, and running on libSQL. One DATABASE_URL covers both a local SQLite file and a remote libsql:// (Turso):

# local file
DATABASE_URL=file:/var/lib/ccpool/server.db PORT=8787 npx ccpool-server

# remote libSQL / Turso
DATABASE_URL=libsql://your-db.turso.io CCPOOL_DB_AUTH_TOKEN=… PORT=8787 npx ccpool-server

Point CLIs at your server with CCPOOL_SERVER_URL=https://your-host when running ccpool init. Run it behind TLS: the bearer token rides on every request, so the CLI refuses plain http:// for anything but localhost. Passwords are stored as salted scrypt hashes and tokens as sha256 hashes; the server never keeps a usable credential.

See Storage & server for how tenancy and the two-password model work.