@planckspace/cli

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

Install

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

With an invite token (skips the manual login step):

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 | Initialize ~/.planckspace/ (local DB + config) | | 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) |

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

License

MIT