docs: reposition docs around coding agents#1009
Merged
Merged
Conversation
Refresh the documentation entry points so ccusage is presented as a multi-agent usage analyzer instead of a Claude Code-only tool. Update the home page, guide introduction, sidebar labels, report guides, configuration pages, and agent pages to prefer the unified ccusage <agent> command shape. Add an Amp guide so every supported non-Claude agent has an explicit docs entry point.
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughRebrand site and docs from Claude-specific to a unified multi-agent ccusage CLI, add an Amp guide and All-Reports page, standardize per-agent command examples and environment-variable/docs, reorganize VitePress sidebar and redirects, and update CLI report title and snapshots. ChangesDocumentation rebranding and multi-agent support
Sequence Diagram(s)No sequence diagrams generated. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
ccusage-guide | 79d26b0 | May 17 2026, 01:16 AM |
@ccusage/amp
ccusage
@ccusage/codex
@ccusage/opencode
@ccusage/pi
commit: |
ccusage performance comparisonThis compares the PR build against the base branch build on the same CI runner. Committed fixture performanceCommitted small fixtures for stable PR-to-PR feedback and explicit Claude/Codex command coverage. Fixtures: Claude
Large real-world-shaped fixture performanceGenerated fixtures shaped from aggregate local log statistics: thousands of JSONL files, many small sessions, and a long tail of larger sessions. No real prompts, paths, or outputs are stored in the fixtures. Fixtures: Claude
Package size
Lower medians and smaller packed package sizes are better. CI runner noise still applies; use same-run ratios as directional PR feedback, not release guarantees. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/guide/weekly-reports.md (1)
11-12: 💤 Low valueConsider adding examples for other agents.
The daily reports page shows examples for
codex,opencode,amp, andpiagents, but the weekly reports only showclaudeandopencode. For consistency, consider adding the other agents if they support weekly reports.📝 Suggested addition
ccusage weekly ccusage claude weekly +ccusage codex weekly ccusage opencode weekly +ccusage amp weekly +ccusage pi weekly🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guide/weekly-reports.md` around lines 11 - 12, The weekly reports section currently only lists "claude" and "opencode" examples (lines showing "ccusage claude weekly" and "ccusage opencode weekly"); add matching weekly examples for the other agents shown on the daily page—specifically "codex", "amp", and "pi"—so the weekly docs mirror the daily examples; update the block in docs/guide/weekly-reports.md to include "ccusage codex weekly", "ccusage amp weekly", and "ccusage pi weekly" alongside the existing lines.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guide/amp/index.md`:
- Around line 45-51: The fenced code block containing the directory tree
starting with "~/.local/share/amp/" is missing a language specifier and triggers
markdownlint MD040; update the opening fence from ``` to ```text to silence the
warning (i.e., add "text" after the backticks) and, if desired, replace the
incorrect "<!-- eslint-skip -->" comment with a markdownlint directive (e.g.
"<!-- markdownlint-disable MD040 -->") or remove it so the lint state is
correct.
---
Nitpick comments:
In `@docs/guide/weekly-reports.md`:
- Around line 11-12: The weekly reports section currently only lists "claude"
and "opencode" examples (lines showing "ccusage claude weekly" and "ccusage
opencode weekly"); add matching weekly examples for the other agents shown on
the daily page—specifically "codex", "amp", and "pi"—so the weekly docs mirror
the daily examples; update the block in docs/guide/weekly-reports.md to include
"ccusage codex weekly", "ccusage amp weekly", and "ccusage pi weekly" alongside
the existing lines.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 3ab673c4-e7d2-4937-ac08-61c78488a572
📒 Files selected for processing (15)
docs/.vitepress/config.tsdocs/guide/amp/index.mddocs/guide/configuration.mddocs/guide/daily-reports.mddocs/guide/directory-detection.mddocs/guide/environment-variables.mddocs/guide/getting-started.mddocs/guide/index.mddocs/guide/installation.mddocs/guide/monthly-reports.mddocs/guide/opencode/index.mddocs/guide/pi/index.mddocs/guide/session-reports.mddocs/guide/weekly-reports.mddocs/index.md
Stop presenting the old per-agent packages and ccusage-* aliases as documentation entry points. The docs now show only the unified ccusage <agent> <report> command surface for Codex, OpenCode, Amp, and pi-agent reports.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/guide/amp/index.md (1)
29-35:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd a language to the directory tree code fence.
This fence still triggers markdownlint MD040 because it has no language identifier.
Suggested fix
-<!-- eslint-skip --> - -``` +```text ~/.local/share/amp/ └── threads/ └── **/*.json🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guide/amp/index.md` around lines 29 - 35, The markdown code fence displaying the directory tree is missing a language identifier and triggers MD040; update the fenced block (the triple-backtick block that contains "~/.local/share/amp/" and the threads tree) to include a language tag such as "text" (i.e., change ``` to ```text) so markdownlint no longer flags it and the tree is treated as plain text.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guide/pi/index.md`:
- Around line 12-18: Make the guidance consistent: either relax the top line
("Recommended - always include `@latest`") or update the alternative runner
examples to include `@latest`. Concretely, change the alternative commands shown
(the lines with "pnpm dlx ccusage pi --help" and "pnpx ccusage pi --help") to
include "`@latest`" (e.g., "pnpm dlx ccusage@latest pi --help" and "pnpx
ccusage@latest pi --help"), or alternatively reword the header to say that using
`@latest` is recommended but optional; update the corresponding examples to match
that wording.
---
Duplicate comments:
In `@docs/guide/amp/index.md`:
- Around line 29-35: The markdown code fence displaying the directory tree is
missing a language identifier and triggers MD040; update the fenced block (the
triple-backtick block that contains "~/.local/share/amp/" and the threads tree)
to include a language tag such as "text" (i.e., change ``` to ```text) so
markdownlint no longer flags it and the tree is treated as plain text.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 96feff34-deab-4a01-b11f-54db3cd1fca9
📒 Files selected for processing (8)
docs/guide/amp/index.mddocs/guide/codex/daily.mddocs/guide/codex/index.mddocs/guide/codex/monthly.mddocs/guide/codex/session.mddocs/guide/index.mddocs/guide/opencode/index.mddocs/guide/pi/index.md
✅ Files skipped from review due to trivial changes (3)
- docs/guide/codex/monthly.md
- docs/guide/opencode/index.md
- docs/guide/codex/index.md
Replace the main report screenshot with the refreshed all-agent daily report. The updated image reflects the current multi-agent docs positioning and shows the unified all-agent output.
Replace the Codex daily screenshot with the current unified command output and add a separate Codex monthly screenshot. This keeps the Codex overview and monthly guide aligned with the current ccusage codex command surface.
Reword agent-focused docs so Codex, OpenCode, Amp, and pi-agent are presented as ccusage data sources rather than standalone command products. The sidebar, overview pages, and report pages now emphasise all-agent reports first and focused source views only when narrowing the same report shape.
Update visible documentation language from coding agent usage toward coding (agent) CLI usage so ccusage is described around the local CLI data it analyzes. Also update Wrangler to 4.91.0, the newest version allowed by the repository minimum release age policy, so Cloudflare Workers Builds uses a recent preview URL implementation.
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
Align remaining user-facing copy, README examples, CLI report titles, and output snapshots around coding (agent) CLI terminology. Keep internal agent identifiers and table columns where they still describe the source dimension.
Reorganize the VitePress sidebar so all-source usage is the default entry point, keep Claude Code, Codex, OpenCode, Amp, and pi-agent as peer data sources, and move Claude-specific Blocks and Statusline into their own feature section. Merge the Codex daily/monthly/session pages back into the Codex data source page and explain the ccusage name expansion from Claude Code usage to general coding CLI usage.
Document Bun as the recommended command runner, update the published Node.js minimum to 22, refresh Bun requirements to 1.3+, and keep compatibility package README examples aligned with bunx-first usage. Also clarify that the cc name maps to both Claude Code and Codex CLI usage.
Update the main ccusage package and repository README copy to describe coding (agent) CLI usage analysis instead of a Claude-only tool. Mark the agent-specific npm packages as compatibility wrappers and make their README examples prefer the unified ccusage command through bunx.
Remove general Deno examples and keep the recommended runtime path focused on bunx, pnpm dlx, and npx. Fold Claude Code custom paths and directory detection into the Claude data source page, redirect the old guide URLs, and remove direct Blocks/Statusline links from shared usage view pages.
Update report examples to use recent May 2026 date ranges across the unified docs and package READMEs. Refresh model examples to use gpt-5.5 for Codex, Claude Opus 4.1, and Claude Sonnet 4.5. Keep full JSON model IDs aligned with current Claude API snapshot names. Also adjust Codex pricing text so gpt-5.5 is described as resolving through LiteLLM pricing rather than mapping directly to an older canonical model.
…t-refresh # Conflicts: # apps/amp/package.json # apps/ccusage/src/commands/all.ts # apps/ccusage/test/cli-output.test.ts # apps/ccusage/test/snapshots/cli-output/all-agent-daily-table.txt # apps/codex/README.md # apps/codex/package.json # apps/opencode/README.md # apps/opencode/package.json # apps/pi/README.md # apps/pi/package.json # docs/guide/codex/daily.md # docs/guide/codex/index.md # docs/guide/codex/monthly.md # docs/guide/codex/session.md # docs/guide/opencode/index.md # docs/guide/pi/index.md # pnpm-lock.yaml
Update configuration docs after the adapter foundation merge so the documented merge order matches the generated JSON schema. The runtime still accepts legacy command keys for compatibility, but the schema exposes source namespace sections such as codex.commands.daily and opencode.commands.weekly as the documented path.
Document the Bun PATH auto-run behavior in Getting Started so users see why bunx remains the recommended command runner. Replace remaining Bun examples that used bunx ccusage@latest with bunx ccusage while keeping npx ccusage@latest examples for npx freshness. Also fix the Amp data-directory code fence language so the docs lint cleanly.
Clarify that package runners can initially start the published CLI under Node.js because the shebang targets Node.js, even when users invoke bunx. The runtime note now explains why ccusage checks for bun in PATH and re-runs the bundled Bun entrypoint for better warm runtime performance.
Owner
Author
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/guide/config-files.md (1)
358-361:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove duplicate "Claude Code" entry in Next Steps.
Lines 358 and 361 both link to
/guide/claude/with slightly different descriptions ("Claude Code data discovery" vs "Claude Code data paths and source-specific options"). This appears to be an accidental duplication.📝 Proposed fix to remove duplicate
- [Command-Line Options](/guide/cli-options) - All available CLI arguments - [Environment Variables](/guide/environment-variables) - System configuration - [Configuration Files](/guide/config-files) - Persistent settings -- [Claude Code](/guide/claude/) - Claude Code data discovery +- [Claude Code](/guide/claude/) - Claude Code data paths and source-specific options - [Cost Modes](/guide/cost-modes) - Understanding calculation modes -- [Claude Code](/guide/claude/) - Claude Code data paths and source-specific options🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guide/config-files.md` around lines 358 - 361, Two Next Steps entries both link to "/guide/claude/" (one labeled "Claude Code data discovery" and the other "Claude Code data paths and source-specific options"); remove the duplicate by keeping the most accurate/complete entry and deleting the other so the Next Steps list contains a single "/guide/claude/" link. Update whichever element (the list item string referring to "/guide/claude/") in the docs/guide/config-files.md Next Steps section—remove the redundant link text and its list item.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guide/monthly-reports.md`:
- Around line 62-64: The heading "Show usage from 2026" and the example command
"ccusage monthly --since 20260101 --until 20260531" are inconsistent with the
prior example; fix by making the heading match the command's date-range (e.g.,
change the heading to "Show usage from Jan–May 2026" or otherwise adjust the
command's --since/--until to reflect the intended year), ensuring the heading
text and the "ccusage monthly --since ... --until ..." example are aligned.
In `@docs/guide/statusline.md`:
- Around line 111-113: The fenced sample outputs in statusline.md (the three
code blocks showing Opus status lines) are missing language identifiers; update
each triple-backtick fence that contains the sample outputs (the blocks starting
with "🤖 Opus 4.1 | ...") to use ```text so they pass MD040 and follow docs
markdown linting conventions, and ensure any docs commands or metadata follow
the ccusage-docs guidelines for docs/**/*.{md,mdx}; update the blocks referenced
around the sample lines (the sequences matching the three shown outputs)
accordingly.
In `@docs/guide/weekly-reports.md`:
- Around line 35-38: The "Understanding the Columns" section mentions an "Agent"
column but the example output table on the same page doesn't include it; either
add an "Agent" column header and sample values to the example table or
remove/qualify the "Agent" bullet in the list to indicate it is
optional/derived. Update the markdown near the "Understanding the Columns"
heading and the example table so both the list and the table headers (and any
sample row data) consistently include or omit "Agent", ensuring the "Agent"
terminology matches the existing table output.
- Around line 17-29: The ASCII table code fences in the weekly-reports.md
example use untagged triple-backticks; update those fences to include the
language tag "text" (e.g., replace ``` with ```text) for the block that begins
with "┌────────────────┬──────────────────────┬..." and the matching closing
fence, and do the same for the other identical table block(s) referenced (also
around the region noted as lines 92-102) so the markdown linter MD040 is
satisfied.
---
Outside diff comments:
In `@docs/guide/config-files.md`:
- Around line 358-361: Two Next Steps entries both link to "/guide/claude/" (one
labeled "Claude Code data discovery" and the other "Claude Code data paths and
source-specific options"); remove the duplicate by keeping the most
accurate/complete entry and deleting the other so the Next Steps list contains a
single "/guide/claude/" link. Update whichever element (the list item string
referring to "/guide/claude/") in the docs/guide/config-files.md Next Steps
section—remove the redundant link text and its list item.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: c19c0d2e-47eb-444b-99a2-9dfc68672206
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (39)
apps/ccusage/README.mdapps/ccusage/package.jsonapps/ccusage/src/commands/all.tsapps/ccusage/test/cli-output.test.tsapps/ccusage/test/snapshots/cli-output/all-agent-daily-table.txtapps/ccusage/test/snapshots/cli-output/daily-table.txtapps/ccusage/test/snapshots/cli-output/session-table.txtdocs/.vitepress/config.tsdocs/guide/all-reports.mddocs/guide/amp/index.mddocs/guide/blocks-reports.mddocs/guide/claude/index.mddocs/guide/cli-options.mddocs/guide/codex/daily.mddocs/guide/codex/index.mddocs/guide/codex/monthly.mddocs/guide/codex/session.mddocs/guide/config-files.mddocs/guide/configuration.mddocs/guide/cost-modes.mddocs/guide/custom-paths.mddocs/guide/daily-reports.mddocs/guide/directory-detection.mddocs/guide/environment-variables.mddocs/guide/getting-started.mddocs/guide/index.mddocs/guide/installation.mddocs/guide/json-output.mddocs/guide/live-monitoring.mddocs/guide/monthly-reports.mddocs/guide/opencode/index.mddocs/guide/pi/index.mddocs/guide/session-reports.mddocs/guide/statusline.mddocs/guide/weekly-reports.mddocs/index.mddocs/package.jsondocs/wrangler.jsoncpnpm-workspace.yaml
💤 Files with no reviewable changes (5)
- docs/guide/custom-paths.md
- docs/guide/codex/session.md
- docs/guide/codex/daily.md
- docs/guide/directory-detection.md
- docs/guide/codex/monthly.md
✅ Files skipped from review due to trivial changes (14)
- apps/ccusage/test/snapshots/cli-output/session-table.txt
- docs/package.json
- apps/ccusage/package.json
- docs/guide/live-monitoring.md
- docs/guide/cli-options.md
- apps/ccusage/test/snapshots/cli-output/all-agent-daily-table.txt
- apps/ccusage/src/commands/all.ts
- docs/guide/json-output.md
- docs/guide/environment-variables.md
- pnpm-workspace.yaml
- docs/index.md
- docs/guide/pi/index.md
- docs/guide/amp/index.md
- docs/guide/installation.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/wrangler.jsonc
Fix the inconsistent monthly date-range label, add text language tags to statusline and weekly sample-output fences, and clarify that the weekly Agent column only appears in unified all-source reports. The remaining config-files Claude link comment is stale against the current file and will be answered on the PR.
Owner
Author
|
@coderabbitai addressed the latest review pass in 79d26b0.
Please review the latest commit. |
Owner
Author
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: Length of output: 780 🏁 Script executed: Length of output: 1514 🏁 Script executed: Length of output: 267 🏁 Script executed: Length of output: 2264
Everything looks good. The PR is in great shape — the documentation refresh is well-structured and the multi-agent/unified CLI positioning is clean throughout. [approve] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refreshes the docs so ccusage is presented as a coding-agent usage analyzer rather than a Claude Code-only tool. The home page, guide introduction, report guides, configuration pages, and agent pages now prefer the unified `ccusage ` command shape, with Claude-specific features labelled explicitly.\n\nAdds a new Amp guide so every supported non-Claude agent has a docs entry point.\n\nValidation run locally:\n- `pnpm run format`\n- `pnpm typecheck`\n- `pnpm run test`\n- `pnpm --filter docs build`
Summary by cubic
Repositions the docs and CLI around coding (agent) CLI usage with all‑source views as the default and a consistent
ccusage <source> <report>flow. Updates copy, titles, examples, runtime guidance, and infra for a clearer multi‑agent experience, plus small review polish.New Features
wranglerupdated to4.91.0.Migration
ccusage <source> <report>; per‑agent packages andccusage-*aliases are no longer presented.--allis accepted but optional.Written for commit 79d26b0. Summary will update on new commits. Review in cubic
Summary by CodeRabbit