---
title: Kumo Usage CLI Bar
description: A spend-and-remainder panel under the Claude Code and Codex prompt — one command to install, it finds your key itself, and it shows what is left: a package, the balance, or your own ceiling.
keywords: cli, statusline, claude code, codex, spend, remainder, package, balance, limit, tree cost
group: integrations
---

## What it is {#what keywords="panel, statusline, remainder, spend"}

A line under your CLI agent's prompt. Across the head — the panel's name and two prices:
**Session Cost**, what this session has cost, and **Tree Cost**, what the working branch has
cost across every session that worked on it. On the left — the folder, the branch, the key
paying, and the model with its reasoning level. In the middle — token spend per minute, the
`Σ` total, and a thin line of what is left. On the right — the context in use.

```text
———— Kumo Router Usage ————          Session Cost $1.84   Tree Cost $12.4
my-project (main)                 │ ▂▃█▇▆▅▆▆██▇▆▃▃▃  Σ 12.9M │   session ctx
key Example Key  Opus (1M) High │ ━━━━── package 18.4M left cache 95%  46%
```

**Tree Cost** is kept per working tree and branch: the panel holds a ledger of each
session's last known total in `~/.claude/statusline-state/` and shows their sum. Switch
branches and the figure changes; switch back and it is the one you left. It answers "what
has this task cost me", not "what has this chat cost me".

It works with Claude Code (a panel under the prompt) and with Codex (its own footer line).
No dependencies — `python3` (3.8+) and `curl` are all it needs.

## Install {#install keywords="curl, installer, install.sh, agent"}

One line in a terminal:

```bash
curl -fsSL https://kumorouter.com/tools/kumo-usage/install.sh | bash
```

The installer **asks nothing**. It finds your Kumo key itself — in the environment
(`KUMO_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`), then in
`~/.claude/settings.json`, `~/.codex/config.toml` and the current directory's `.env` — asks
the account for the key's name and funding, and fills in the config. The secret is never
written down: only the NAME of the variable holding it goes into the file.

If an agent should do the installing, hand it the ready prompt beside the installer at
`https://kumorouter.com/tools/kumo-usage/prompt.md` — the same text the console's button copies.

:::note
Settings are read at start. Restart Claude Code (or run `/statusline`) and Codex — the
panel does not appear until you do.
:::

## What lands on the machine {#files keywords="files, settings.json, config.toml, uninstall"}

| where | what |
|---|---|
| `~/.claude/kumo-usage/` | the renderer: `cc_statusline.py`, `providers.py` |
| `~/.claude/statusline.json` | the config: `title`, `key_name`, `limit`, `kumo` |
| `~/.claude/settings.json` | the `statusLine` key; the previous file stays beside it as `.bak` |
| `~/.codex/config.toml` | `[tui] status_line`; the previous file stays beside it as `.bak` |

The same script removes it:
`curl -fsSL https://kumorouter.com/tools/kumo-usage/install.sh | bash -s -- --uninstall`. The config stays — delete
it by hand if you no longer want it.

## Four kinds of remainder {#limits keywords="package, balance, key ceiling, project ceiling, tokens, dollars"}

Kumo sells tokens and money, so the line under the chart counts down one of four things.
Which one is the `limit` block in `~/.claude/statusline.json`; the installer fills it in
from what the key spends from.

| `kind` | what it shows |
|---|---|
| `package` | what is left of a bought package, `cap` in tokens |
| `money` | the money on the balance (Pay As You Go), `cap` in dollars |
| `key` | your own ceiling on this key — in tokens or in dollars |
| `project` | the ceiling on the project — in tokens or in dollars |

```json title=~/.claude/statusline.json
{
  "title": "Kumo Router Usage",
  "key_name": "Example Key",
  "limit": { "kind": "package", "cap": 25000000, "unit": "auto" },
  "kumo": { "enabled": true, "key_env": "KUMO_API_KEY" }
}
```

`unit` is `auto` (a package in tokens, everything else in dollars), `tokens` or `usd`. The
line is green, amber at 30 % left, red at 10 %.

## Where the number comes from {#source keywords="account, key, estimate, approximate"}

In order, and the order is the point:

1. **the Kumo account**, read with the same key the agent routes through. Only the account
   knows the package, the balance and what the router actually billed;
2. a number written into `limit.remaining` by hand, for a machine that cannot reach the
   account;
3. a gateway balance from the `router` block, for a panel pointed at something that is not
   Kumo;
4. last, and marked `≈`: `cap` minus the spend measured from **this machine's** own
   transcripts. That is one client's estimate rather than the account's, and the panel says
   so.

The key leaves the machine for exactly one address — the one in `kumo.url` — and is read in
the background: the prompt never waits on a network.

## Diagnostics {#doctor keywords="demo, doctor, error, missing"}

```bash
python3 ~/.claude/kumo-usage/cc_statusline.py --demo      # a preview on fake data
python3 ~/.claude/kumo-usage/cc_statusline.py --doctor    # config, billing mode, width, account
```

The panel never breaks the prompt: on any internal error it prints one line,
`<model> statusline error: …`. If there is no panel at all, restart the agent; if
`--doctor` says the key was not found, put it in the environment variable named by
`kumo.key_env`.

The full description and the screenshots live beside the installer at
`https://kumorouter.com/tools/kumo-usage/README.md`.