Skip to content

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

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 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.

tclaude usage
tclaude usage --json     # structured multi-provider observations and forecasts

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:

tclaude session new --peer-messaging
tclaude agent spawn <group> --peer-messaging

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.