Add CLI cards view

[DonnieFi]

Summary

• Add codexbar cards, a one-shot terminal usage snapshot with a responsive provider card grid.
• Add codexbar cards --brief, a compact Provider / Usage / Reset table with source/plan detail and enhanced terminal colors.
• Reuse the existing codexbar usage fetch pipeline, summarize provider failures in a footer, and document the new command.

Test plan

• swift test --filter 'CLICards|CLITerminalCapabilities' (19 tests)
• swift build --product CodexBarCLI -c release
• git diff --check
• make check reaches SwiftFormat cleanly, then fails on this Linux host when SwiftLint/SourceKit cannot load libsourcekitdInProc.so.

Terminal proof (redacted)

codexbar cards --no-color on Linux (head 7566af4):

╭─────────────────────────────────────╮  ╭─────────────────────────────────────╮
│ Codex [oauth]             PLAN Free │  │ Cursor [web]        PLAN Cursor Pro │
│ @ user@example.com                  │  │ @ user@example.com                  │
│ ─────────────────────────────────── │  │ ─────────────────────────────────── │
│ Limit Reset Credits:    0 available │  │ Total                      43% left │
│                                     │  │ [ ━━━━━━━━━━━━━                   ] │
│ Session                    50% left │  │ Reset in 20d 13h                    │
│ [ ━━━━━━━━━━━━━━━                 ] │  │                                     │
│ Reset in 19d 31m                    │  │ Auto                       49% left │
│                                     │  │ [ ━━━━━━━━━━━━━━━                 ] │
│                                     │  │ Reset in 20d 13h                    │
╰─────────────────────────────────────╯  ╰─────────────────────────────────────╯

codexbar cards --brief --no-color on Linux (head 7566af4):

codexbar • AI Usage & Limits                                2026-07-05 21:13 ADT
Next reset: Antigravity in 5h

┌───────────────────────────────────┬──────────────────────────────┬──────────┐
│ Provider                          │ Usage                        │    Reset │
├───────────────────────────────────┼──────────────────────────────┼──────────┤
│ Codex · oauth · Free              │ 50% ███████████░░░░░░░░░░░   │  19d 31m │
│ Cursor · web · Cursor Pro         │ 57% ████████████░░░░░░░░░░   │  20d 13h │
│ Antigravity · cli · Google Ai Pro │ 0% ░░░░░░░░░░░░░░░░░░░░░░    │       5h │
│ OpenRouter · api · Balance: $7.55 │ 100% ██████████████████████  │        — │
│ Grok · web · Supergrok            │ 18% ███░░░░░░░░░░░░░░░░░░░   │   4d 21h │
└───────────────────────────────────┴──────────────────────────────┴──────────┘

⚠ Warnings: OpenRouter approaching session limit

Notes

• Root screenshot artifacts and the release-owned changelog entry were removed from the branch after review feedback.
• Package.swift and Package.resolved are intentionally unchanged in the final PR surface.
• Enhanced rendering now defaults only on Kitty/Ghostty/WezTerm/truecolor-capable terminals, with CODEXBAR_CARDS_ENHANCED=1 as an explicit override.
• 7566af4 fixes zero-usage/zero-remaining bar rendering in standard brief and card grid paths.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 5, 2026, 8:20 PM ET / 00:20 UTC.

Summary
The branch adds a codexbar cards command with card-grid and brief-table renderers, shared usage-fetch plumbing, terminal capability detection, focused tests, and CLI docs.

Reproducibility: not applicable. as a bug reproduction: this is a feature PR. The contributor supplied redacted current-head terminal output for both card modes, and source/tests cover the prior renderer issue.

Review metrics: 2 noteworthy metrics.

• Diff Size: 13 files, +2568/-22. The feature spans command dispatch, rendering, shared usage output plumbing, terminal capability detection, tests, and docs.
• New CLI Surface: 1 command, 1 env override. Maintainers should explicitly accept both the cards command and CODEXBAR_CARDS_ENHANCED before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Wait for the pending Linux build and macOS test jobs to finish green.
• Get maintainer acceptance for the separate cards command and enhanced-mode environment override.

Risk before merge

• [P1] A maintainer still needs to accept the separate codexbar cards command and CODEXBAR_CARDS_ENHANCED environment override as supported CLI surface.
• [P1] Several required CI jobs were still queued or in progress at the latest check, so merge should wait for the normal check gate.

Maintainer options:

1. Decide the mitigation before merge
   Land this PR if a maintainer accepts the new CLI surface and the pending CI jobs finish green; otherwise narrow the card view into the maintainer-preferred CLI shape.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] The remaining action is maintainer product acceptance plus normal CI gating, not a concrete code repair for ClawSweeper to make.

Maintainer decision needed

• Question: Should CodexBar accept a separate codexbar cards command plus the CODEXBAR_CARDS_ENHANCED environment override as supported CLI surface?
• Rationale: The technical blockers from the previous review appear resolved, but adding a command and environment override is a user-facing product/API choice that automation should not approve by itself.
• Likely owner: steipete — steipete is the strongest current-history owner for CLI command/help/docs surface and the product-surface choice.
• Options:
  • Accept Separate Cards Command (recommended): Merge after pending CI finishes green, treating codexbar cards and the enhanced-mode override as intentional supported CLI surface.
  • Fold Into Existing Usage Command: Ask for the rendering mode to live under the existing codexbar usage surface instead of adding a new top-level command and override.
  • Defer The Feature: Close or pause the PR if the extra terminal UI surface is not worth carrying right now.

Security
Cleared: No concrete security or supply-chain concern was found; the net diff is limited to CLI rendering/command code, tests, and docs without dependency, workflow, release-script, or secret-handling changes.

Review details

Best possible solution:

Land this PR if a maintainer accepts the new CLI surface and the pending CI jobs finish green; otherwise narrow the card view into the maintainer-preferred CLI shape.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this is a feature PR. The contributor supplied redacted current-head terminal output for both card modes, and source/tests cover the prior renderer issue.

Is this the best way to solve the issue?

Yes for the technical path: the branch reuses the existing usage fetch pipeline and adds focused renderers, tests, and docs. Product acceptance of the separate command and env override remains maintainer-owned.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against b43a0ef645ab.

Label changes

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes redacted copied terminal output from the current head for both codexbar cards --no-color and codexbar cards --brief --no-color, which is sufficient proof for this CLI text-rendering change.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes redacted copied terminal output from the current head for both codexbar cards --no-color and codexbar cards --brief --no-color, which is sufficient proof for this CLI text-rendering change.
• remove rating: 🧂 unranked krab: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
• remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

• P2: This is a normal-priority CLI feature PR with focused tests and proof, but it still needs maintainer product acceptance and completed CI.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes redacted copied terminal output from the current head for both codexbar cards --no-color and codexbar cards --brief --no-color, which is sufficient proof for this CLI text-rendering change.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes redacted copied terminal output from the current head for both codexbar cards --no-color and codexbar cards --brief --no-color, which is sufficient proof for this CLI text-rendering change.

Evidence reviewed

What I checked:

• Repository policy read and applied: AGENTS.md was read fully; its CLI-focused validation, no live-provider probe guidance, release-owned changelog guidance, and provider data silo rule shaped the review. (AGENTS.md:25, b43a0ef645ab)
• Current main does not already provide the feature: Current main dispatches usage, cost, serve, config, cache, and diagnose commands, with no cards command descriptor or switch case. (Sources/CodexBarCLI/CLIEntry.swift:36, b43a0ef645ab)
• PR adds a new CLI command: The PR head adds a cards switch case and command descriptor, making this a new user-facing CLI command. (Sources/CodexBarCLI/CLIEntry.swift:37, 7566af4d9876)
• PR reuses the existing usage fetch path: runCards builds a UsageCommandContext with cardsLayout: true and calls fetchUsageOutputs, so the feature shares the existing provider/account/source fetch pipeline instead of adding a separate fetcher. (Sources/CodexBarCLI/CLICardsCommand.swift:153, 7566af4d9876)
• Prior zero-bar finding is fixed: cardUsedBar now permits zero filled cells, and the added tests cover standard brief 0%/100% rows plus exhausted card-grid bars. (Sources/CodexBarCLI/CLIRenderer.swift:208, 7566af4d9876)
• Renderer tests cover the repaired paths: The PR adds tests for standard and enhanced brief bars and empty remaining bars at exhaustion. (Tests/CodexBarTests/CLICardsRendererTests.swift:230, 7566af4d9876)

Likely related people:

• steipete: Peter Steinberger appears repeatedly in current-main history for CLI command dispatch, config/API-key commands, musl compatibility, usage output, renderer work, and CLI docs. (role: recent CLI product-surface contributor; confidence: high; commits: d8ce86980772, 8132f7c89378, 23a89fb02a08; files: Sources/CodexBarCLI/CLIEntry.swift, Sources/CodexBarCLI/CLIUsageCommand.swift, Sources/CodexBarCLI/CLIRenderer.swift)
• kmatsunami: Kentoku Matsunami recently changed CLI text and JSON usage output and docs in the same rendering and usage-command surface this PR extends. (role: recent CLI usage/rendering contributor; confidence: medium; commits: 5bfd1d1474bb; files: Sources/CodexBarCLI/CLIRenderer.swift, Sources/CodexBarCLI/CLIUsageCommand.swift, docs/cli.md)
• DonnieFi: Beyond authoring this PR, DonnieFi has prior current-main work touching Linux CLI provider behavior in CLIUsageCommand.swift. (role: recent CLI usage contributor; confidence: medium; commits: 780767953539; files: Sources/CodexBarCLI/CLIUsageCommand.swift, TestsLinux/CursorLinuxTests.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (4 earlier review cycles)

• reviewed 2026-07-05T23:08:56.785Z sha 6e046c1 :: found issues before merge. :: [P1] Preserve musl imports for the CLI target | [P2] Render used bars from the used percentage | [P2] Gate enhanced cards to capable terminals | [P3] Remove release-owned and generated artifacts
• reviewed 2026-07-05T23:23:15.516Z sha 1ddc002 :: needs real behavior proof before merge. :: [P2] Let standard brief bars show zero usage as empty
• reviewed 2026-07-05T23:28:39.927Z sha 1ddc002 :: needs real behavior proof before merge. :: [P2] Let standard brief bars show zero usage as empty
• reviewed 2026-07-05T23:34:22.853Z sha 70e28fe :: needs real behavior proof before merge. :: [P2] Let standard brief bars show zero usage as empty

[DonnieFi]

Addressed the ClawSweeper findings in 1ddc002:

• preserved musl compatibility by using canImport(Glibc) / canImport(Musl) / canImport(Darwin)
• fixed enhanced brief bars to fill from used percentage, with 0% and 100% coverage
• gated enhanced cards to truecolor-capable terminals unless explicitly opted in
• removed committed root screenshots
• removed the release-owned changelog and Package.swift changes from the net PR diff

Validation:

• swift test --filter 'CLICards|CLITerminalCapabilities'
• swift build --product CodexBarCLI -c release
• git diff --check
• make check still reaches SwiftFormat cleanly, then hits the local Linux SwiftLint/SourceKit load issue (libsourcekitdInProc.so).

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[DonnieFi]

@clawsweeper re-review — pushed 7566af4 with zero-bar fixes, expanded tests, and redacted terminal proof in the PR body.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.