Docs

How to set up Kibble

Kibble is a Claude Code and Codex usage dashboard for software teams. Its open-source collector sends counts from the logs the agents already write, GitHub Copilot's included. Content never leaves the machine. Every command on this page is complete: copy it, paste it into a terminal, press Enter.

Which agents does Kibble collect?

Claude Code, Codex and GitHub Copilot are collected as soon as the collector is installed. Cursor is experimental and needs one extra command.

Install the collector on every machine where one of these agents runs: a laptop, a desktop, a build server. A machine with no agent on it has nothing to report, which is fine. Logs written before the install are imported too, back to 30 days, except for Cursor, whose hooks only see turns after they are installed.

How do I install the collector?

Two commands in a terminal on each machine: one installs the CLI, one links it to your account. Node.js 20 or newer must be there first; most developer machines already have it.

1. Open a terminal. macOS: Terminal (press Command-Space, type Terminal). Windows: PowerShell (press the Windows key, type PowerShell). Linux: any terminal. The commands are the same on all three.
2. Check Node.js.

   node --version

   v22.14.0

   A v20 or higher is fine. command not found, not recognized, or a lower number: install the LTS build from nodejs.org, then close the terminal and open a new one.

3. Install the collector. It takes under a minute and is open source, MIT.

   npm install -g @usekibble/cli

   Check it is there:

   kibble --version

   0.9.0

4. Link the machine.

   kibble login

   A browser tab opens at app.usekibble.com. Sign in with Google if it asks. Check that the code on the page matches the one in the terminal, then click Approve. Back in the terminal, the collector uploads the last 30 days and schedules the hourly push. The last line is a question: press Enter to let the CLI update itself, or type n to keep the version you installed.

Example: what the terminal shows (your numbers will differ)

$ kibble login

  Open   https://app.usekibble.com/device
  Code   KXQ4-9TRM

  Approve the request there, then come back. Ctrl-C to cancel.

Linked you@company.com to Acme (no team yet) as "Mac · linked 2026-09-16".
This device can read personal usage only. For role-based reporting, run kibble login --reporting.
Collecting available usage from the last 30 UTC days now...
2026-08-18..2026-09-16  38 rows across 21 day(s)  [tokscale-core+codex+cursor+cli]
  claude-code       $312.40      480,112,331 tokens
  codex              $18.02       61,004,510 tokens
  TOTAL             $330.42

    64 sessions   p50 $2.10  p90 $14.80  max $41.20   top 10% = 47% of spend

  repos: 3 (names only, never paths)
  activity: 64 sessions, 212 human turns, 4,318 tool calls (37 errored), 291 edits +6,204/-1,987 lines, 0 hook errors, 9 compactions

  billing:
  claude-code    max 5x subscription
  codex          plus subscription

  capabilities: 6 with recorded use, 41 with no recorded use (names only; Codex coverage: explicit skill selections and recorded slash commands)

Pushed 38 rows, 64 session ids, 47 capability rows, 12 repo rows to https://app.usekibble.com.
Your organization requires automatic collection: scheduled `kibble push` hourly and at startup.
Run `kibble schedule status` to check the background job. After a successful push, refresh My usage in the dashboard.
Kibble will download and run new CLI versions approved by Kibble on this machine. It checks daily. Turn off anytime: kibble update disable
Enable automatic CLI updates? [Y/n]

That is the whole setup. The terminal can be closed. Repeated pushes replace the same daily counts instead of adding them twice, so running kibble login or kibble push again never doubles anything.

No browser on this machine? A server, or a machine you reach over SSH

kibble login --no-browser

The terminal prints the link and the code and waits. Open the link on any device, your phone included, sign in, type the code, click Approve. The terminal finishes on its own. Over SSH and in CI the CLI already skips the browser without the flag.

Give the machine a name

kibble login --device "work laptop"

The name shows on My usage beside the last push time. Without it the machine is called Mac, Linux or Windows, with the date it was linked. Nothing about the machine itself is sent: not the hostname, not the user name, not a hardware id.

If your organization switched automatic collection off

An owner can turn it off under Settings. Then kibble login links the machine but sends nothing and schedules nothing, and these two commands are how counts move:

kibble push              # import the last 30 days now
kibble schedule install  # optional: push every hour anyway

What should I see after login?

Three places confirm the link: the last lines in the terminal, kibble whoami, and My usage in the dashboard.

kibble whoami

Example output

config   /Users/you/.config/kibble/config.json
server   https://app.usekibble.com
email    you@company.com
org      Acme
team     (unassigned)
device   Mac · linked 2026-09-16  (install id in /Users/you/.config/kibble/device.json)
linked   yes
collect  automatic, required by the organization
skills   skill, command and MCP names reported (organization policy)

On Windows the config line reads C:\Users\you\.config\kibble\config.json. team stays unassigned until an owner puts you in one; it changes nothing about collection.

Then open My usage in the dashboard. It lists this machine with its last push time and the billing mode it reported. Overview shows spend by agent, model and repository for the selected range; if today is quiet, pick a wider range at the top of the page.

How do I check it is working?

kibble schedule status

Example output on macOS

scheduled yes
where     /Users/you/Library/LaunchAgents/com.usekibble.push.plist
policy    required by your organization
log       /Users/you/.config/kibble/push.log
last      2026-09-16T09:00:04.118Z  Pushed 3 rows, 2 session ids, 12 repo rows to https://app.usekibble.com.

On Linux the where line reads crontab (hourly and @reboot), on Windows Task Scheduler (com.usekibble.push, com.usekibble.push.boot). The last line is the newest entry of the push log; a timestamp from the last hour or two means the job is alive.

kibble doctor

Example output

parser   tokscale-core+codex+cursor+cli
version  @tokscale/core native 0.1.0; Kibble Codex parser 1; Kibble Cursor stop parser 1; tokscale 4.14.0; Copilot session events v1; VS Code chat session JSON/JSONL v3
covers   8 native clients, Codex transcripts, experimental Cursor stop hooks, and CLI fallback for additional agents; GitHub Copilot CLI and VS Code chat counters with session ids
rows     20 in the last 7 days
sessions 83
agents   claude-code, codex

OK

The agents line is the one to read: it names every agent whose logs were found on this machine in the last 7 days. (none found) means no supported agent was used here in that window, not that something is broken.

kibble push

Example output

2026-09-15..2026-09-16  4 rows across 2 day(s)  [tokscale-core+codex+cursor+cli]
  claude-code        $61.20       88,402,115 tokens
  codex               $2.14        4,010,338 tokens
  TOTAL              $63.34

     9 sessions   p50 $3.10  p90 $17.90  max $19.02   top 10% = 30% of spend

  repos: 2 (names only, never paths)
  activity: 9 sessions, 41 human turns, 612 tool calls (8 errored), 37 edits +820/-241 lines, 0 hook errors, 1 compactions

  billing:
  claude-code    max 5x subscription
  codex          plus subscription

  capabilities: 4 with recorded use, 43 with no recorded use (names only; Codex coverage: explicit skill selections and recorded slash commands)

Pushed 4 rows, 9 session ids, 47 capability rows, 4 repo rows to https://app.usekibble.com.

After the first sync a push covers yesterday and today; a machine that was off for a week sends the whole week. The dollar figures are estimates at the vendor's list rates, so a subscription user sees what the same work would have cost on an API key, not a bill. kibble push --dry-run prints the same summary and ends with the full list of what the payload contains, without sending it.

On the dashboard, My usage lists each linked machine with its last push time. kibble logout, or unlink on My usage, revokes a machine; running kibble login again just renews it.

What if something is not working?

Most problems are one of these. Find the message the terminal printed.

Anything else: write to hello@usekibble.com with the last lines the terminal printed. They contain counts and paths on your own machine, never prompts or code.

What data does Kibble collect?

Never collected: prompts, file contents, diffs, tool arguments, paths, hostnames, hardware ids. The server's ingest schema is strict: a request with an unknown field is rejected. Every field is listed in the privacy policy and every line that sends one is in the source.

How do I read my usage in the terminal?

kibble usage prints this month's totals by agent and by model for the person the machine is linked to. It reads from the dashboard, so it needs a linked machine and a network connection, and it shows the same numbers as the screen.

kibble usage                  # this month, against the month before
kibble usage --range week     # the last 7 days; also day, or 90d
kibble usage --since 2026-09-01 --until 2026-09-15
kibble usage --json           # everything, day by day, for scripts

Example output

$ kibble usage --range week
you@company.com at Acme  2026-09-10..2026-09-16
Scope: Personal
  total      $214.60      312,904,118 tokens   +$38.15 vs prior 7 day(s)

  by agent
    claude-code                     $198.20      284,110,377 tokens
    codex                            $16.40       28,793,741 tokens

  by model
    claude-opus-5                   $171.05      240,882,910 tokens
    claude-sonnet-5                  $27.15       43,227,467 tokens
    gpt-5.6-luna                     $16.40       28,793,741 tokens

  Add --json to the same command for full day-by-day detail.

Ask your coding agent instead

kibble skill install

Example output

installed  /Users/you/.claude/skills/kibble-usage/SKILL.md
skipped  codex (not installed on this machine)
skipped  copilot (not installed on this machine)
skipped  cursor (not installed on this machine)

Ask your coding agent about "my AI usage this month" and it will read the data with `kibble usage --json`.

The skill teaches Claude Code (and Codex, Copilot and Cursor where they are installed) to answer questions such as "how much did I spend on AI this week, by model?" by running kibble usage --json. Credentials stay in the CLI's own config; the agent never sees them. Run the command again after a CLI upgrade to refresh the skill.

Team and organization totals, for owners and managers

By default a machine can read its own person's usage only. An owner or manager who wants team or organization totals in the terminal grants that to the machine explicitly, once:

kibble login --reporting
kibble usage --list-scopes

Example output

$ kibble usage --list-scopes
Role: owner
Available scopes: self, team, org
  2f6d9a1c-1b7e-4c1a-9a3b-5d0e8f7a6b21  Engineering
  8c41e0d2-7a9f-4e3b-b6d1-0f2a9c7e5d44  Platform

kibble usage --scope team --team Engineering --range week
kibble usage --scope team --range week     # all teams you may read
kibble usage --scope org --range week      # owners only

Owners can read the organization or any team. Managers can read the teams assigned to them, and themselves. Members can read themselves. The grant is checked on the server against your current role on every request, so a role change applies immediately. A plain kibble login later switches the machine back to personal-only reads. Team and organization reports are aggregates: no roster of people or machines comes back.

How do I set it up for a team?

1. Choose Start with your team and create your organization. Pro is $100/mo or $1,000/yr for up to 30 people, then $5 per person a month. The first subscription includes a 30-day trial, with a payment card required. Review the price and billing interval before checkout; cancel before the trial ends to avoid the first charge.
2. Open Settings, Invite by email and enter one address or several at once. They accept with the invited Google address, install the collector and run kibble login on every machine they want included. If the browser uses a different Google account, switch accounts on the invitation page.
3. Optional: add your Anthropic Admin API key on Settings. Kibble syncs Claude Console analytics hourly and uses vendor estimates for matching daily usage; overlapping sources are never summed.

Roles: engineers see their own machines, owners see totals per person, team, model and repo, managers see the teams they are assigned. Nobody sees content.

A message to send your engineers

Copy it as it is, or change the first line.

Hi team. Please set up the Kibble collector on every machine where you use Claude Code, Codex or GitHub Copilot. It takes two minutes and sends counts only, never prompts or code.

1. Accept the Kibble invitation in your email with your work Google account.
2. Open a terminal (Terminal on macOS, PowerShell on Windows) and paste:
   npm install -g @usekibble/cli && kibble login
3. Approve in the browser, then press Enter at the updates question.

Guide with sample output: https://usekibble.com/docs

How do I know the team is ready?

Use Set up your team on Overview or Settings to check progress before interpreting totals. In organization means membership exists, which can also come from vendor imports; it does not prove someone signed in. A connected machine is not proof that usage has arrived.

1. Review pending invitations and follow up with engineers who have not joined.
2. Check the separate statuses for a connected machine, a previous upload and usage records dated in the last seven days. Recent usage dates, including vendor data, do not prove a recent upload. Each engineer can check their own machines' last push on My usage. For a missing machine, ask its owner to run kibble push, then kibble doctor if collection fails.
3. Confirm that each relevant laptop, desktop and CI runner is included. A connected laptop does not cover logs on another machine.
4. Read Overview for the same date range, read the observed coverage in Read your first results, and identify one change by agent, model or repository. Compare list-rate estimates with subscription plans and vendor invoices before calling the change a saving or extra charge.

Start with a few reporting engineers, then complete coverage before comparing the whole team. Older history is available only if the corresponding local logs exist; a new connection cannot reconstruct deleted logs or activity on an unconnected machine.

How do I count agents running in CI?

A CI run is automation, not a person's seat, so it uses a write-only credential from Settings instead of kibble login. Two steps: create the credential, then add two lines to the job.

1. Create the credential. In the dashboard open Settings, find CI connections, give the connection a name such as "PR review workflow", pick a team or organization-wide, and click Create credential. Copy it now: it is shown once. Store it in your CI's secret store under the name KIBBLE_CI_TOKEN. On GitHub that is the repository's Settings, then Secrets and variables, then Actions, then New repository secret. The credential can only send receipts: it cannot read the dashboard, and an owner can rotate or revoke it at any time.
2. Wrap the agent command. kibble run starts the agent, watches its output for token counts, and writes a small JSON receipt. kibble ci upload sends the receipt, and runs even when the agent failed, so failed runs are counted too.

   - name: Run the coding agent
     run: >-
       kibble run --receipt "$RUNNER_TEMP/kibble-ci.json"
       -- codex exec "Run the tests and report failures"
   
   - name: Send usage to Kibble, even when the agent failed
     if: ${{ always() }}
     env:
       KIBBLE_CI_TOKEN: ${{ secrets.KIBBLE_CI_TOKEN }}
     run: kibble ci upload "$RUNNER_TEMP/kibble-ci.json"

   For Claude Code the first step is kibble run --receipt "$RUNNER_TEMP/kibble-ci.json" -- claude -p "Run the tests and report failures". Put Kibble's own options before the --, the agent and its arguments after it. The agent keeps its own credentials, permissions and sandbox; Kibble changes none of them and removes KIBBLE_CI_TOKEN from the agent's environment.

A complete GitHub Actions workflow, for a repository where Codex is authenticated with a secret the way your team already does it:

name: Agent with Kibble
on: [workflow_dispatch]

jobs:
  agent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install Kibble and the agent (pin both versions)
        run: npm install -g @usekibble/cli@0.9.0 @openai/codex

      # Authenticate the agent here, the way your team already does it.

      - name: Run the coding agent
        run: >-
          kibble run --receipt "$RUNNER_TEMP/kibble-ci.json"
          -- codex exec "Run the tests and report failures"

      - name: Send usage to Kibble, even when the agent failed
        if: ${{ always() }}
        env:
          KIBBLE_CI_TOKEN: ${{ secrets.KIBBLE_CI_TOKEN }}
        run: kibble ci upload "$RUNNER_TEMP/kibble-ci.json"

Example output of the two steps

Kibble run 6f2d9c1e-4b7a-4d7e-9a1c-2e8f5b3c7d10: succeeded; usage complete; cost unavailable. Receipt saved locally.
Kibble CI 6f2d9c1e-4b7a-4d7e-9a1c-2e8f5b3c7d10: accepted.

The receipt names the checkout it ran in, the repository name from the git remote and the branch, never a path, so CI work sits beside the same repository on laptops. In the dashboard, CI usage in the navigation lists every receipt with its outcome, tokens and estimate, grouped by repository, and Overview shows one line for CI. These estimates stay separate from laptop and vendor totals, because a receipt has no invoice identity to reconcile against. A Codex receipt has tokens but no price, which is the cost unavailable above; a Claude Code receipt carries the agent's own estimate instead. Unavailable stays unavailable in the dashboard, never a zero.

When the agent already saves its sessions

Keep the agent step exactly as it is and add one collection step after it, pointed at the job's own session folder. Never point it at a shared runner's personal history.

- name: Collect the agent's saved sessions, even when it failed
  if: ${{ always() }}
  env:
    KIBBLE_CI_TOKEN: ${{ secrets.KIBBLE_CI_TOKEN }}
  run: >-
    kibble ci collect --agent codex
    --sessions-dir "$CODEX_HOME/sessions"
    --receipts-dir "$RUNNER_TEMP/kibble-receipts" --upload

Set CODEX_HOME to a folder inside the job, such as ${{ runner.temp }}/codex, before the agent runs. For Claude Code use --agent claude-code --sessions-dir "$CLAUDE_CONFIG_DIR/projects", with CLAUDE_CONFIG_DIR set the same way. If delivery fails, keep the receipts folder as a build artifact and send it later with kibble ci upload "$RUNNER_TEMP/kibble-receipts/"*.json; a receipt sent twice is acknowledged as a duplicate, never counted twice, and the agent is never rerun to resend one.

How do I collect Cursor usage?

Cursor support is experimental. Kibble registers hooks in Cursor that record token counts for every turn from then on; there is no import of earlier history. Optionally, kibble cursor sync adds your Cursor account's daily totals.

kibble cursor install
kibble cursor status

Example output

$ kibble cursor status
Cursor stop hook: installed
Cursor postToolUse hook: installed
Cursor postToolUseFailure hook: installed
Cursor beforeSubmitPrompt hook: installed
Cursor subagentStop hook: installed
Captured turns: 14
Captured tool calls: 97
Captured prompt submissions: 14
Captured subagent completions: 0
Paired observed turn durations: 14
Latest captured UTC day: 2026-09-16
Experimental: token usage requires token-bearing stop hooks. Turn timing measures hook receipts, not model execution. Historical usage, skill/command invocations and full activity parity are not established.

When automatic collection is on, kibble login installs the hooks itself on a machine that has a .cursor folder, and every push repairs a missing one. Existing Cursor hooks are kept. The hooks write counts only, to a file in Kibble's own config folder; kibble push sends them with everything else.

kibble cursor sync             # add your account's daily totals
kibble cursor account-disable  # stop sending them
kibble cursor uninstall        # remove the hooks; counts stay

The first kibble cursor sync signs in to your Cursor account and saves a private snapshot; run it again whenever you want fresher account totals. On days the account snapshot covers, it replaces the hook counts instead of adding to them, so two laptops on one account never double-count. What Cursor does not expose stays unknown rather than zero: edits and lines, automatic skill use, and turns before the hooks existed.

How does the CLI update?

Only with your permission. The first interactive login asks once; press Enter to let the CLI install releases Kibble has approved, or type n to stay on the version you installed. Nothing else on the machine changes either way.

kibble update status     # the choice, the versions, the last check
kibble update            # check for an approved release now
kibble update enable     # allow updates, or answer the question later
kibble update disable    # stay on the current version
kibble update rollback   # previous version, updates off

Example output

$ kibble update status
Automatic updates  enabled
Current version  0.9.0
Previous version  none
Last check  2026-09-16T09:00:02.412Z
Last error  none

With updates on, the hourly push checks about once a day, downloads a release into a private folder beside the config, verifies it, and switches only after it starts correctly. A release that fails any check is discarded and the current version keeps collecting. Updates never ask for administrator rights and never take instructions from the dashboard server. To upgrade by hand at any time:

npm install -g @usekibble/cli@latest

Setting up a machine without a terminal, in a script? kibble login --auto-update answers the question with yes. A company that deploys software centrally sets KIBBLE_NO_UPDATE=1 in the environment and the CLI never checks.

How do I stop or remove it?

One command stops the reporting and removes the background job. What the machine already reported stays in the dashboard.

kibble logout

Example output

Forgot the link token on this machine.
Removed the background push.
Revoked "Mac · linked 2026-09-16" on the server.

Unlink on My usage revokes a machine from the dashboard side, for a laptop you no longer have; its background job then fails harmlessly every hour until someone runs kibble logout there. To remove the command and every file it kept, also run:

npm uninstall -g @usekibble/cli
rm -rf ~/.config/kibble

On Windows the second line is Remove-Item -Recurse -Force "$HOME\.config\kibble". That folder held the link token, the sync position, the push log, any Cursor counts not yet sent, and the updater's private copies of the CLI. kibble schedule uninstall alone removes only the background job, and refuses while your organization requires automatic collection; the way to stop a machine is kibble logout.

How do I use the numbers?

Read the dashboard weekly:

• Top movers on Overview: ask about an outlier before judging it; a migration or a new joiner is the usual answer.
• Capabilities: review Claude Code skills with no observed invocations over a representative period. Check collection coverage, intended manual use and emergency workflows before removing one. Codex records explicit skill selections and recognized command submissions. Automatic skill reads and skill cost attribution remain unobserved, so zero does not mean unused. See the capability cleanup guide.
• Spend by model per repo: set a cheaper default model where the work is small edits.
• High spend plus high errors in one repo: fix the repo (an AGENTS.md, a one-command build), not the person.

Do not set per-engineer budgets, rank people by spend, or read transcripts. The full method is in the measuring-teams post.

Questions

Why is my dashboard empty after I signed in?

Install the collector and run kibble login on a machine with supported agent logs. When automatic collection is on, login uploads immediately; otherwise run kibble push. The first sync includes today and the preceding 29 UTC days where logs exist. Refresh My usage after a successful push. Check the selected date range, kibble doctor and kibble schedule status if numbers are missing.

Does the collector read my prompts or code?

No. It reads the usage logs the agents already write and sends per-day counts: token totals, model names, opaque session ids and repository names, plus supported skill, command and MCP names and counts when capability reporting is on. Never prompts, file contents, tool arguments or paths. The server's ingest schema is strict, so an unexpected field is a rejected request, and the collector is open source, so what leaves each machine can be read line by line.

Which agents does Kibble collect?

Claude Code, Codex and GitHub Copilot, including the Copilot CLI and Copilot Chat in VS Code, are collected as soon as the collector is installed. Cursor is experimental: kibble cursor install registers hooks that record turns from then on, and kibble cursor sync can add your account totals. Install the collector on every machine where an agent runs.

Does Kibble work on Windows and Linux?

Yes. The same two commands work in PowerShell on Windows and in any terminal on macOS and Linux. The hourly background push is a Task Scheduler task on Windows, a crontab entry on Linux and a launchd job on macOS, registered by kibble login when the organization requires automatic collection. The configuration lives in the .config/kibble folder of your home directory on every platform.

Do I have to keep the terminal open?

No. Once kibble login has finished, close the terminal. The background job pushes every hour and at startup, and each push sends only the days since the last accepted one. A machine that was asleep or offline catches up on its next push, back to 30 days.

How many machines can one person link?

Two on the free plan, a laptop and a desktop; Pro and self-hosted have no cap. Each machine shows on My usage with its last push. Running kibble login again on a machine the server already knows renews its token instead of counting as a new machine.

Can I count agents running in CI?

Yes. An owner creates a write-only credential under Settings, CI connections, and the job stores it as KIBBLE_CI_TOKEN. Wrap the agent command in kibble run, or run kibble ci collect over the job's saved sessions, then deliver the receipt with kibble ci upload. CI usage has its own page in the dashboard and is never mixed into laptop totals.

How do I stop a machine from reporting?

Run kibble logout on the machine, or open My usage and unlink it there. Either way the machine's link token is revoked immediately. What it already reported stays, so your history does not change.