Utilities¶
Small tools that round out everyday use: the status line, activity and subscription reporting, Claude Code memory-file management, database inspection, and the Claude Code context knobs.
Status line¶
Claude Code: command-backed status bar¶

The Claude Code status line: model and context bar, five-hour and seven-day rate-limit windows, effort — with the branch and PR link line below
tclaude setup offers to install tclaude's status bar as Claude Code's
command-backed statusline (statusLine: {type: command, command: "tclaude
status-bar"} in ~/.claude/settings.json). Requires Claude Code >= 2.1.80,
which delivers rate limits in the statusline input so no extra API polling is
needed.
Line one shows the model label with its effective context-window marker
(re-based onto a pinned --auto-compact-window when
set, matching the dashboard meter), a context bar with a compaction-buffer
indicator, 5-hour and 7-day rate-limit bars with reset timers, a 7-day Sonnet
bar when it is above zero, and session cost on API plans. Line two shows the
git branch and working directory plus a repo/compare/PR link. Git data is
cached per repo with a short TTL, so the bar stays cheap.
Codex CLI: curated built-in items¶
Codex CLI has no command-backed status line, so tclaude cannot install its own
renderer there. Instead, tclaude setup (or tclaude setup --harness codex)
curates Codex's built-in footer items in ~/.codex/config.toml under
[tui] status_line: model with reasoning level, context remaining, git
branch, five-hour limit, weekly limit, and thread id.
The managed value is guarded by a # tclaude:managed-status-line marker
comment. Delete the marker to own the setting yourself — tclaude never
clobbers a user-managed value.
Codex context and token telemetry for tclaude's own meters comes from Codex's
durable rollout token_count events rather than from the footer, so the
dashboard's Codex context figures work whether or not the curated items are
installed.
pi: extension footer segment¶
pi has no command-backed status line either. tclaude's per-launch pi extension
adds a tclaude segment to pi's own footer with ctx.ui.setStatus. When the
agent pins an --auto-compact-window, the segment shows
the context measured against that window, as the dashboard meter does (pi's
footer measures the model's full window); it says no live status when the
extension cannot reach tclaude.
OpenCode shows only its own TUI status, and Copilot CLI and Gemini CLI have no tclaude status line; see the capability matrix.
tclaude stats¶
Claude Code activity stats, read from Claude Code's own
~/.claude/stats-cache.json: sessions, messages, tokens, daily activity, and
per-model usage/cost.
tclaude stats # last 7 days
tclaude stats -d 30 # last 30 days
tclaude stats -t # token detail
tclaude stats -j # raw cache as JSON
The data source is Claude Code's; Codex, OpenCode, Copilot, Gemini, and pi activity is not included here — the dashboard is where cross-harness usage lives.
tclaude usage¶
Reads daemon-cached subscription quota windows for all observed providers, including resets, forecasts, and freshness metadata. It makes no provider API requests.
See Querying usage and costs for access permissions, response fields, and how to interpret missing or stale readings.
tclaude memory-files¶
Inspect and clean Claude Code's per-project auto-memory markdown files under
~/.claude/projects/<encoded-dir>/memory/. Aliases: mem-files, memory.
tclaude memory-files ls # list memory files for this project
tclaude memory-files cat # print them, MEMORY.md first
tclaude memory-files clean # remove them
tclaude memory-files prune-index # drop dangling MEMORY.md index entries
By default the scope is the project and its git worktree siblings, because
they share an encoded-name prefix and can cross-poison one another's memory.
--prefix switches to plain encoded-name-prefix matching; --no-siblings
restricts to the exact directory.
Context: tclaude launches Claude Code sessions with auto memory off by
default (CLAUDE_CODE_DISABLE_AUTO_MEMORY=1), precisely because agents
sharing a checkout would otherwise write into one shared per-project store.
Re-enable per launch with --auto-memory. See
Harnesses.
Claude Code peer messaging¶
Claude Code has its own cross-session messaging mesh: each session binds an
inbox socket, discovers your other sessions with the ListAgents tool, and
delivers plain-text messages to them with SendMessage. Where the feature is
present it is on with nothing to enable.
tclaude turns it off by default. That mesh is a second, unmanaged
coordination channel running alongside the one tclaude owns — none of the
group membership, permission slugs, audit trail, or dashboard visibility that
tclaude agent send provides applies to it, and two agents you deliberately
put in different groups can still find each other and talk with nothing
recording that it happened.
Every Claude Code session tclaude launches therefore carries these three
settings, delivered in the same per-session --settings payload as the
sandbox block, so tclaude never edits your own settings.json:
{
"crossSessionInbound": "refuse",
"isolatePeerMachines": true,
"permissions": { "deny": ["ListAgents"] }
}
Which yields:
| Direction | Effect |
|---|---|
| Inbound from peer sessions | Hard off — messages are dropped, never delivered |
| Peer discovery | Off — ListAgents is denied, so peers cannot be listed |
| Sends beyond this machine | Require your explicit approval |
| In-harness subagents | Unaffected — spawn, message, and reply all work |
That last row is the constraint the design is built around. Claude Code's own
docs note that denying SendMessage "also removes messaging to subagents and
agent-team teammates, since the same tool serves both", and tclaude relies on
in-harness subagents (the cold-review fallback, for one). So the deny names
ListAgents instead: messaging a subagent addresses it by the agent ID the
Agent tool returned, never via a peer lookup, so it keeps working.
The consequence is a deliberate asymmetry — inbound is hard off, outbound is
only discovery-off. It matters less than it reads, because the default is
fleet-wide: when every tclaude-launched agent refuses inbound, no tclaude
agent can be reached by another whatever a sender attempts. What remains is
a send toward a non-tclaude session you started by hand, and
isolatePeerMachines covers that whenever it would leave the machine.
Opt back in per launch, per spawn, or per profile:
Opting in injects nothing at all, leaving Claude Code's own defaults and
your settings.json in charge — rather than forcing the feature on. That is
deliberate: with no crossSessionInbound set, Claude Code decides per message
from the two sessions' permission modes, holding a message for approval when
the sender bypasses permission prompts and the receiver does not. That default
is more careful than a blunt accept, so an operator opting back in gets it.
Claude-Code-only; asking for it on any other harness is an error rather than a silent no-op. The posture is recorded per session, so a resume, clone, or reincarnation reproduces what the agent actually launched with.
tclaude db¶
Inspects tclaude's own SQLite database at ~/.tclaude/data/db.sqlite. (A
pre-split ~/.tclaude/db.sqlite is auto-relocated into data/; the command's
help text still prints the legacy path, but the data/ path is the real one.)
tclaude db schema # canonical CREATE statements
tclaude db schema --json # structured per-table columns and FKs
tclaude db schema --relations # identity audit: conv-id vs agent-id keying
The command operates on the live database and migrates it to the current schema version first.
tclaude paf¶
Verifies, describes and renders Portable Agent Format files and legacy agent bundles, locally and read-only. See Reading a PAF.
tclaude paf validate reviewer.paf
tclaude paf inspect reviewer.paf
tclaude paf render reviewer.paf --out reviewer.html
Startup-context trimming¶
Claude Code loads a fixed body of startup context into every session —
bundled skills, tool schemas, system-prompt blocks — sized for a
general-purpose assistant. A worker agent spawned for one narrow job has to
read past all of it. --context-features (on tclaude session new and
tclaude agent spawn, plus spawn profiles and the dashboard spawn dialog)
lets you choose per agent what loads.
Every feature in the catalog is in one of three states: default (tclaude
injects nothing; Claude Code and your settings.json decide), trim
(removed from this agent's startup context), or keep (stays, even if a
profile trimmed it). Nothing is trimmed unless you ask.
# A bare feature name means "trim"
tclaude agent spawn crew --name lean-worker \
--context-features bundled-skills,workflows,artifact
# Keep one thing a lean profile trimmed
tclaude agent spawn crew --profile lean --name needs-artifacts \
--context-features artifact=on
# List the catalog, with what each trim costs
tclaude session new --help-context-features
Resolution follows the usual stack — explicit request, then the group's default profile, then the global default profile — except the tiers do not merge: the most specific tier that says anything wins entirely, so one profile always tells the whole story of what an agent loads.
Claude Code only; the other harnesses expose no equivalent switches, and asking for a trim there is an error rather than a silent no-op.
Auto-compact window¶
--auto-compact-window (Claude Code and pi) pins the context capacity that
Claude Code's auto-compaction reasons from, via
CLAUDE_CODE_AUTO_COMPACT_WINDOW. It accepts 450000, 450k, or 0.5M;
unset uses the model's own threshold. For pi, tclaude's extension compacts
between runs once the context reaches the pinned window.
The point is long-lived agents on large-window models: pin the window below a 1M model's real capacity and the agent compacts while it is still sharp, instead of degrading toward the end of an enormous window. Claude Code caps the value at the model's actual window, and tclaude re-bases every context meter, bar, and percentage — dashboard and status line alike — onto whichever is smaller, so what you see always matches what compaction will act on.
Set it per launch, per spawn profile, or in the dashboard spawn dialog; like other posture flags it is replayed on resume, reincarnate, and clone.