Make the plan-usage statusLine exporter delegate instead of replacing the user's statusline

[irisitymichaelgrundberg]

The problem

Codeman injects a statusLine into each managed repo's .claude/settings.local.json so the Plan Usage chip gets live rate_limits numbers. Claude Code ranks that project file above ~/.claude/settings.json, so the injection replaces whatever statusline the user configured globally.

The replacement is not silent, and it is worse than just losing your own line. The exporter prints whatever /api/status-telemetry returns. That route answers codeman for a session id it does not know, so running claude by hand in a managed repo makes the statusline the single word codeman. I hit this across seven repositories before working out where it came from.

applyStatusLineConfig already refuses to overwrite a hand-authored statusLine, and that guard works. It does not catch this case, because the user's line is inherited from ~/.claude/settings.json rather than written into the repo, so there is nothing in the file for the guard to see.

What I would like to propose

Keep the data tap and give the line back. The exporter becomes a generated shim that forwards the same blob to /api/status-telemetry, resolves the statusline its own entry shadows, runs that command with the same blob on stdin, and prints its output. Codeman's footer still appears when there is nothing to shadow, so the exporter keeps its value for a user with no statusline of their own.

The shim follows deepseek-status-shim.ts closely, since that pattern is already in the repo and solves the same distribution problem. It is a versioned .mjs written into the data dir through dataPath(), refreshed when its marker changes, and written with temp-and-rename because a live render can be executing the path during a refresh.

Three details are worth calling out:

• The delegate resolves at render time, by walking the settings files Claude Code consults from the render directory upward and then the home ones, taking the first statusLine that is not Codeman's own. Resolving late means a user who edits their global statusline sees the change with no reinjection.
• Ownership moves to a version-free token in the shim's filename, and isCodemanStatusLine() still accepts the old /api/status-telemetry command. Without that second form, every repo an older Codeman managed would read as hand-authored, the upgrade would refuse to touch it, and the user would keep the replacing exporter forever.
• The shim skips both of its own command forms while hunting for a delegate, which is also its loop guard.

What I have and where

I built this before opening a Discussion, which is the wrong order under CONTRIBUTING, and I am posting rather than sending a PR so the design gets a look first. The branch is here if it is useful:

https://github.com/irisitymichaelgrundberg/Codeman/tree/feat/statusline-shim-delegates

It adds src/statusline-shim.ts, rewires generateStatusLineCommand() and the ownership check in hooks-config.ts, and updates the plan-usage sections of CLAUDE.md and docs/architecture-invariants.md. There are 25 tests across test/statusline-shim.test.ts and test/hooks-config.test.ts. The shim tests run the real generated file as a subprocess against a live listener, because tsc never sees it. npm test is green at 6828, and typecheck, lint, format and the frontend syntax check all pass. I have been running it on my own machine since this morning.

Questions I would want answered before a PR

1. Should the shim also wrap a hand-authored statusLine in the repo's own settings.local.json? My branch keeps the current bail-out, so Codeman never owns an entry it would have to restore on uninstall. Wrapping it would cover more users at the cost of that guarantee.
2. Is a child process per render acceptable? The statusline fires on every assistant message. The shim runs the delegate and the POST concurrently, so the cost is the slower of the two rather than their sum, but it is still a spawn the inline curl did not do.
3. Is my settings precedence order right? I walk project settings.local.json, then project settings.json, then the two home files. I derived that from observed behavior rather than from a spec, and I am unsure whether Claude Code reads a user-level ~/.claude/settings.local.json at all. Getting this wrong means delegating to a command Claude Code itself would have ignored.
4. Is the fallback ordering the one you want? Right now the shadowed line wins, Codeman's footer fills in when there is nothing to shadow or the delegate produced nothing, and a brand string is the last resort so the statusline is never blank.

[Ark0N]

Thanks for the writeup. The diagnosis is correct, and I confirmed every part of it against master (1.28.0).

The exporter is written into <case>/.claude/settings.local.json by applyStatusLineConfig() in src/hooks-config.ts, and the isOurs guard there reads only that one file, so a statusline inherited from ~/.claude/settings.json is invisible to it. The design notes for the chip (docs/usage-limits-display-plan.md) only ever contemplate a statusLine already present in the case file, so the inherited case is an oversight rather than a tradeoff anyone weighed.

The bare word is real too, and there are three paths to it, not one. POST /api/status-telemetry returns the literal codeman for a session id it does not know (src/web/routes/status-telemetry-routes.ts). The exporter's own || echo codeman fallback is the one that actually fires when you run claude by hand, since CODEMAN_API_URL is exported only inside a managed session and curl fails without it. And formatSessionStatusText(null) in src/usage-telemetry.ts returns the same string for a session Codeman does know when the blob carries no model or token fields.

Seven repositories is not bad luck either. showPlanUsageLimits resolves to on for desktop (settings-ui.js), and the exporter goes into the working dir of every Claude session created from a desktop browser.

One thing that makes it worse than you described, and that I want fixed in the same pass: nothing takes the exporter back out. applyStatusLineConfig(dir, false) has no caller in src/ at all, only in test/hooks-config.test.ts. Both live call sites pass true, deliberately, because a repo's settings.local.json is shared by sibling sessions and one device turning the chip off must not yank the exporter another device depends on. The effect is that turning the chip off leaves the line in every repo it ever reached.

On your four questions:

1. Keep the bail-out. "Never clobber what we did not write" is the rule the whole settings-writing layer runs on, and the agent-skill injector next to it works the same way (marker-owned, never touches an unmarked user copy). An entry Codeman would have to unwrap on uninstall costs more than the users it would cover. Your branch has this right.

2. A spawn per render is defensible, since the current command already spawns a shell and curl. The delta is a Node process start: on my machine, ten runs each, node -e came out around 30ms against about 10ms for shell plus curl, before the delegate runs at all. The delegate's own cost is one the user already chose by configuring a statusline. What would settle it is a measurement on the slowest machine you can get to, not a fast one.

3. The documented set is three files, not four: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json (the copy mirrored here is docs/claude-code-hooks-reference.md). A user-level settings.local.json is not in it, and delegating to a command Claude Code would have ignored is the failure you named yourself, so drop that candidate unless you can show Claude Code reading it. The ancestor walk has the same shape of risk: pushing both project filenames for every parent directory up to the root can resolve a delegate from a .claude that is not a project root.

4. The ordering is right. The one thing I would change is the last resort. codeman is the exact string that cost you seven repositories of debugging, so the shim should treat a bare codeman from the route as "no telemetry" and fall through, or better, the route should answer an unknown session with an empty body. That second one is a two-line change in status-telemetry-routes.ts and is worth doing on its own, whatever happens to the rest.

There is a fifth question your list does not cover, and it is the one that decides the shape for me: Docker cases. The current command is portable by construction, env vars plus curl, and containerApiUrl() rewrites CODEMAN_API_URL so the same bind-mounted settings.local.json works from inside the container. A shim command bakes in process.execPath and a path under ~/.codeman, and neither exists in there: the only mounts are the workspace and the credential artifacts, and the image just creates an empty .codeman. Enabling the chip while a Docker case session is live does inject into that bind-mounted workspace today, because the injection loop in system-routes.ts has no docker guard, so the shim would render a broken statusline there. I want that answered before the exporter stops being self-contained shell. Falling back to the inline command for a docker case is one way; there may be a better one.

None of that is a no. The problem is real, the pattern you picked is the right one to copy, and delegating is the right instinct. Rebase first, the branch is 25 commits behind, and open the PR once the Docker path and the precedence question have answers. Posting the design here first was the right call under CONTRIBUTING even if the branch came before the thread.

[Ark0N]

Opened #416 with your branch as the first commit, credited to you as-is, plus one follow-up commit that answers the questions above so the thread does not have to wait on a second round.

What the follow-up changes:

• Docker. The injected command is now a shell guard, if [ -x <node> ] && [ -f <shim> ]; then exec <node> <shim>; fi; followed by the inline curl exporter. Inside a container neither path exists, so the same bind-mounted settings.local.json runs the shim on the host and the curl in the container. The exporter stays self-contained shell that way, which was the property I did not want to lose.
• Precedence. Exactly the three documented files: the two project files under workspace.project_dir (the launch directory), then ~/.claude/settings.json. The ancestor walk and the user-level settings.local.json are gone.
• The bare word. The route answers an unknown session with an empty body, formatSessionStatusText(null) returns '', the inline fallback ends in || true with curl -f, and the shim treats a literal codeman from an older server as no telemetry. With nothing to shadow and no footer, the line stays blank.
• Removal. Turning the chip off now takes the exporter out of live workspaces. statusLineTelemetry:false rides only the save that flips the chip off on a device, so a phone whose chip was never on cannot strip what a desktop depends on.
• Cost, measured against the live server: about 85 ms per render through the shim against 26 ms for the old curl. node:http alone was 38 ms of startup, so the shim now imports its transport lazily; that took it down from 112 ms.

Your tests run the shim as a real subprocess; the follow-up adds the injected command run the same way, with the shim path pointed at nothing to cover the container's view. Gate and CI are green. If you want to look over the follow-up commit, the PR is the place; otherwise it goes out in the next release pass.

[Ark0N]

Change of plan on the mechanism, same outcome for you, and a better one.

#361 from @timkjr had been reworked in parallel to stop Codeman writing a statusLine into settings.local.json at all: the exporter is passed to claude as an ephemeral --settings flag when Codeman spawns it, your own statusline is found the same three-file way (project-local, project, then ~/.claude/settings.json) and wrapped inside Codeman sessions, and a hand-run claude in a managed repo sees nothing of Codeman anymore. That is the stronger fix, so it is what went in, and #416 is closed. Your bare-word fixes moved across as a follow-up: the exporter prints nothing when it cannot reach Codeman, the route answers an unknown session with an empty body, and the footer is empty rather than codeman. Repos an older Codeman already wrote to self-heal the first time a session starts there.

One limit worth knowing: sessions running inside a Docker case no longer feed the Plan Usage chip, since the flag rides local spawns only. The chip is account-wide, so any local Claude session covers it, and threading the flag into the container launch is a follow-up.

Ships in the next release. Thanks for the diagnosis, it is what settled the design.