Are you the author? Sign in to claim
A Claude Code status line with a reactive character plus cost, git, and usage widgets. Zero token spend, local-first, MI
A Claude Code status line with a character that reacts to your session. Full cost, git, and usage at a glance, at zero token spend.
npx ccsidekick
Running ccsidekick in a terminal opens the setup UI. On a first run it walks you through a short
guided wizard (character → theme → comments); later runs open the full dashboard to change
config or view stats, and either view can switch to the other with Ctrl+W / Ctrl+D. It wires
everything into Claude Code's settings.json (backing the file up first). Run
npx ccsidekick --help for every command, including a clean uninstall.
Prefer no TTY? npx ccsidekick setup --character spiderman --theme houston --mode fixed configures
and wires everything from flags. See Non-interactive setup.
Every character ships bundled with the engine, so a fresh install has them all — no download or install step. Pick and switch between them in the Character section (or the wizard): fixed mode pins one, random mode rotates a roster.
Each pack is data, never code: a single sourced ASCII figure (credited to its original artist; mood
adds color-only effects, never a new frame), a curated message library, and at least twenty-five
in-voice spinner verbs. Out of the box ccsidekick runs in random mode over the full roster, picking
a character per session; spiderman is the default only when you pin one in fixed mode.
Available packs:
…and more on the way. New characters land as they're authored.
Each pack registers its theme as a selectable option, so every bundled character also adds a palette. Authoring your own is a documented path; see below.
No terminal required — configure and wire ccsidekick from flags, ideal for scripts and AI agents:
npx ccsidekick setup --character spiderman --theme houston --mode fixed
Only the flags you pass are applied (a partial patch onto the existing config, or the defaults on a
fresh install); it then writes config.toml and wires settings.json exactly like the TUI. Flags
map to config fields: --character, --mode, --roster, --theme (character = match the
character, the default), --currency, --budget, --comments <on|off>, --helpful <on|off>,
--min-severity, --widgets, plus --global / --local and --config-dir.
Discover valid values and every flag:
npx ccsidekick list characters # also: themes, widgets
npx ccsidekick setup --help
An unknown value (a misspelled theme, say) exits non-zero and prints the valid set; it never silently falls back to a default.
A hand-editable TOML file at ${CLAUDE_CONFIG_DIR:-~/.claude}/ccsidekick/config.toml (a per-project
.ccsidekick/config.toml overrides it), with the TUI on top. The tables mirror the dashboard
sections, in order. A representative subset:
schema_version = 1
[character]
mode = "random" # fixed | random (random picks once per session)
name = "spiderman" # active pack in fixed mode; the default
roster = [] # pool for random mode (empty = all characters)
[theme]
name = "character" # "character" matches the active character; or any built-in / pack theme (default: character)
mood_shift = false # re-tint accent + gradient with the current mood
[comments]
character = true # the character's voice line (tone stays pack-owned)
helpful = true # actionable tips above the field rows
min_severity = "medium" # low | medium | high | critical
[network]
fx_refresh = false # off by default; weekly currency-rate refresh when on
usage_fetch = false # off by default; the account-usage widget sends your OAuth token to Anthropic
[statusline]
currency = "USD" # local-currency parenthetical on cost; default follows your system locale
Every field is toggled in [statusline.widgets] (the engine owns order and placement). The ids:
dir, added_dirs, session_name, git_branch, git_hash, git_tag, git_worktree,
git_changes, git_ahead_behind, git_status, git_conflict, git_operation, git_stash, pr,
model, fast_mode, thinking, output_style, agent, context_usage, compactions,
cost_chat, cost_project, cost_total, cost_burn, block_usage, weekly_usage, balance,
pay_as_you_go, cache_hit, token_burn, session_duration, todo.
Claude Code ──stdin JSON──▶ ccsidekick-render render ──stdout ANSI──▶ status line (main agent only)
▲
three PostToolUse-family hooks ──ccsidekick-render classify──▶ events log + state (disk only, no API, no tokens)
State lives under ${CLAUDE_CONFIG_DIR:-~/.claude}/ccsidekick/, partitioned per session so two
Claude windows never collide. Git runs fresh each tick; cost reads sit behind a short-lived cache.
The render path runs under plain Node and ships as a precompiled bundle, so the per-tick cost stays
low.
A Bun workspace. The engine is packages/core (published as ccsidekick); each character is
packages/packs/<name> (published as @ccsidekick/pack-<name>).
bun install
bun test
See CONTRIBUTING.md for the full toolchain (TypeScript, ESLint, Prettier, native
.githooks) and CLAUDE.md for the load-bearing invariants. The render path carries no
runtime dependencies the user manages.
Building locally needs Bun for the build and Node 20.6+ to run.
git clone https://github.com/krayong/ccsidekick.git
cd ccsidekick
bun install # workspace deps + git hooks
bun run link:global # build, then symlink both commands into ~/.local/bin
link:global puts ccsidekick and ccsidekick-render on your PATH (make sure ~/.local/bin is on
it). Re-run it after pulling changes to rebuild and relink.
The package ships two executables:
ccsidekick-render is the lean hot path. Claude Code calls ccsidekick-render render on
every statusline tick and ccsidekick-render classify on every tool call. It loads no UI and runs
under plain Node.ccsidekick is the user-facing entry: the setup TUI plus setup, list, and uninstall.
Only the TUI loads the Ink interface; setup/list/uninstall run under plain Node.Art is sourced through tooling, never hand-drawn, and every figure credits its creator. The
ascii-art image-to-ASCII skill supplies figures; the authoring kit width-normalizes them, checks
coverage and legibility, and generates the pack's README.md with a statusline preview rendered in
the pack's own theme. The full contract lives in the pack-author skill (
.claude/skills/pack-author).
Prior art in Claude Code statuslines, coding-companion pets, and transcript-based usage accounting:
Every character figure credits its original ASCII artist in the pack's attribution. The characters
themselves are unofficial fan art of trademarked properties. ccsidekick is a non-commercial hobby
project, not affiliated with or endorsed by any rights-holder, and any figure is removed on request.
Bugs and feature requests belong in GitHub Issues; security reports go through a Security Advisory. For anything else, email ccsidekick@krayong.com.
MIT © Karan Gourisaria. The MIT license covers ccsidekick's own code. The character figures are unofficial fan art of trademarked properties owned by their respective rights-holders; each ASCII rendering is credited to the artist who drew it (per pack), and figures are removed on a rights-holder's request.
1000+ skills curated from Anthropic, Vercel, Stripe, and other engineering teams
Agent harness performance optimization with skills, instincts, memory, and security
Design enforcement with memory — keeps your UI consistent across a project
Detects 37 AI writing patterns and rewrites text with human rhythm across 5 voice profiles