English | 繁體中文

cc-footprint

"How is the context full already? I'm halfway through the task — and it just auto-compacted. Again."

"Running Claude Code in several windows is blazing fast… so why does my machine keep getting slower?"

"My statusline is crammed with things I never look at. Can I just turn them off?"

Let cc-footprint solve these for you.

It puts each Claude Code session's footprint — the context it carries and the RAM it holds — in that session's own statusline. You see what is filling the context and which session is eating the memory, and it helps you shrink both. Every item can be switched on or off from the tray icon, so the line shows only what you care about.

<p> <img src="screenshots/cc-footprint.png" alt="A Claude Code session: the statusline on the last two lines, the /footprint pane at the right" width="75%"> <img src="screenshots/tray-menu.png" alt="The tray menu: one switch per statusline item, in three groups" width="22%"> </p>

Read it as: the context is 92% full, and this turn alone added 83k tokens to it. What fills it is mostly command output (31%), file reads (26%) and Claude's own output (26%). The 5-hour limit resets in 5 minutes.

On the memory side: this session — its claude process and everything it started — holds 310 MB of the 1.3 GB all your sessions use.

In the large picture, the two lines at the bottom are the statusline, always on screen, and the panel at its right is the plugin's /footprint pane, for when you want the whole breakdown. The pane reads again at the end of every turn and every half minute while it is open, so its figures can trail the statusline's by a moment, as they do in this picture. The small picture is the tray menu, where each statusline item is switched on or off.

Runs on Windows and Linux; macOS is next. Formerly claude-status-monitor-4-windows — existing installs upgrade by re-running install.ps1.

Context: how full, what's filling it, how to shrink it

A session's whole context is re-read on every request. The fuller it gets, the more each turn costs, the faster your 5-hour and weekly limits burn, and the sooner auto-compaction starts dropping earlier detail.

cc-footprint keeps that whole chain in view, per session:

| Question | Item | What you do with it | |---|---|---| | How full is it? | Ctx | /compact or start fresh before a big change, not in the middle of one | | Was that last step expensive? | ↑15k — tokens this turn has added so far | A big jump right after a file read or a long command output tells you which step to avoid repeating | | What is filling it? | Top source, e.g. (files 29%) (off by default), and MCP$ — share of this session's cost that went to requests consuming MCP tool results | think high: lower the effort level. files or shell high: read less at a time. An MCP server or MCP$ high: move that work to a subagent | | What is it costing me? | 5h, Week with the time left until each resets, optional session cost | Pause the sessions that can wait before you hit a limit — or wait out a reset that is minutes away | | How do I shrink it? | Global optimizations | Move browser work into a subagent's short context, then watch MCP$ drop |

Claude Code's own /usage attributes cost to MCP servers too, but as a 24h/7d total across all sessions. MCP$ is this session, live, where you are already looking.

RAM: find the session that's heavy

Task Manager shows five identical claude.exe rows and no way to tell them apart. Other statuslines show how full the machine's RAM is — that tells you something is heavy, not which session.

• Claude 1.2G/3.4G — this session / all sessions. A session is its claude process plus everything under it: the MCP servers it started and the shells its tools run in. Find the heavy one and close or restart it (claude --resume brings it back).
• MCP 410M(6) — this session's own MCP servers and what they hold. Every session starts its own copy of each local server, so this is often where the memory went.
• +2 orphaned 240M — after MCP, in yellow: MCP servers still running although the process that started them is gone. They do nothing but hold memory; end them in Task Manager.
• Sys 71% — whether memory is why the machine feels slow at all.

Claude Code doesn't pass a process ID to the statusline, so cc-footprint maps each session to its process from the session files Claude Code writes, and adds up that process's whole tree.

Built for Windows, runs on Linux too

Spawning a process on Windows costs hundreds of milliseconds, and statusline tools that spawn on every render have been reported to leave orphaned processes piling up. cc-footprint's statusline spawns nothing: a background tray app does the slow work once a minute, and the statusline reads the cached answer over a local socket in ~35 ms. Details in How it works.

On Linux the same monitor reads the process table straight from /proc, with no command spawned at all.

Quick install

Windows — needs Windows 10/11, Node.js 18+ and Git Bash (comes with Git for Windows):

git clone https://github.com/ilwu/cc-footprint
cd cc-footprint
.\install.ps1

Linux — needs Node.js 18+ and bash:

git clone https://github.com/ilwu/cc-footprint
cd cc-footprint
./install.sh

Open a Claude Code session and the statusline appears. The installer:

1. Installs npm dependencies
2. Copies the statusline script to ~/.claude/
3. Points statusLine in settings.json at it — if you already had your own, it is backed up to *.bak first, and the rest of settings.json (key order included) stays as it was
4. Makes the monitor start when you log in: a startup shortcut on Windows, a systemd user service on Linux
5. Starts the monitor. On Windows it is a tray app (orange footprint, bottom-right); on Linux it runs in the background with no icon
6. Lists the optional global optimizations — listed only, never applied for you

Re-running the installer is safe: it stops the running monitor, refreshes the files, and starts it again.

What you see

On Windows, right-click the tray icon to turn items on or off. On Linux, set them to true or false in ~/.cc-footprint/config.json. Either way the change applies at once.

| Item | Shows | When it helps | Default | |------|-------|---------------|---------| | Context & usage | | | | | Context Window | Context usage % with progress bar | Near full, auto-compaction kicks in and earlier detail can be lost — /compact or start fresh before a big change. A longer context also makes every request cost more; if it climbs unusually fast, check MCP$ | On | | Context: Growth This Turn | ↑15k after Ctx — tokens the current turn has added to the context so far (↓ after a compaction); yellow once one turn takes 5% of the window | See right away that a step was expensive, instead of noticing at 90% | On | | Context: Top Source | (files 29%) after Ctx — the largest thing in the context and its share: output (Claude's replies and tool calls), think, files, shell, search, web, agents, prompts, summary (after a compaction) or an MCP server's name | Know what to change — see the table above | Off | | MCP Usage Share | MCP$ — share of this session's cost spent on requests that consumed MCP tool results (subagents included); 0% until the session uses an MCP tool | When Ctx climbs fast, it flags that browser work may be the cause — every click or page read re-reads the whole conversation, and the page content lands in the context. If it's high, hand browser work to a subagent (see global optimizations), then watch it drop | On | | 5h Usage | 5-hour rate-limit usage % (subscription plans; hidden when Claude Code doesn't report it) | Close to the limit: finish the important work first and pause sessions that can wait | On | | Weekly Usage | 7-day rate-limit usage % | Budget the rest of the week; if it's going fast, push big tasks back or use a cheaper model | On | | Limit Reset Countdown | Time left until each limit resets, shown after 5h and Week (2h13m, 4d21h) | Decide whether to wait for the reset or keep going | On | | Session Cost | Cumulative cost in USD | On API billing, see what a single task cost; on a subscription, compare the cost of different approaches | Off | | Memory | | | | | System Memory | RAM usage % with progress bar | The machine feels slow: check whether memory is the cause, and hold off on new sessions when it's nearly full | On | | Claude Memory | This session / all sessions total. A session counts its whole process tree: the claude process, its MCP servers and its tools' shells | Several sessions open: find the heaviest one and close or restart it (--resume brings it back) | On | | MCP Memory | This session's own MCP servers: memory and count. Then, in yellow, +N orphaned: servers on this machine whose parent process is gone | See how much of the session is MCP servers; end the orphaned ones, which only hold memory | On | | Session info | | | | | Session ID | Full UUID | Reopen this session later with claude --resume <id>, or include it in a bug report | On | | Project Path | Project root directory | With several windows open, tell at a glance which project this one is in before typing a command | On | | Model + Effort | Current model and the effort level it runs at (e.g., Opus 5.5 · high) | Confirm which model and effort are active after /model or /effort, or when projects default to different ones. Effort drives how much thinking lands in the context | Off | | Lines +/- | Lines added / removed this session | Before committing, check whether the change grew bigger than intended | Off | | Session Duration | Elapsed wall time | A long-running session usually has a swollen context and memory too — a hint to restart | Off |

Plugin: alerts and the /footprint pane (early access)

The statusline stays short. The detail lives in a Claude Code plugin that speaks up only when something happens, and shows the rest when you ask for it:

• A toast when a turn bloats the context — Context +45k this turn (5% of the window), mostly file reads. It fires when one turn adds 5% of the window or more, and names what grew when one thing explains most of it.
• A toast before auto-compaction — once, when the context is 85% of the way to the auto-compact point, so you can /compact on your own terms instead of mid-task.
• A toast after a compaction — Context compacted: 181k → 9k.
• /footprint opens a pane with everything: the full context breakdown, how far away auto-compaction is, both limits with their reset times, and the memory of every running session.

Install it from inside Claude Code:

/plugin marketplace add ilwu/cc-footprint
/plugin install cc-footprint@cc-footprint

or from a terminal, with claude plugin marketplace add ilwu/cc-footprint and claude plugin install cc-footprint@cc-footprint. New sessions load it; claude plugin uninstall cc-footprint@cc-footprint removes it. To try it from a clone without installing, start one session with claude --plugin-dir C:\path\to\cc-footprint\plugin.

The plugin reads the tray app on 127.0.0.1:19823. Without the tray app it still reports growth and the compaction point from Claude Code's own figures, but has no memory figures and no breakdown. Claude Code's plugin hooks API is early access and can change between releases; this plugin was written against 2.1.289.

Global optimizations

Seeing it is half the job; these shrink the context. They change Claude Code's global setup in ~/.claude/, which affects every project — so the installer only lists them and leaves the decision to you.

Delegate browser work to a subagent

Browser automation through the claude-in-chrome tools is expensive in a long session: every click, scroll or read is a separate request that re-reads the whole conversation. In one measured session, 72 browser requests re-read 110k tokens each on average — about 75% of what those requests cost — while everything the browser actually returned was about 15%.

The rule tells Claude to hand browser tasks of more than two or three actions to a browser subagent, which does the work in its own short context and reports back. Claude still uses the Chrome tools directly for a quick look at a page, when you want to watch each step, or when you have to act in the browser yourself (login, 2FA).

To apply (both files are in this project's claude/ folder):

1. Copy claude/agents/browser.md to ~/.claude/agents/browser.md. If a file with that name is already there, compare them before deciding.
2. Append the full contents of claude/global-rule.md — including the <!-- cc-footprint:browser-agent:start/end --> markers — to the end of ~/.claude/CLAUDE.md, keeping what is already there.
3. Restart any open Claude Code sessions.

Keep the markers: they are how uninstall.ps1 finds and removes just this block. Measure it with MCP$, and edit model: in browser.md to run the subagent on a different model.

For AI assistants

If you are an AI assistant (such as Claude Code) installing this for a user: after install.ps1 finishes, ask the user whether to apply the global optimizations above, and apply them only with a yes. Read the existing ~/.claude/CLAUDE.md and ~/.claude/agents/ first and merge — never overwrite. When run under Claude Code, the installer prints the same instructions at the end of its output.

How it works

A slow statusline shows nothing: Claude Code reruns the script on every update (debounced at 300 ms) and cancels a run that is still going when the next one starts. On Windows, the obvious way to find a session's memory is far too slow for that:

| Operation on Windows | Time | |-----------|------| | PowerShell process query | ~500–900 ms | | curl to localhost | ~650 ms (process spawn overhead) | | cat via pipe | ~230 ms | | one $(...) subshell in Git Bash | ~30 ms |

So the work is split in two:

┌─ Tray app (Node.js, 127.0.0.1:19823) ────────────────────────┐
│  Every 60 s: one CIM query for the process table, then each  │
│  session's tree is added up (MCP servers, tool shells)       │
│  Reads  ~/.claude/sessions/*.json      (session → PID)        │
│         ~/.claude/projects/**/*.jsonl  (MCP$ and context)     │
│  Serves /session/:id  /context/:id  /status  /config          │
│  Config ~/.cc-footprint/config.json                           │
└───────────────────────────────────────────────────────────────┘
          ▲ /dev/tcp, ~35 ms — no curl, no jq, no subshells
┌─ Statusline (bash) ───────────────────────────────────────────┐
│  Runs on every update, asks for its own session, prints ANSI  │
└───────────────────────────────────────────────────────────────┘

(wmic, the old fast-ish option, no longer ships with Windows 11 24H2+.)

Configuration

The tray menu on Windows writes ~/.cc-footprint/config.json; on Linux you edit that file yourself (defaults shown):

{
  "sys_mem": true, "claude_mem": true, "mcp_mem": true,
  "ctx": true, "ctx_grow": true, "ctx_src": false, "mcp_use": true,
  "five_hour": true, "week": true, "resets": true,
  "session_id": true, "path": true,
  "model": false, "cost": false, "lines": false, "duration": false
}

The tray app listens on 127.0.0.1:19823. To change the port, edit PORT in monitor/app.js and the matching port in statusline/statusline.sh.

Uninstall

.\uninstall.ps1     # Windows

./uninstall.sh      # Linux

Removes the startup shortcut, this tool's statusline and statusLine setting, the global optimizations (browser.md and its marked block in CLAUDE.md), and the config folder. A statusline this tool did not install is left alone; if the installer backed up your previous settings, they are in settings.json.bak. The project folder stays — delete it yourself if you like.

Troubleshooting

Statusline shows ? or nothing — check that the orange footprint is in the tray; if not, double-click monitor/start.vbs.

Statusline shows offline — the tray app is not reachable. Restart it from the tray or start.vbs.

Claude memory shows - for a brand-new session — normal for a few seconds; the tray app picks up the new session on the next render.

Tray icon doesn't appear (Windows) — it may be in the overflow area; click the ^ arrow in the taskbar.

Is the monitor running? (Linux) — systemctl --user status cc-footprint; where there is no systemd user session, the installer says so and prints the command to start it yourself.

License

MIT