ccglance 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CxMYu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,384 @@
+# ccglance
+
+> A fast, zero-dependency, multi-line status line for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — model, effort, context, cache, git and session, all at a glance.
+
+[![Node.js >= 22](https://img.shields.io/badge/node-%3E%3D22-3c873a)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+English | [简体中文](./README.zh-CN.md)
+
+Repository: [github.com/CxMYu/CcGlanceLine](https://github.com/CxMYu/CcGlanceLine)
+
+`ccglance` uses the JSON that Claude Code pipes to its status-line command
+on stdin as its primary data source; the session `status` segment reads only
+the transcript tail when enabled. It's written in
+**TypeScript** and ships as compiled JavaScript with **zero runtime
+dependencies** (Node standard library only).
+
+## Preview
+
+![ccglance preview](./docs/assets/preview.png)
+
+Generated from `ccglance preview`.
+
+## Features
+
+- **Compact multi-line layout** — runtime, quota and project/session state are
+  separate logical rows; empty rows disappear.
+- **Zero runtime dependencies** — Node standard library only; TypeScript is a
+  build-time tool, never shipped in the published package.
+- **stdin-first** — core segments consume the JSON Claude Code provides; status
+  reads a bounded transcript tail only when used.
+- **Rich context block** — usage %, this-turn input/output tokens, tokens left.
+- **Prompt-cache block** — cache hit rate, read/write tokens.
+- **Git segment** — branch, clean/dirty/conflict glyph, ahead/behind counts,
+  using one bounded `git status` call plus a short local cache.
+- **Session segment** — elapsed time plus lines added/removed.
+- **Claude Code version + update hint** — shows the `version` field from
+  Claude Code stdin and appends `↑latest` when the 4h local cache reports a
+  newer Claude Code release. Refresh runs after stdout and never blocks.
+- **Additional session context** — 5h/7d rate-limit quota, USD cost and
+  worktree name next to the git branch when Claude Code provides it.
+- **Responsive multi-line layout** — probes the terminal width
+  (`CCGLANCE_WIDTH` → `COLUMNS` → TTY → `tput`/`stty`) and wraps each row into
+  as many lines as fit, down to a minimum of **one segment per line** so
+  nothing gets hidden; display-width aware (CJK/emoji safe).
+- **Fixed built-in style** — no user config file and no external style file;
+  the status line uses ccglance's own emoji-first style.
+
+## Requirements
+
+- Node.js **>= 22**
+- `git` on `PATH` (optional — only for the git segment)
+
+Claude Code compatibility:
+
+| Claude Code CLI | ccglance behavior |
+|---|---|
+| >= 1.0.71 | Basic status-line stdin support |
+| >= 2.1.80 | Subscription quota row when official `rate_limits.five_hour` / `rate_limits.seven_day` fields are present |
+| >= 2.1.153 | Preferred terminal-width sizing through `COLUMNS` / `LINES`; older versions fall back to TTY width or 80 columns |
+
+The quota row is subscription-only. Claude.ai Pro/Max-style sessions can expose
+`rate_limits`; API-key, Bedrock, Vertex, and other usage-based sessions usually
+do not, so ccglance hides the quota row instead of inferring one.
+
+## Install
+
+### Option A — npm (global, recommended)
+
+```bash
+npm install -g ccglance          # npm
+yarn global add ccglance         # or yarn
+pnpm add -g ccglance             # or pnpm
+```
+
+Behind a slow registry? Use a mirror:
+
+```bash
+npm install -g ccglance --registry https://registry.npmmirror.com
+```
+
+npm downloads the prebuilt `dist/` — no compiler runs on your machine — and puts
+a `ccglance` command on your `PATH`. Requires Node.js **>= 22**.
+
+After installation:
+
+- ✅ The `ccglance` command is available everywhere.
+- ⚙️ **Installing alone does not activate the status line** — add the `statusLine`
+  block to `~/.claude/settings.json` (see [Configure](#configure)), then restart
+  Claude Code.
+- 🔎 Verify with `ccglance preview` (sample render) or `ccglance --help` (usage +
+  the exact `settings.json` setup). Running `ccglance` in a plain terminal just
+  prints this help.
+
+Update or remove later with `npm update -g ccglance` / `npm uninstall -g ccglance`.
+
+### Option B — build from source
+
+```bash
+git clone https://github.com/CxMYu/CcGlanceLine.git
+cd CcGlanceLine
+npm install             # installs devDeps; the `prepare` script then compiles src/ → dist/
+npm link                # optional: expose `ccglance` on your PATH
+```
+
+`npm install` already builds `dist/` for you via the `prepare` lifecycle script —
+there is no separate build step to run. The compiled entry point is
+`dist/cli.js`; the `ccglance` bin command and `node dist/cli.js` are the same
+file. Verify:
+
+```bash
+node dist/cli.js preview
+```
+
+## Configure
+
+Add a `statusLine` block to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "ccglance",
+    "padding": 0
+  }
+}
+```
+
+If you didn't install globally, point Node at the compiled file directly:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node /absolute/path/to/ccglance/dist/cli.js"
+  }
+}
+```
+
+On Windows use a full path, e.g. `node D:\\path\\to\\ccglance\\dist\\cli.js`.
+
+> **Cross-platform paths:** Claude Code v2.1.47+ expands a leading `~` in the
+> command on every platform, so `node ~/path/to/dist/cli.js` works too. Prefer
+> `~` over `%USERPROFILE%` (unreliable in recent versions); the global `ccglance`
+> command needs no path at all. `"padding": 0` drops Claude Code's default leading
+> indent so the row starts at the left edge.
+
+## Line reference
+
+**Line 1 — runtime**
+
+| Label | Segment | Source | Shows |
+|---|---|---|---|
+| 🤖 | model | `model.display_name`, fallback to `model.id` | stdin display name with minimal compacting (`Opus 4.8 1M`); readable id fallback when missing |
+| 🧠 | effort | `effort.level` | reasoning effort |
+| ✅/⏸️/💭/⚙️/🔧 | status | transcript tail | icon-only state; tool name while a tool is running |
+| 🚀 | fast | `fast_mode` | shown only when fast mode is on |
+| ⚡️ | context | `context_window` | usage % · input · output · tokens left |
+| 💾 | cache | `context_window.current_usage` | hit % · cache read · cache write |
+| 🎯 | style | `output_style.name` | active output style |
+
+**Line 2 — quota**
+
+| Label | Segment | Source | Shows |
+|---|---|---|---|
+| 📊 | rate limits | `rate_limits.five_hour` / `rate_limits.seven_day` | Compact Hour / Week moon-phase meters with percentage and reset time; Claude Code does not provide a monthly quota window |
+
+**Line 3 — project / session**
+
+| Icon | Segment | Source | Shows |
+|---|---|---|---|
+| 📁 | dir | `workspace.current_dir` | current directory name |
+| 🌿 / 🌲 | git + worktree | stdin + local `git` | branch + status glyph: `✓` clean, `●` dirty, `⚠` conflicts; plus `↑ahead` `↓behind`; `worktree.name` is appended after the branch state |
+| 🏷️ | session name | `session_name` | set via `--name` or `/rename` |
+| ⏱️ | session | `cost` | elapsed time + `+added` `-removed` lines |
+| 💰 | cost | `cost.total_cost_usd` | USD cost, shown only when greater than 0 |
+| 💩 | version | `version` | Claude Code version; appends `↑latest` when the 4h cache finds a newer release |
+
+Rate-limit moon phases:
+
+| Usage | Icon |
+|---|---|
+| 0% <= usage < 10% | 🌑 |
+| 10% <= usage < 30% | 🌒 |
+| 30% <= usage < 60% | 🌓 |
+| 60% <= usage < 90% | 🌔 |
+| 90% <= usage <= 100% | 🌕 |
+
+## Icon Reference
+
+| Icon | Meaning |
+|---|---|
+| 🤖 | model name; `model.display_name` is the source of truth, with readable `model.id` fallback |
+| 🧠 | reasoning effort |
+| ✅ | idle; the last assistant turn appears complete |
+| ⏸️ | paused; a running action was interrupted or cancelled |
+| 💭 | thinking; waiting for or receiving model output |
+| ⚙️ | working; a tool result returned and Claude is processing it |
+| 🔧 | tool call in progress; the tool name is shown when available |
+| 🚀 | fast mode |
+| ⚡️ | context-window usage |
+| 💾 | prompt cache usage |
+| 🎯 | output style |
+| 📊 | Hour / Week rate-limit quota |
+| 🌑 🌒 🌓 🌔 🌕 | rate-limit usage level |
+| ⏳ | time until the quota window resets |
+| 📁 | current directory |
+| 🌿 | git branch |
+| ✓ ● ⚠ | git clean / dirty / conflict |
+| 🌲 | worktree name, shown inside the git segment |
+| 🏷️ | session name |
+| ⏱️ | session duration |
+| 💰 | session cost |
+| 💩 | Claude Code version |
+| ↑latest | newer Claude Code version is available |
+
+## Color Semantics
+
+| Color | Meaning |
+|---|---|
+| Bright green | idle/healthy state, fast mode, cache, additions, clean git marker, git ahead/outgoing/push count |
+| Yellow | attention state: paused status, effort, quota reset time, cost, warning thresholds |
+| Bright red | risk or negative state: danger thresholds, conflicts, deletions, update hint |
+| Blue | Git modified/dirty status and behind/incoming/pull count |
+| Cyan / white | neutral runtime/project identity: model, style, session duration, git branch |
+| Magenta | active context/session identity: context window, session name |
+
+The status icons are inferred from the transcript tail when Claude Code redraws
+the status line. They are a redraw-time approximation, not a live event stream.
+If a running action is cancelled with Esc, ccglance updates on the next Claude
+Code redraw; transcript interrupt markers are shown as paused.
+
+## How it works
+
+On every redraw Claude Code runs your status-line `command` and pipes a JSON
+object to its **stdin** (model, effort, context window, cost, workspace,
+version, …). `ccglance` reads that once via `fs.readFileSync(0)`, formats its
+fixed rows, and **prints them first**. The `status` segment reads only a
+bounded transcript tail. The version segment synchronously
+reads only a tiny local cache; after stdout is written, ccglance refreshes the
+Claude Code latest-version cache in a detached background process when it is
+older than 4 hours. If the JSON can't be parsed it exits silently so it can never
+break the CLI. Text from stdin, transcript, and git is sanitized before being
+printed so terminal control sequences cannot escape the status line. The main
+external calls are local `git` (single bounded status call with a short cache),
+bounded transcript-tail reads, and the post-render detached npm registry check.
+
+## Development
+
+### Source Build
+
+```bash
+git clone https://github.com/CxMYu/CcGlanceLine.git
+cd CcGlanceLine
+npm install              # installs devDeps and runs prepare -> build
+
+npm run build            # compile src/ → dist/
+npm run typecheck        # tsc --noEmit (strict)
+npm test                 # build + node:test fixtures/snapshots/smoke
+npm run benchmark        # build + latency benchmark
+ccglance preview         # preview the linked/global command
+
+# smoke-test with a sample stdin payload:
+printf '%s' '{"model":{"display_name":"Claude Opus 4.8 (1M context)","id":"claude-opus-4-8[1m]"}}' | node dist/cli.js
+```
+
+For local dogfooding, use `npm link` after building and configure Claude Code
+with `"command": "ccglance"`. Without a global link, point Claude Code directly
+at `node /absolute/path/to/ccglance/dist/cli.js`.
+
+### Validation
+
+- `test/fixtures/` contains stdin payloads for subscription, API-style,
+  missing-field, and high-context scenarios.
+- `test/snapshots/` locks the ANSI-colored rendered output so icon, spacing,
+  color, and row changes are intentional.
+- `test/*.test.js` uses Node's built-in `node:test`; no test runner dependency
+  is added to the runtime package.
+- `bench/latency.js` measures cold process startup against an empty Node
+  baseline, plus no-git, subscription+transcript, git warm-cache, and git
+  cold-fallback paths. On Windows, the empty Node baseline is usually the
+  dominant part of the number; compare ccglance cases to that baseline.
+
+### Agent Build Practices
+
+- Treat `src/` as the source of truth. Do not hand-edit `dist/`; regenerate it
+  with `npm run build`.
+- Keep the status line fixed-style: no user config loader, no external style
+  file, and no runtime style discovery.
+- Keep runtime dependencies at zero. New dependencies must be development-only
+  and justified by the build pipeline.
+- After code changes, run `npm run typecheck`, `npm run build`, and
+  `ccglance preview`.
+- When changing icon or spacing behavior, test the plain ANSI-stripped preview
+  and at least one synthetic stdin payload that exercises the edited segment.
+
+### Source layout
+
+```text
+src/
+  cli.ts              # command entry: preview / statusLine stdin
+  defaults/           # fixed built-in style and segment order
+  readers/            # stdin, transcript tail reads, terminal width
+  render/             # colors, icons, layout, final rendering
+  segments/           # per-segment rendering logic
+  runtime/            # git and Claude Code version-cache helpers
+  types/              # Claude Code stdin and renderer types
+  utils/              # formatting and display-width helpers
+test/
+  fixtures/           # representative Claude Code stdin and transcript data
+  snapshots/          # fixed rendered-output baselines
+bench/
+  latency.js          # startup and cache-path benchmark
+```
+
+Only the compiled `dist/` is published to npm. `npm run build` cleans `dist`
+before compiling so old flat artifacts cannot leak into the package.
+
+## Session status and preview
+
+- Session status: an icon indicator inferred from the transcript tail; `✅` idle, `⏸️` paused/interrupted, `💭` thinking, `⚙️` processing a tool result, `🔧 <tool>` running a tool.
+- ccglance preview: render a built-in sample with the fixed renderer.
+
+## Cache Files
+
+ccglance stores only disposable runtime caches: git status, transcript-derived
+status, and the Claude Code latest-version check. Files are grouped under
+`git/`, `transcript/`, and `version/`.
+
+Caches live under Claude Code's own config directory on every platform, so they
+travel with your Claude setup and are trivial to clear:
+
+```text
+~/.claude/ccglance/
+├── git/          # git status snapshots (one per repo)
+├── transcript/   # transcript-derived session status
+└── version/      # Claude Code latest-version check
+```
+
+If you set `CLAUDE_CONFIG_DIR` to relocate Claude Code's config, ccglance places
+its caches under that directory instead. Deleting the whole `ccglance/` folder is
+safe — every file is regenerated on the next render.
+
+Git cache behavior:
+
+- Cache key is the Git worktree root, so multiple Claude Code terminals in the
+  same repo share one git cache.
+- The branch name prefers Claude Code stdin when `worktree.branch` is present;
+  otherwise ccglance checks `.git/HEAD` on every render, so normal branch
+  switches still show up immediately.
+- Dirty/conflict and ahead/behind details use a cache. A cache newer than 20
+  minutes is returned when it still belongs to the current branch.
+- Local state (`✓` / `●` / `⚠`) and upstream state (`↑ahead` / `↓behind`) come
+  from the same cached `git status --porcelain=v2 --branch` snapshot, so they
+  share the same TTL. If both local and upstream changes exist, ccglance shows
+  them together, for example `main ● ↑1 ↓1`.
+- A stale cache, missing cache, or branch change still renders immediately;
+  ccglance shows a fast branch-only `HEAD` fallback, then refreshes `git status`
+  in a detached process.
+- Refresh uses an exclusive `.refresh` marker and atomic temp-file rename, so
+  concurrent terminals do not corrupt the cache.
+- There is no heartbeat or resident watcher. Refresh is lazy: Claude Code
+  redraws the status line, ccglance checks the cache age, and only then starts
+  the detached refresh process if the cache is stale.
+
+## Related Projects
+
+- [CCometixLine](https://github.com/Haleclipse/CCometixLine) — high-performance Rust status line with an interactive TUI config and themes
+- [ccstatusline](https://github.com/sirmalloc/ccstatusline) — configurable status line with powerline styling
+- [claude-powerline](https://github.com/Owloops/claude-powerline) — lightweight powerline-style status line
+
+## Contributing
+
+Issues and pull requests are welcome. For code changes, run `npm run typecheck`,
+`npm run build`, and `ccglance preview` before opening a PR; keep the runtime at
+**zero dependencies** and the style fixed (no config loader).
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=CxMYu/CcGlanceLine&type=Date)](https://star-history.com/#CxMYu/CcGlanceLine&Date)
+
+## License
+
+[MIT](./LICENSE) © 2026 CxMYu