rtk-ai / rtk-ai/rtk

feat: rtk context — Show Claude Code context token budget

Open
#486 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

area:cli effort-medium enhancement help wanted priority:medium
Dominant language
Rust
Stars
81.1k
Forks
5.1k
Avg merge
4d 21h
Merged PRs (30d)
35

Description

Use case

rtk context gives a clear picture of how many tokens my Claude Code setup costs per message, so I can decide if I need to slim down my CLAUDE.md or archive skills.

Scope MVP (v1)

Single command, zero flags. Scans and displays:

Component Source Method
CLAUDE.md (global) ~/.claude/CLAUDE.md Read file, estimate_tokens()
CLAUDE.md (project) ./CLAUDE.md Read file, estimate_tokens()
@imports detected Lines @file.md in CLAUDE.md List without resolving, show "not resolved (v1)"
MEMORY.md ~/.claude/projects/<encoded-cwd>/memory/MEMORY.md + global Read file, estimate_tokens()
Skills ~/.claude/skills/*/SKILL.md Read each SKILL.md, estimate_tokens() on real content
Commands ~/.claude/commands/**/*.md (recursive) Read each file, estimate_tokens()
Rules .claude/rules/*.md (project) Read each file, estimate_tokens()
MCP servers ~/.claude/settings.jsonmcpServers keys Count servers (not tools)

Target output

RTK Context Budget
--------------------------------------
Component                Tokens   Note
--------------------------------------
CLAUDE.md (global)        1,200
CLAUDE.md (project)         480
  @imports detected:
    @RTK.md                        not resolved (v1)
    @TONE.md                       not resolved (v1)
MEMORY.md (global)            0   not found
MEMORY.md (project)         187
Skills (47 loaded)        4,200
Commands (53 loaded)      2,150
Rules (1 file)              890
MCP servers (0)               0
--------------------------------------
TOTAL MEASURABLE          9,107
--------------------------------------
Note: System prompt + built-in tools add ~15K (not measurable by RTK)

Files to create/modify

File Action
src/context_cmd.rs Create (~300 lines)
src/main.rs Add mod context_cmd, Commands::Context, routing
scripts/test-all.sh Add smoke test assertion

Reuse existing

  • tracking::estimate_tokens() (pub, src/tracking.rs)
  • Table pattern from gain.rs (colored, TTY-aware, styled())
  • dirs::home_dir() to locate ~/.claude/
  • discover::provider::ClaudeProvider::encode_project_path() to find the project folder

Error handling

  • ~/.claude/ absent → "Claude Code not detected"
  • Missing file → skip, display 0 + "not found"
  • settings.json absent/malformed → display "unknown"

Tests

  • Inline #[cfg(test)] with tempdir
  • Test detect_imports() on @file.md patterns
  • Test missing component → 0 tokens
  • Snapshot test on output format

Verification

cargo fmt --all && cargo clippy --all-targets && cargo test
./target/debug/rtk context   # on real setup
rtk --help | grep context
hyperfine 'rtk context'      # target <100ms

Out of scope (v2, defer)

  • --format json
  • --project scope
  • Recursive @import resolution
  • --detailed per-file breakdown

Acceptance criteria

  • rtk context displays a table with all listed components
  • Each token count is based on real file content (no fixed estimates except MCP)
  • Missing file = graceful skip (no panic)
  • cargo test passes, clippy clean
  • CHANGELOG.md + README Module Responsibilities table updated

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with src/main.rs for command definitions and routing, then read src/tracking.rs, gain.rs, and discover/provider.rs for token estimation, table output, and project-path encoding. Create src/context_cmd.rs and update scripts/test-all.sh, covering the listed components, missing-file handling, inline tests, and output snapshot. Run cargo fmt, clippy, cargo test, and the documented context smoke checks; done includes the README and CHANGELOG updates.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.