{"id":35893255,"url":"https://github.com/luongnv89/cc-context-stats","last_synced_at":"2026-04-02T13:40:33.549Z","repository":{"id":330820539,"uuid":"1124037438","full_name":"luongnv89/cc-context-stats","owner":"luongnv89","description":"Keep your model sharp. Ship with confidence.","archived":false,"fork":false,"pushed_at":"2026-04-01T11:56:24.000Z","size":17915,"stargazers_count":69,"open_issues_count":7,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-01T13:28:52.653Z","etag":null,"topics":["context","stats"],"latest_commit_sha":null,"homepage":"https://luongnv.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luongnv89.png","metadata":{"files":{"readme":"README.backup.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-28T07:24:42.000Z","updated_at":"2026-04-01T11:56:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/luongnv89/cc-context-stats","commit_stats":null,"previous_names":["luongnv89/claude-statusline","luongnv89/cc-context-stats"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/luongnv89/cc-context-stats","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fcc-context-stats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fcc-context-stats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fcc-context-stats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fcc-context-stats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luongnv89","download_url":"https://codeload.github.com/luongnv89/cc-context-stats/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luongnv89%2Fcc-context-stats/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["context","stats"],"created_at":"2026-01-09T11:00:36.028Z","updated_at":"2026-04-02T13:40:33.539Z","avatar_url":"https://github.com/luongnv89.png","language":"Python","funding_links":[],"categories":["Usage Tracker"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/logo/logo-full.svg\" alt=\"cc-context-stats\" width=\"320\"/\u003e\n\n  \u003ch3\u003eKeep your model sharp. Ship with confidence.\u003c/h3\u003e\n\n  \u003cp\u003eReal-time model intelligence monitoring for Claude Code — know exactly when your model is at peak quality and when it's time for a fresh session.\u003c/p\u003e\n\n[![PyPI version](https://img.shields.io/pypi/v/cc-context-stats)](https://pypi.org/project/cc-context-stats/)\n[![npm version](https://img.shields.io/npm/v/cc-context-stats)](https://www.npmjs.com/package/cc-context-stats)\n[![PyPI Downloads](https://img.shields.io/pypi/dm/cc-context-stats)](https://pypi.org/project/cc-context-stats/)\n[![npm Downloads](https://img.shields.io/npm/dm/cc-context-stats)](https://www.npmjs.com/package/cc-context-stats)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003c/div\u003e\n\n**Always use Claude at its best** — monitor model intelligence in real-time so you know exactly when quality starts to drop.\n\n![Context Stats - Model Intelligence](images/1.10/1.10.0-model-intelligence.png)\n\n## Why Context Stats?\n\nResearch shows that LLM quality degrades as the context window fills up — even the best models lose retrieval accuracy at longer contexts. But you can't see this happening. Context Stats makes it visible:\n\n- **Model Intelligence (MI)** - A benchmark-calibrated score (1.000 → 0.000) that tracks how much quality has degraded, with per-model profiles for Opus, Sonnet, and Haiku\n- **Know your zone** - See if you're in the Smart Zone, Dumb Zone, or Wrap Up Zone\n- **Track context usage** - Real-time monitoring with live-updating ASCII graphs\n- **Get early warnings** - Color-coded alerts tell you when to start a fresh session\n- **Per-model awareness** - Opus retains quality longer than Sonnet, which degrades faster than Haiku. MI reflects this automatically\n\n## Context Zones\n\n| Zone                | Context Used | Status   | What It Means                                 |\n| ------------------- | ------------ | -------- | --------------------------------------------- |\n| 🟢 **Smart Zone**   | \u003c 40%        | Optimal  | Claude is performing at its best              |\n| 🟡 **Dumb Zone**    | 40-80%       | Degraded | Context getting full, Claude may miss details |\n| 🔴 **Wrap Up Zone** | \u003e 80%        | Critical | Better to wrap up and start a new session     |\n\n## Installation\n\n### Shell Script\n\nFor the quickest setup:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/install.sh | bash\n```\n\n### NPM\n\n```bash\nnpm install -g cc-context-stats\n```\n\nOr with yarn:\n\n```bash\nyarn global add cc-context-stats\n```\n\n### Python\n\n```bash\npip install cc-context-stats\n```\n\nOr with uv:\n\n```bash\nuv pip install cc-context-stats\n```\n\n### Verify Installation\n\nAfter installing via any method, verify that both the statusline and context-stats CLI are working:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/luongnv89/cc-context-stats/main/scripts/check-install.sh | bash\n```\n\nOr if you cloned the repo:\n\n```bash\n./scripts/check-install.sh\n```\n\n## Quick Start\n\n### Status Line Integration\n\nAdd to `~/.claude/settings.json` (the command depends on how you installed):\n\n**pip or npm install:**\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"claude-statusline\"\n  }\n}\n```\n\n**Shell script install (`install.sh`):**\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"~/.claude/statusline.sh\"\n  }\n}\n```\n\nRestart Claude Code to see real-time model intelligence and context stats in your status bar.\n\n### Real-Time Monitoring\n\nGet your session ID from the status line (the last part after the pipe `|`), then run:\n\n```bash\ncontext-stats \u003csession_id\u003e\n```\n\nFor example:\n\n```bash\ncontext-stats abc123def-456-789\n```\n\nThis opens a live dashboard that refreshes every 2 seconds, showing:\n\n- Your current project and session\n- Context growth per interaction graph\n- Model Intelligence degradation over time\n- Your current zone status and MI score\n- Remaining context percentage\n\nPress `Ctrl+C` to exit.\n\n### Graph Types\n\n| Delta (default) | Cumulative |\n|:---:|:---:|\n| ![Delta](images/1.10/1.10-delta.png) | ![Cumulative](images/1.10/1.10-cumulative.png) |\n\n## Context Stats CLI\n\n```bash\ncontext-stats                    # Live monitoring (default)\ncontext-stats -w 5               # Custom refresh interval (5 seconds)\ncontext-stats --no-watch         # Show once and exit\ncontext-stats --type cumulative  # Show cumulative context usage\ncontext-stats --type both        # Show both graphs\ncontext-stats --type mi          # Model Intelligence over time\ncontext-stats --type all         # Show all graphs including I/O and MI\ncontext-stats \u003csession_id\u003e       # View specific session\ncontext-stats explain            # Diagnostic dump (pipe JSON to stdin)\ncontext-stats --version          # Show version\n```\n\n### Output Example\n\n```\nContext Stats (my-project • abc123def)\n\nContext Growth Per Interaction\nMax: 4,787  Min: 0  Points: 254\n...graph...\n\nSession Summary\n----------------------------------------------------------------------------\n  Context Remaining:   43,038/200,000 (21%)\n  \u003e\u003e\u003e DUMB ZONE \u003c\u003c\u003c (You are in the dumb zone - Dex Horthy says so)\n  Model Intelligence:  0.646  (Context pressure building, consider wrapping up)\n    Context: 79% used\n\n  Last Growth:         +2,500\n  Input Tokens:        1,234\n  Output Tokens:       567\n  Lines Changed:       +45 / -12\n  Total Cost:          $0.1234\n  Model:               claude-sonnet-4-6\n  Session Duration:    2h 29m\n```\n\n## Status Line\n\nColors change based on MI score and context utilization — green when the model is sharp, yellow as quality degrades:\n\n| MI \u003e= 0.90 (green) | MI \u003c 0.90 (yellow) |\n|:---:|:---:|\n| ![Green](images/1.10/statusline-green.png) | ![Yellow](images/1.10/1.10-statusline.png) |\n\nThe status line shows at-a-glance metrics in your Claude Code interface:\n\n| Component | Description                               |\n| --------- | ----------------------------------------- |\n| Model     | Current Claude model                      |\n| Context   | Tokens used / remaining with color coding |\n| Delta     | Token change since last update            |\n| MI        | Model Intelligence score (per-model)      |\n| Git       | Branch name and uncommitted changes       |\n| Session   | Session ID for correlation                |\n\n## Configuration\n\nCreate `~/.claude/statusline.conf`:\n\n```bash\ntoken_detail=true    # Show exact token counts (vs abbreviated like \"12.5k\")\nshow_delta=true      # Show token delta in status line\nshow_session=true    # Show session ID\nautocompact=true     # Show autocompact buffer indicator\nreduced_motion=false # Disable animations for accessibility\nshow_mi=false        # Show Model Intelligence score (disabled by default)\nmi_curve_beta=0      # Use model-specific profile (0=auto, or set custom beta)\n\n# Custom colors - named colors or hex (#rrggbb)\ncolor_green=#7dcfff\ncolor_red=#f7768e\ncolor_yellow=bright_yellow\n```\n\n## Model Intelligence (MI)\n\nMI estimates how well the model will perform at your current context fill level, calibrated from the [MRCR v2 8-needle](https://docs.anthropic.com/) long context retrieval benchmark. The score drops from 1.000 (fresh context) to 0.000 (full context), with model-specific degradation rates:\n\n| Model | Beta | MI at 50% | MI at 75% | When to worry |\n|-------|------|-----------|-----------|---------------|\n| Opus  | 1.8  | 0.713     | 0.404     | ~60% used     |\n| Sonnet| 1.5  | 0.646     | 0.350     | ~50% used     |\n| Haiku | 1.2  | 0.565     | 0.292     | ~45% used     |\n\nThe model is auto-detected from your session. See [Model Intelligence docs](docs/MODEL_INTELLIGENCE.md) for the full formula and benchmark data.\n\n## How It Works\n\nContext Stats hooks into Claude Code's status line feature to track token usage across your sessions. The Python and Node.js statusline scripts write state data to local CSV files, which the context-stats CLI reads to render live graphs. Data is stored locally in `~/.claude/statusline/` and never sent anywhere.\n\n## Documentation\n\n- [Installation Guide](docs/installation.md) - Platform-specific setup (shell, pip, npm)\n- [Context Stats Guide](docs/context-stats.md) - Detailed CLI usage guide\n- [Configuration Options](docs/configuration.md) - All settings explained\n- [Available Scripts](docs/scripts.md) - Script variants and features\n- [Model Intelligence](docs/MODEL_INTELLIGENCE.md) - MI formula, per-model profiles, benchmark data\n- [Architecture](docs/ARCHITECTURE.md) - System design and components\n- [CSV Format](docs/CSV_FORMAT.md) - State file field specification\n- [Development](docs/DEVELOPMENT.md) - Dev setup, testing, and debugging\n- [Deployment](docs/DEPLOYMENT.md) - Publishing and release process\n- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions\n- [Changelog](CHANGELOG.md) - Version history\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on the development setup, branching strategy, and PR process.\n\nThis project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Migration from cc-statusline\n\nIf you were using the previous `cc-statusline` package:\n\n```bash\npip uninstall cc-statusline\npip install cc-context-stats\n```\n\nThe `claude-statusline` command still works. The main change is `token-graph` is now `context-stats`.\n\n## Related\n\n- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)\n- [Blog: Building this project](https://medium.com/@luongnv89/closing-the-gap-between-mvp-and-production-with-feature-dev-an-official-plugin-from-anthropic-444e2f00a0ad)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluongnv89%2Fcc-context-stats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluongnv89%2Fcc-context-stats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluongnv89%2Fcc-context-stats/lists"}