@planckspace/cli

PlanckSpace CLI — sync AI token usage from Claude Code, Cursor, and Windsurf to your team ledger.

Quick start — a real number in minutes

npx @planckspace/cli@latest init

init connects your workspace (paste the CLI token from the console when prompted), backfills and syncs your last 30 days, installs the background daemon, and prints what's recoverable this month — dormant seats, oversized plans and metered waste, in real (billed) dollars. With too little history it says what is missing instead of printing a $0; with part of the team not yet reporting it marks the figure incomplete — a floor, not a total.

Your prompts, responses and code never leave your machine; only usage metadata does (token counts, timings, models, tool names, repo and file names, git email). Check exactly what was sent for any session with planck inspect <id>.

Onboard a whole team — one command per developer

An admin copies the team command from Team & settings → Connect your team in the console and pastes it into the team channel:

npx @planckspace/cli@latest init --join pk_join_xxx

Each developer who runs it joins as themselves (their git config user.email, or --email [email protected]) and gets their own device token. The join code only ever grants developer access, can be rotated or revoked from the console, and respects the workspace's claimed email domain. The console's coverage meter ("18 of 22 developers reporting") shows who is still missing.

Install

curl -fsSL https://planckspace.dev/install | sh

With a join code or CLI token (skips the manual connect step):

curl -fsSL https://planckspace.dev/install | sh -s -- --join pk_join_xxx
curl -fsSL https://planckspace.dev/install | sh -s -- --token pk_live_xxx

Or install manually:

npm install -g @planckspace/cli

See docs/INSTALL.md for manual steps and troubleshooting.

VS Code extension

Install the companion extension to see spend, insights, and skill recommendations right in your editor:

• VS Code Marketplace — search "Planckspace" in the Extensions view, or run:

  code --install-extension planckspace.planckspace-extension

• Open VSX (Cursor / Windsurf / VS Codium): open-vsx.org/extension/planckspace/planckspace-extension
• Headless / CI:

  code --install-extension planckspace.planckspace-extension
  # or install from VSIX:
  code --install-extension planckspace-extension-win32-x64-0.2.0.vsix

Commands

| Command | Description | |---|---| | planck init | First run: connect, backfill + sync, daemon, recoverable $/mo | | planck init --join <code> | Join your team's workspace with the shared join code | | planck login <token> | Connect to a PlanckSpace workspace | | planck scan | Ingest local AI session history | | planck sync | Push unsynced sessions to the team dashboard | | planck sync --watch | Keep syncing on an interval (default 60 s) | | planck status | Show connection + session stats | | planck logout | Disconnect (local data retained) | | planck routing on / off / status | Model routing for Claude Code (below) |

Model routing for Claude Code

planck routing on installs the planckspace-routing plugin for Claude Code on this machine, in every repo. It adds three agents, each pinned to a model:

• explorer on Haiku, for read-only lookups
• builder on Sonnet, for routine edits
• investigator on Opus, for unknown-cause bugs, cross-repo work and releases

It also adds a session-start rule that tells the main session to route each task to one of them. A model you name ("use opus") always wins. It never changes your default model.

• Metered (API) users: the same work costs less.
• Seat users (Pro / Max / Team): the bill doesn't change, but the usage limit goes further.

planck init offers routing when Claude Code is present. Your workspace admin sets the policy in the console under Workspace → Policy:

• Ask (the default): init asks, default yes.
• On: installed without a question, including on already-connected machines at their next sync.
• Off: never offered.

planck routing off removes the plugin and keeps it off on this machine, whatever the policy. init --routing / --no-routing skip the question.

Installation uses Claude Code's own claude plugin commands. The CLI finds the claude binary on PATH, in the native installer's location, or bundled in the VS Code / Cursor / Windsurf extension. With none of those, it adds two keys to ~/.claude/settings.json after writing settings.json.planckspace-backup. Set PLANCKSPACE_CLAUDE_BIN to a path to use a specific binary, or to none to use settings only.

Non-interactive login (CI / install scripts)

planck login --token pk_live_xxx
# or
PLANCKSPACE_TOKEN=pk_live_xxx planck login

Backfill + sync in one step

planck scan --sync

What gets synced

• Session metadata: tool, model, token counts, cost, duration, repo name, outcome
• Git attribution: git config user.email from each repo (maps sessions to team members)
• Never synced: prompt text, code content, file contents, turnsJson

See docs/COVERAGE.md for per-tool capture details.

What's new in 0.2.0

• Cost insights — the CLI now detects patterns that inflate spend (large CLAUDE.md, low cache hit rates, repeated context) and writes them to ~/.planckspace/local.db. The VS Code extension surfaces these with estimated monthly savings.
• Audit scoring — planck status reports a workspace configuration score across five dimensions: CLAUDE.md token budget, prompt-cache hit rate, hooks, installed skills, and MCP servers.
• Improved Windsurf support — schema detection updated for recent Windsurf session log changes.
• Anomaly detection — the CLI flags sessions with unusually high token counts or cost spikes.

Supported editors

| Editor | Sessions | Tokens / cost | Notes | |---|---|---|---| | Claude Code | Yes | Yes | Full | | Cursor | Yes | No | Cursor meters server-side; token fields are 0 | | Windsurf | Yes (beta) | Provisional | Unverified schema — may vary by version |

Requirements

• Node.js 20+
• macOS or Linux (Windows: use WSL)

Publishing

Build and publish to npm:

npm run release
# equivalent to: npm run build && npm publish

prepublishOnly runs tsc automatically before every npm publish.

To log in to npm first:

npm login
npm run release

The package publishes as @planckspace/cli (public scoped package).

Development

npm install
npm run dev -- scan       # run any command via tsx (no build needed)
npm test                  # vitest
npm run build             # compile TypeScript → dist/

Override the API endpoint during development:

PLANCKSPACE_API_URL=http://localhost:4000 npm run dev -- sync

Running a local daemon alongside the production one

PLANCKSPACE_API_URL alone is not enough to work locally: the token, the selected workspace and the synced-session cache all live in ~/.planckspace, so pointing the URL at localhost and running login would overwrite the production profile — and the shared local.db would mark sessions as synced that the local backend never received.

PLANCKSPACE_HOME relocates that whole directory, giving you a second, fully isolated profile:

export PLANCKSPACE_HOME=~/.planckspace-local
export PLANCKSPACE_API_URL=http://localhost:4000

planck login <token>       # writes ~/.planckspace-local/config.json
planck scan --sync         # one-shot backfill
planck daemon run          # foreground watcher

~/.planckspace — and the daemon registered against it — are untouched. Both variables must be explicitly exported; the CLI never loads a .env, so a stray file in the working directory can't redirect where a bearer token is written.

Use planck daemon run (foreground) for local work. planck daemon install registers an OS-level autostart service that does not inherit these variables, so it would still run against production.

Daemon not syncing?

planck daemon fix                       # or: npx -y @planckspace/cli@latest daemon fix

One idempotent pass: checks the CLI version and the connection, re-registers auto-start (with its crash supervisor), restarts the daemon and waits for the backend to accept its heartbeat. Anything it cannot fix is marked ✗ with the remedy underneath. The dashboard's "Fix daemon" button hands out the same command with --workspace <id>, which also flags a machine that is healthy but reporting to a different workspace — and --code <code>, a one-time code (single use, 10 minutes) that reconnects such a machine without a token paste.

Connecting a new machine from the console works the same way: Connect this machine shows npx -y @planckspace/cli@latest init --code 7KQ4-M2XD, which connects, backfills, syncs and starts the daemon in one go.

License

MIT