ccline: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (and humans) working on this repo.

What this is

@abdallahaho/ccline is a single-file bash statusline for Claude Code. Install is npx @abdallahaho/ccline@latest — it copies one script to ~/.claude/statusline.sh and wires a statusLine entry into ~/.claude/settings.json.

Two design constraints drive every decision in this codebase:

1. It runs on every Claude Code render. Latency matters. Every subprocess spawn is a cost.
2. It can be killed mid-render if it exceeds Claude Code's statusline timeout. It must never leave persistent side effects behind (stale lock files, half-written caches, etc.).

Repository layout

ccline/
├── bin/
│   ├── statusline.sh        # the script — everything users actually run
│   └── install.js           # npm-bin entrypoint; copies statusline.sh to ~/.claude/ and edits settings.json
├── .github/
│   └── workflows/publish.yml  # release-it on push to main
├── package.json             # @abdallahaho/ccline — npm package metadata + release-it config
├── README.md                # user-facing docs
├── how-it-works.md          # script internals — read this before touching statusline.sh
├── CHANGELOG.md             # auto-generated by @release-it/conventional-changelog
├── CLAUDE.md                # this file
└── LICENSE

bin/statusline.sh is the entire product. Don't factor it into multiple files — install needs to be a single cp, and shell sourcing across files adds fragility for no gain.

Design principles

• One script, no dependencies beyond the basics. bash, jq, curl, git — nothing else. These are available everywhere Claude Code runs.
• Single jq parse per document. All input JSON fields are hydrated in one eval block, and the usage API response in another (see how-it-works.md). Don't add per-field jq calls — each one is a subprocess.
• Degrade quietly. Missing tool, missing field, API failure — the statusline should produce less output, never an error message and never a crash.
• Cross-platform by default. Every date / stat call needs a BSD path and a GNU path. macOS ships BSD; Linux/WSL ships GNU; Git Bash is somewhere in between.
• No persistent state. The only things written to disk are a 60s OAuth cache and a one-line fetch-backoff marker under ${TMPDIR:-/tmp}/claude-${UID}/. No pidfiles, no session files.
• Minimal visual noise. Badges hidden when they'd duplicate the default (e.g. permission-mode badge only renders when non-default). Don't add segments that fire on every render unless they carry signal.