Repository navigation
Rewrite README (evidence-first template, Tier 1) - #47
Conversation
…failure modes Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe README now presents the project’s MVP status, operating model, setup, scope, tradeoffs, limitations, roadmap, and technology stack. A new question document requests clarification about project provenance and waveform documentation. ChangesProject documentation restructure
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
README.md (1)
96-102: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winSource or qualify the Tauri resource figures.
The
~5–10 MBbinary and30–80 MBmemory figures depend on build flags, operating system, and workload. Add measurement conditions or replace them with qualitative wording. An evidence-first README should not present unqualified ranges as stable project facts.🤖 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 `@README.md` around lines 96 - 102, Update the Tauri comparison paragraph to remove or qualify the unsubstantiated “~5–10 MB” binary and “30–80 MB” memory figures. If retaining them, add their measurement conditions and source; otherwise replace them with qualitative wording while preserving the surrounding resource-usage comparison.
🤖 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 `@README.md`:
- Around line 61-67: Update the README testing documentation to keep cargo,
pnpm, and Playwright fixture tests under the “no real library needed” section,
then move ./scripts/real-library-smoke.sh to a separate optional real-library
smoke section. Document that the script requires an explicit master.db input
path or a user-created copy, rather than implying the default path is
automatically safe or fixture-based.
- Around line 44-50: Update the README description of the MCP server and local
execution around the Rust tool service to name Claude Code as the authenticated
subscription boundary, explain that external MCP hosts route tool results
through Claude Code, and state that in-app chat sends conversation history and
tool results to Anthropic via the configured API key. Clarify that MCP library
tool output leaves the machine while distinguishing this traffic from telemetry,
and remove the ambiguous “your existing subscription” wording.
---
Nitpick comments:
In `@README.md`:
- Around line 96-102: Update the Tauri comparison paragraph to remove or qualify
the unsubstantiated “~5–10 MB” binary and “30–80 MB” memory figures. If
retaining them, add their measurement conditions and source; otherwise replace
them with qualitative wording while preserving the surrounding resource-usage
comparison.
🪄 Autofix
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 Plus
Run ID: 389c9489-b0e8-412e-893f-6639106a9a7b
📒 Files selected for processing (2)
README-QUESTIONS.mdREADME.md
| - The same Rust tool service backs three surfaces at once: the in-app | ||
| Claude chat panel, an MCP server (`decks mcp` / `decks mcp-http`) usable | ||
| from any MCP host on your existing subscription, and a `decks tools call` | ||
| CLI. | ||
| - Everything runs on your machine. No telemetry; enrichment APIs | ||
| (MusicBrainz, opt-in Discogs) only fire if enabled, through a local | ||
| cache. The Anthropic key lives in the OS keychain. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Repo files (top-level):\n'
git ls-files | sed -n '1,120p'
printf '\nREADME around lines 1-90:\n'
if [ -f README.md ]; then
cat -n README.md | sed -n '1,90p'
else
fd -a '^README\.md$' . | while read -r f; do echo "===== $f ====="; cat -n "$f" | sed -n '1,90p'; done
fi
printf '\nSearch for Claude/MCP/Anthropic/network/telemetry terms:\n'
rg -n -i 'Claude|anthropic|telemetry|network|subscription|MCP|mcp|MusicBrainz|Discogs|keychain|api' README.md . --glob '!node_modules' --glob '!dist' --glob '!build' | sed -n '1,240p'Repository: cole-hackman/decks
Length of output: 42575
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Relevant source excerpts:\n'
for f in \
apps/desktop/src-tauri/src/claude_agent.rs \
apps/desktop/src-tauri/src/lib.rs \
crates/agent-tools/src/mcp.rs \
apps/desktop/src/agent/useAgent.ts \
apps/desktop/src-tauri/capabilities/default.json
do
if [ -f "$f" ]; then
echo "===== $f ====="
wc -l "$f"
if [ "$f" = "README.md" ]; then
cat -n "$f" | sed -n '40,54p;116,125p'
elif [ "$f" = "apps/desktop/src-tauri/capabilities/default.json" ]; then
cat -n "$f" | sed -n '1,220p'
else
rg -n -C 4 'claude|Claude|anthropic|ClaudeCode|get_claude_code_status|mcp|http|MCP|library|staged|tool' "$f" | sed -n '1,260p'
fi
fi
doneRepository: cole-hackman/decks
Length of output: 37798
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Antropics SDK usage:\n'
rg -n -C 3 'Anthropic|`@anthropic`|apiKey|client|messages\.stream|stream_claude_code_chat|getApiKey' apps/desktop/src apps/desktop/src-tauri/src crates/agent-tools/src/mcp.rs README.md docs/MCP.md 2>/dev/null | sed -n '1,260p'
printf '\nRelevant docs around Claude keys/subscription/network:\n'
for f in README.md docs/MCP.md docs/STATUS.md docs/UI_AUDIT.md CLAUDE.md
do
if [ -f "$f" ]; then
echo "===== $f ====="
rg -n -C 4 'Claude|Anthropic|api key|subscription|network|API traffic|MCP|telemetry|local|keychain' "$f" | sed -n '1,220p'
fi
done
printf '\nWeb search for Claude Code MCP network behavior and Anthropic API billing:\n'
web_search "Claude Code MCP server sends tool output to Anthropic API billing Anthropic key Claude code external host"Repository: cole-hackman/decks
Length of output: 40396
🌐 Web query:
Claude Code MCP tool results sent to Anthropic API billing Anthropic API key Claude Code MCP server tool_output
💡 Result:
When using Claude Code with Model Context Protocol (MCP) servers, tool usage is integrated into your standard Anthropic API billing [1][2]. There is no separate "MCP billing" category; instead, the interaction consumes tokens as part of the normal request-response lifecycle [1][3]. How billing works for Claude Code MCP usage: 1. Token Consumption: You are billed for the tokens consumed by your API requests, which include the tool definitions, tool calls (tool_use blocks), and tool results (tool_result blocks) sent to and from the model [1][4]. 2. Context Window Impact: Because MCP tool definitions (names, descriptions, and schemas) are included in the prompt's tools parameter, they consume context window tokens [1][4]. Loading a large number of MCP tools can increase your token usage significantly [5][6]. 3. Automated Reasoning: Invoking an MCP tool as part of an automated reasoning chain initiated by your prompt counts toward your total token usage for that request, but it does not count as a separate, new prompt or turn against rate limits [3]. 4. Cost Tracking Caveats: - Built-in reporting tools (like /context in Claude Code) may report inflated token usage estimates [7][6]. This often occurs because the tool calculates costs by summing individual tool definitions separately, which incorrectly accounts for shared system instructions multiple times [7][6]. - Client-side estimates (e.g., total_cost_usd or /cost) are approximations for budgeting [2][8]. For authoritative billing, always refer to the Usage page in the Claude Console or your cloud provider's billing dashboard [2][8]. 5. Efficiency Tips: - To reduce costs, use --strict-mcp-config or pin your MCP server configurations to keep the tool surface constant across turns [4]. Changing the tool definitions mid-session can break the cache and trigger expensive "cold" rebuilds [4]. - Large toolsets can be managed by only loading the tools necessary for the current task [5]. In summary, MCP tool results are sent back to the Anthropic API as part of the ongoing conversation history, and you are billed based on the total token usage—input and output—of these interactions [1][9].
Citations:
- 1: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
- 2: https://code.claude.com/docs/en/costs.md
- 3: Clarification on Claude Code Pro Rate Limits and MCP Usage anthropics/claude-code#2739
- 4: https://dev.to/sumedhbala/claude-code-costs-act-i-how-the-billing-actually-works-25kn
- 5: https://www.anthropic.com/engineering/code-execution-with-mcp
- 6: https://www.async-let.com/posts/claude-code-mcp-token-reporting/
- 7: Bug: /context command over-reports MCP server token usage by ~3x anthropics/claude-code#16466
- 8: https://code.claude.com/docs/en/agent-sdk/cost-tracking
- 9: https://medium.com/@richardhightower/anthropics-claude-and-mcp-a-deep-dive-into-content-based-tool-integration-dcf18cba82f0
🌐 Web query:
site:docs.anthropic.com Claude Code MCP tool results sent to Anthropic API billing
💡 Result:
Claude Code and other MCP-enabled applications do not have a separate billing category specifically for "MCP tool results." Instead, usage related to MCP tools is billed through standard Anthropic API token consumption and, where applicable, specific server-side tool costs [1]. How MCP tool usage impacts your billing: 1. Token Consumption: Using MCP tools increases the number of tokens in your API requests and responses [1]. This includes: - Tool Definitions: The tool names, descriptions, and schemas in your tools parameter consume tokens [1]. - Tool Interaction: The tool_use and tool_result content blocks sent to and from the API are counted as input and output tokens [1]. 2. Standard API Pricing: These tokens are billed at the standard rate for the Claude model you are using, just like any other API request [1]. 3. Server-Side Tool Costs: While MCP tools (which are generally client-side integrations) are billed via token volume [1], certain built-in server-side tools (like specific web search or code execution tools when used outside of free tiers) may incur additional usage-based charges that appear on your bill [2][3][1]. 4. Claude Code Specifics: If you are using Claude Code, the session usage reported in the tool is an estimate based on list prices and does not necessarily match your official bill in the Claude Console [4]. For authoritative billing information, you should always consult the Usage page in the Claude Console [4]. In summary, MCP tool results themselves do not have a unique, extra charge; they are simply part of the overall token usage generated by the conversation context [1].
Citations:
- 1: https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview
- 2: https://docs.anthropic.com/en/docs/about-claude/pricing
- 3: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/code-execution-tool
- 4: https://docs.anthropic.com/en/docs/claude-code/costs
Document the MCP network and billing boundary.
decks mcp runs locally, but external MCP hosts call tool results through Claude Code under the authenticated Claude subscription, while the in-app chat sends conversation history and tool results via the Anthropic API to the configured API key. Clarify that MCP library tool output leaves the machine, distinguish this traffic from telemetry, and avoid saying Claude access comes from “your existing subscription” without naming Claude Code.
🤖 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 `@README.md` around lines 44 - 50, Update the README description of the MCP
server and local execution around the Rust tool service to name Claude Code as
the authenticated subscription boundary, explain that external MCP hosts route
tool results through Claude Code, and state that in-app chat sends conversation
history and tool results to Anthropic via the configured API key. Clarify that
MCP library tool output leaves the machine while distinguishing this traffic
from telemetry, and remove the ambiguous “your existing subscription” wording.
| Tests run against synthetic fixture libraries in `fixtures/` — no real | ||
| library needed: | ||
|
|
||
| cargo test --workspace | ||
| pnpm test && pnpm typecheck && pnpm lint | ||
| pnpm e2e # Playwright | ||
| ./scripts/real-library-smoke.sh # data-layer smoke vs a real master.db copy |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Separate fixture tests from the real-library smoke test.
The heading says no real library is needed, but line 67 invokes a real master.db. scripts/real-library-smoke.sh also defaults to ~/Library/Pioneer/rekordbox/master.db and does not create a copy. Move the smoke command to an optional real-library section and document the explicit input path or copy.
🤖 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 `@README.md` around lines 61 - 67, Update the README testing documentation to
keep cargo, pnpm, and Playwright fixture tests under the “no real library
needed” section, then move ./scripts/real-library-smoke.sh to a separate
optional real-library smoke section. Document that the script requires an
explicit master.db input path or a user-created copy, rather than implying the
default path is automatically safe or fixture-based.
Rewrites the README against the Tier 1 template, per the promotion decision. No traction line — the honest status line (MVP, pre-v0.1.0, real-library validation outstanding) sits where traction would.
Tradeoffs are lifted from your own ADR log, which made this the easiest repo of the seven to write honestly: the staged-changes/XML-default vs WriteGuard Sync story (ADR-0010) and Tauri-over-Electron with its real numbers (ADR-0001). The ADR-0009 agent-shipped-broken-code incident is stated plainly as a failure-mode bullet — it's the most distinctive engineering-judgment content in the repo; say the word if you'd rather not air it.
Verified while writing: CI runs the Rust suite on macOS + Windows plus frontend checks; Playwright e2e and the real-library smoke are local-only and Linux is not in the matrix (stated as a limitation and next-step). Old README's structure and claims were current and accurate — this is a restructure, not a correction pass.
Needs Cole: README-QUESTIONS.md — problem provenance line, and whether any surface still shows the ADR-0008 synthetic waveform so the README doesn't overclaim.
🤖 Generated with Claude Code
Summary by CodeRabbit