{"id":49041186,"url":"https://github.com/tugayoktayokay/claude-code-ctx","last_synced_at":"2026-04-19T15:00:23.327Z","repository":{"id":352412339,"uuid":"1215038340","full_name":"tugayoktayokay/claude-code-ctx","owner":"tugayoktayokay","description":"Standalone zero-dep CLI for Claude Code session token tracking, model-aware quality ceiling, tailored /compact prompt generation, and snapshot-to-memory bridging. No hooks, no AI, no auto-triggers.","archived":false,"fork":false,"pushed_at":"2026-04-19T13:00:46.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T14:30:08.024Z","etag":null,"topics":["anthropic","claude","claude-code","cli","context-management","nodejs","token-tracker","zero-dependency"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/tugayoktayokay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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":"2026-04-19T11:54:48.000Z","updated_at":"2026-04-19T13:00:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tugayoktayokay/claude-code-ctx","commit_stats":null,"previous_names":["tugayoktayokay/ctx"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tugayoktayokay/claude-code-ctx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tugayoktayokay%2Fclaude-code-ctx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tugayoktayokay%2Fclaude-code-ctx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tugayoktayokay%2Fclaude-code-ctx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tugayoktayokay%2Fclaude-code-ctx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tugayoktayokay","download_url":"https://codeload.github.com/tugayoktayokay/claude-code-ctx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tugayoktayokay%2Fclaude-code-ctx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32010957,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["anthropic","claude","claude-code","cli","context-management","nodejs","token-tracker","zero-dependency"],"created_at":"2026-04-19T15:00:19.558Z","updated_at":"2026-04-19T15:00:23.321Z","avatar_url":"https://github.com/tugayoktayokay.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ctx\n\n**A standalone CLI for knowing when to `/compact` or `/clear` your Claude Code session — and preparing the prompt that makes it worth it.**\n\nZero dependencies. Zero AI calls. Zero hooks inside your Claude Code session. You run it in a side terminal. It tells you what's happening, and hands you a prompt you can paste.\n\n---\n\n## Why it exists\n\nClaude Code now ships with Opus 4 at a 1M-token context window. But quality degrades well before you hit the ceiling — typically around 200k, where cache churn and attention dilution start to bite.\n\nExisting tooling doesn't surface this:\n\n| tool | problem it solves | what it misses |\n|---|---|---|\n| [ccusage](https://github.com/ryoppippi/ccusage) | \"How much have I spent?\" (cost + token reports) | No active in-session guidance |\n| [Claude-Code-Usage-Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor) | \"How much of my Pro/Max plan is left?\" (5h windows) | Tracks plan quota, not context saturation |\n| [claudikins-acm](https://github.com/elb-pr/claudikins-automatic-context-manager) | Auto-handoff at 60% via plugin hooks | Fixed threshold, no model-aware ceiling, plugin eats in-session tokens |\n| [claude-mem](https://github.com/thedotmack/claude-mem) | AI-compressed memory injection via agent-sdk | Uses AI on every capture, SQLite + HTTP worker, heavy |\n| **ctx** | **When should I stop? What should I preserve?** | — |\n\n`ctx` answers two questions `ccusage` doesn't and makes two choices the plugins don't:\n\n1. **Model-aware quality ceiling.** Opus 4's 1M is the technical max; 200k is where quality ceiling kicks in. `ctx` thresholds fire against the ceiling, not the max. Haiku gets 100k. Override per-model in config.\n2. **Tailored `/compact` prompts.** `ctx compact` reads your session, detects categories (schema / api / auth / bug / etc.), extracts critical signals (decisions, failed attempts, endpoints, errors), and generates a ready-to-paste prompt like:\n   \u003e `/compact focus on API routes + DB/Schema — keep: files: petitions.ts, schema.prisma; 2 architectural decisions; failed attempts — continue: \"now wire the stripe webhook\"`\n3. **Standalone.** No plugin, no hooks, no agent-sdk. Runs in a side terminal or as a background daemon. Your Claude Code session doesn't know it exists.\n4. **Zero deps.** Pure Node built-ins. 1600 lines. Readable in one sitting.\n\n---\n\n## Install\n\n```bash\nnpm install -g claude-code-ctx\nctx --help\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/tugayoktayokay/claude-code-ctx.git ~/tools/claude-code-ctx\ncd ~/tools/claude-code-ctx\nnpm link\nctx --help\n```\n\nRequires Node 18+. No transitive dependencies — the package has nothing in `dependencies` or `devDependencies`.\n\n\u003e The CLI command is `ctx`. The npm package is `claude-code-ctx` because the bare `ctx` and `claude-ctx` names are taken or blocked by npm's typo-squatting policy.\n\n---\n\n## Commands\n\n```bash\nctx                                  # analyze current session, show recommendation\nctx watch                            # live token % in foreground terminal\nctx daemon start|stop|status|log     # background watcher with macOS notifications\nctx compact                          # generate tailored /compact prompt, copy to clipboard\nctx snapshot [--name NAME]           # write session summary to your Claude Code memory dir\nctx history [N]                      # last N sessions across all projects\nctx config                           # open / create ~/.config/ctx/config.json\nctx file \u003cpath\u003e                      # analyze a specific JSONL file\n```\n\n### `ctx` — analyze\n\nReads the most recent JSONL under `~/.claude/projects/\u003cencoded-cwd\u003e/` and prints:\n\n```\n  [█████████████████████░░░░░░░░░░░░░░░░░░░] 54%\n  108.1k / 200.0k quality ceiling   (model max 1.0M)\n  ⚠️  COMPACT\n  model: claude-opus-4-7\n\n  Metrics:\n    Messages  : 75\n    Tool calls: 71\n    Files     : 20\n    Output    : 183.7k tokens\n\n  Analysis:\n    • Context 54% of 200.0k quality ceiling (108.1k tokens)\n    • Model max: 1.0M, but quality degrades past 200.0k\n\n  ✓ Keep in compact:\n    • active areas: Tests, Infra/DevOps, Bug fix, AI integration\n    • modified files (20): …\n    • last task: \"now wire the stripe webhook\"\n\n  ➜ ctx compact — prepare a tailored /compact prompt\n```\n\n### `ctx compact` — tailored prompt\n\nThe payoff command. `ccusage` tells you 150k tokens are gone; `ctx compact` tells you *what* those tokens were and writes the prompt that preserves the important parts:\n\n```\n  /compact prompt (copy + paste):\n\n  /compact focus on API routes + DB/Schema + Bug fix — keep: files: petitions.ts, schema.prisma, petitions.test.ts, auth.ts; 2 architectural decisions; failed attempts; decision, endpoint, failed attempt — continue: \"now wire the stripe webhook\"\n\n  ✓ Copied to clipboard\n```\n\nPaste it straight into Claude Code. The structure tells Claude what to focus on, what to preserve, what to drop, and what you were about to do next.\n\n### `ctx daemon` — background\n\n```bash\nctx daemon start    # detaches, writes pid to ~/.config/ctx/daemon.pid\nctx daemon status   # uptime, last level, last git commit\nctx daemon log 30   # tail\nctx daemon stop\n```\n\nThe daemon polls every 10 seconds (configurable). It fires a macOS notification when:\n- You cross a threshold (`compact` / `urgent` / `critical`)\n- You make a new git commit in the cwd — natural moment for `ctx snapshot`\n\nNo time-based alerts (\"you've been coding for 45 minutes\"). Token state or git state only.\n\n### `ctx snapshot` — bridge to memory\n\nWrites a markdown file into `~/.claude/projects/\u003ccwd\u003e/memory/project_\u003cauto-name\u003e.md` with:\n- What files you modified\n- Architectural decisions detected\n- Failed approaches to avoid\n- Last user intent\n- Context metrics at snapshot time\n\nThen appends a line to `MEMORY.md`. The next session's Claude Code instance loads it as context. If you use a custom `/snapshot` skill, this is the non-interactive version of it.\n\n---\n\n## Configuration\n\n`~/.config/ctx/config.json` — created on first `ctx config` call.\n\n```json\n{\n  \"limits\": {\n    \"models\": {\n      \"claude-opus-4-7\":   { \"max\": 1000000, \"quality_ceiling\": 200000 },\n      \"claude-sonnet-4-6\": { \"max\": 200000,  \"quality_ceiling\": 200000 },\n      \"claude-haiku-4-5\":  { \"max\": 200000,  \"quality_ceiling\": 100000 },\n      \"default\":           { \"max\": 200000,  \"quality_ceiling\": 200000 }\n    },\n    \"thresholds\": {\n      \"comfortable\": 0.20,\n      \"watch\":       0.40,\n      \"compact\":     0.55,\n      \"urgent\":      0.75,\n      \"critical\":    0.90\n    }\n  },\n  \"categories\": {\n    \"api\":    { \"words\": [\"route\", \"endpoint\", \"fastify\", \"express\"], \"label\": \"API routes\" },\n    \"schema\": { \"words\": [\"schema\", \"migration\", \"prisma\"],          \"label\": \"DB/Schema\" }\n  },\n  \"watch\": {\n    \"interval_ms\": 10000,\n    \"macos_notifications\": true\n  }\n}\n```\n\nThe model list is matched against Claude Code's `message.model` field in the JSONL. Unknown models fall back to `default`. The category word lists drive both detection and the `/compact` prompt structure.\n\n---\n\n## What ctx deliberately does *not* do\n\n- **Write to `CLAUDE.md`.** Your architecture docs are yours; `ctx` never touches them.\n- **Install hooks into Claude Code.** No `SessionStart` / `PreToolUse` / `Stop` hooks. The tool has zero runtime cost inside your session.\n- **Call an LLM.** Everything is regex, token math, and category heuristics. No `anthropic` SDK, no agent-sdk, no API key needed.\n- **Auto-trigger `/clear` or `/compact`.** It generates the prompt; you decide when to run it.\n- **Fire time-based alerts.** A 45-minute session that's at 30k tokens is fine. A 5-minute session that's at 180k is not.\n- **Require an npm install.** No dependencies, ever.\n\n---\n\n## Testing\n\n```bash\nnode --test src/test/*.test.js\n```\n\n17 tests covering session parsing, analysis, decision thresholds, compact strategy, snapshot writing, model detection, and git integration. The fixture `src/test/fixtures/demo-session.jsonl` is the canonical reference for what a JSONL entry looks like.\n\n---\n\n## Architecture\n\n```\nsrc/\n  session.js      JSONL reader + findLatestSession\n  analyzer.js     entries → stats (tokens + categories + files + decisions + critical patterns)\n  decision.js     stats → level + action (model-aware thresholds)\n  strategy.js     analysis → /compact prompt builder + clipboard\n  snapshot.js     analysis → memory markdown + MEMORY.md index\n  watcher.js      foreground live loop\n  daemon.js       background loop + pid/log/state + git detection\n  models.js       detectModel() + getLimits()\n  config.js       defaults merge + user config loader\n  output.js       ANSI formatting + macOS notifier\n  cli.js          subcommand dispatch\nbin/\n  ctx             shebang entrypoint\n```\n\nEach module is independently testable. `src/test/*.test.js` mirrors this layout.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftugayoktayokay%2Fclaude-code-ctx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftugayoktayokay%2Fclaude-code-ctx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftugayoktayokay%2Fclaude-code-ctx/lists"}