codachi

A productivity copilot disguised as a tamagotchi, living in your Claude Code statusline.

Why codachi?

• Context ETA — ~15m left tells you when to /compact, not just how full you are. The only statusline that predicts it.
• Event-aware pet — hooks watch Claude work and react with 900+ contextual messages, across 40+ event categories.
• codachi stats — local, zero-telemetry productivity dashboard: sessions, uptime, tier progress, last-24h test/commit/edit counts.
• Plugin API — drop a .mjs file into ~/.config/codachi/plugins/ to add your own palettes and messages. No forking required.
• i18n — bundled 简体中文; English fallback for any missing keys. BYO locale via CODACHI_LOCALE.
• Terminal-aware — auto-detects truecolor / 256-color / 16-color / monochrome and degrades gracefully. NO_COLOR honored.
• Zero overhead — no API calls, no tokens consumed. Local JSON + disk. Render p95 is ~0.1ms (verified by npm run bench).

Quick Start

One line. That's it.

npx codachi init

This wires up your ~/.claude/settings.json statusline and PostToolExecution hook. Restart Claude Code and your pet will hatch.

Prefer a global install? npm install -g codachi && codachi init works too.

Useful commands once installed:

npx codachi stats             # productivity dashboard (sessions, uptime, tiers)
npx codachi plugins           # list loaded plugins
npx codachi config            # interactive TUI configurator
npx codachi demo              # live preview without installing

git clone https://github.com/vincent-k2026/codachi.git
cd codachi && npm install && npm run build
node dist/index.js init

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "node /absolute/path/to/codachi/dist/index.js"
  },
  "hooks": {
    "PostToolExecution": [
      {
        "matcher": "",
        "command": "node /absolute/path/to/codachi/dist/hook.js"
      }
    ]
  }
}

Statusline Layout

Line 1   Opus 4.6 | ██░░ 55% 555K/1.0M ^3%/m ~15m | 5h ████░░░░ 32% ⇡5% ~2h | 7d ██░░░░░░ 8% ⇣2% ~6d
Line 2   git:(main*) ~12 ?3 | +489 -84 lines | last: fix auth bug
Line 3   Mochi *slow blink* ...I love you

| Metric | Description | |:-------|:------------| | ██░░ 55% | Context window usage with progress bar | | 555K/1M | Tokens used / total window size | | ^3%/m | Context burn speed (how fast you're filling up) | | ~15m | Estimated time until context is full | | 5h ████░░░░ 32% ⇡5% ~2h | 5-hour rate limit + pace delta + reset countdown | | 7d ██░░░░░░ 8% ⇣2% ~6d | 7-day rate limit + pace delta + reset countdown | | ⇡5% | Over-consuming (red) — your pace exceeds the natural rate limit window | | ⇣2% | Has headroom (green) — you're below the natural pace | | git:(main*) ~12 ?3 | Branch, modified/untracked files | | +489 -84 lines | Insertions / deletions in working tree | | Mochi *slow blink* | Custom pet name + contextual mood message |

Features

Your pet grows with context

The more context you use, the bigger your pet gets.

/\_____/\  ~            tiny    (< 20%)
( o w o )
( "   " )

/\_____________/\  ~     medium  (40-60%)
==( o   w   o )==
==( "       " )==

/\_________________________/\  ~     thicc   (> 80%)
====( o       w       o )====
====( "               " )====

5 species, 5 moods, 10 palettes

Each session randomly assigns a species and color palette (or set them in config).

/\_____/\  ~       (ovo)        {O,O}        ,---.        (\  /)
( o w o )         <(   )>      /)--(\\      ( O.O )      ( oYo )
( "   " )          (" ")        " "        /|~|~|\\       (")(")
   Cat            Penguin        Owl       Octopus        Bunny

| Mood | Trigger | Expression | |:-----|:--------|:-----------| | Idle | Normal | o ^ - blink cycle, ~ tail wag | | Happy | Tests pass, commit, recovery | ^ squinting eyes | | Busy | Claude streaming | Rapid eye cycle | | Danger | Context > 85% | O wide eyes, ! tail | | Sleep | Context < 10% | - closed eyes, z Z tail |

Palettes: Coral Flame · Electric Blue · Neon Mint · Purple Haze · Hot Pink · Golden Sun · Ice Violet · Cherry Blossom · Cyan Surge · Tangerine

Event-reactive mood (900+ messages)

Via the PostToolExecution hook, your pet knows what Claude is doing and reacts in real time.

| Event | Example message | |:------|:----------------| | Tests pass | "ALL GREEN! *happy dance*" | | Tests fail | "Tests tripped... you got this!" | | Build succeeds | "Clean build! *sparkling eyes*" | | Git commit | "Checkpoint saved! *relief*" | | Git push | "Go forth, little commits!" | | Fix after failure | "Redemption arc complete!" | | Multiple failures | "Hang in there! *warm hug*" | | Rapid editing | "Flow state detected! Beautiful~" | | Dangerous commands | "My insurance doesn't cover this..." | | Cat idle | "*knocks something off the desk*" | | Owl idle | "In my expert owl-pinion, this is going well" | | Octopus idle | "*squirts ink* Oops, that was the dark theme" | | Late night | "The whole world is asleep... except us" | | Easter egg | "I live in the statusline but you live in my heart" |

Messages are file-aware (shows the actual filename being edited), time-aware (morning/night/weekend), and relationship-aware (different messages for strangers vs besties).

Testing (pass/fail) · Building (pass/fail) · Installing packages · Git (commit, push, pull, merge, rebase, stash, checkout) · Linting/formatting · Server start · Docker/K8s · Network/HTTP · Dangerous commands · Search/grep · File editing by type (tests, docs, styles, config, code) · New file creation · Rapid editing · Code exploration · Recovery from errors · Struggling pattern (3+ failures) · Session milestones · Tier upgrades · Smart /compact suggestion

TypeScript · JavaScript · Python · Rust · Go · Ruby · Java · Kotlin · Swift · C/C++ · CSS · HTML · Vue · Svelte · Shell · SQL · Proto · GraphQL · Config · Docs · Tests

Pet memory

Your pet remembers you across sessions and levels up your relationship.

| Tier | After | Greeting | |:-----|:------|:---------| | Stranger | 0 sessions | "Oh! A new friend!" | | Acquaintance | 3 sessions | "Hey, good to see you again!" | | Friend | 15 sessions | "My favorite human is back!" | | Bestie | 50 sessions | "BESTIE! You're here! #50" |

Tier upgrades trigger a one-time celebration: "BESTIE STATUS UNLOCKED! WE DID IT!"

Smart /compact suggestion

When context is above 70% and burn speed is high, your pet gently suggests compacting — once per trigger, never nagging.

"Cache is getting cold... maybe /compact?"

Productivity dashboard

Run codachi stats any time for a local summary of your relationship with your pet — no network calls, no telemetry, everything read from ~/.claude/plugins/codachi/.

codachi stats — Mochi the cat

  first met    2026-01-12  (87d ago)
  last seen    2026-04-09
  sessions     73
  total uptime 4d12h
  avg session  89m

  relationship
  current      friend
  progress     ████████████████░░░░  80%
  next tier    bestie (23 more sessions)

  recent activity (last 24h from local events)
  events       142
  tests        18 pass · 3 fail
  commits      7
  edits        34

  this session 1h12m

Plugins

Drop an ES module into ~/.config/codachi/plugins/ to add custom palettes and message packs. Plugins are auto-loaded at startup — no registration, no imports in user code.

// ~/.config/codachi/plugins/midnight.mjs
export default {
  name: 'midnight',
  messages: {
    BUSY_MESSAGES: ['⌘ focused', '⌘ flow state'],
    EVENT_MESSAGES: {
      test_passed: ['green — ship it', '✓ all green'],
    },
  },
  palettes: [
    {
      name: 'Midnight',
      body:   [20, 30, 80],
      accent: [60, 80, 160],
      face:   [180, 190, 230],
      blush:  [120, 140, 200],
    },
  ],
};

Run codachi plugins to see what's loaded. Precedence is: locale file > plugin > English default, so translators still have the final word.

Available message keys: BUSY_MESSAGES, DANGER_MESSAGES, USAGE_HIGH_MESSAGES, VELOCITY_FAST, VELOCITY_SLOW, COMPACT_SUGGEST, IDLE_MESSAGES (per animal), SIZE_MESSAGES (per body size), WELCOME_MESSAGES (per tier), TIER_UPGRADE (per tier), RARE_EVENTS, EVENT_MESSAGES (per category), FILE_TYPE_MESSAGES (per language), GIT_CLEAN_MESSAGES / GIT_BUSY_MESSAGES / GIT_AHEAD_MESSAGES / GIT_BEHIND_MESSAGES / GIT_STASH_MESSAGES / GIT_WIP_MESSAGES.

Localization

Codachi ships with English (canonical source) and Simplified Chinese. Override any or all message keys with your own language:

CODACHI_LOCALE=zh   # or set LANG / LC_ALL on your OS

User overrides go in ~/.config/codachi/locales/<locale>.json — same key schema as plugins, partial files are fine (missing keys fall through to English). To contribute a language upstream, open a PR adding src/locales/<locale>.json.

Configuration

Run the interactive wizard:

node dist/index.js config

Or edit ~/.config/codachi/config.json directly:

{
  "name": "Mochi",
  "animal": "cat",
  "palette": 3,
  "widgets": ["model", "context", "velocity", "rateLimit5h", "rateLimit7d"]
}

| Option | Default | Description | |:-------|:--------|:------------| | name | species name | Custom pet name (e.g. "Mochi") | | animal | random | cat penguin owl octopus bunny | | palette | random | Color palette index 0–9 | | widgets | all shown | Line 1 widget order + visibility — see widgets below | | showTokens | true | Show token count 555K/1M | | showVelocity | true | Show burn speed ^3%/m + time remaining ~15m | | showGit | true | Show git status on line 2 | | animationSpeed | 1.5 | Seconds per animation frame |

Available widgets (line 1): model, context, velocity, rateLimit5h, rateLimit7d. Reorder or remove any of them in the widgets array.

Environment variables:

| Var | Purpose | |:----|:--------| | CODACHI_LOCALE | Force a locale (en, zh, etc.) — overrides LANG | | CODACHI_COLOR | Force color depth: truecolor | 256 | 16 | none | | CODACHI_NO_PLUGINS | Set to 1 to skip plugin scanning | | CODACHI_QUIET | Set to 1 to silence codachi.log writes | | CODACHI_DEBUG | Set to 1 to enable verbose debug logs | | NO_COLOR | Standard no-color opt-out (honored) | | FORCE_COLOR | Standard color force: 0–3 (honored) |

Debug log: errors land in ~/.claude/plugins/codachi/codachi.log (auto-rotated at 256KB). tail -f it if things look off.

How it works

Claude Code ──stdin:JSON──▶ codachi ──stdout:ANSI──▶ statusline
                 │
                 └──hook──▶ events.json ──▶ mood engine

| Property | Detail | |:---------|:-------| | Cost | Zero — hooks write to disk, no API calls, no tokens | | Speed | ~50ms render, git cached for 2s | | Persistence | Session state, memory, events in ~/.claude/plugins/codachi/ | | Reliability | Atomic writes (write-to-tmp + rename), graceful degradation | | Session binding | Pet identity tied to transcript_path from Claude Code | | Event freshness | Hot (< 15s), warm (< 60s), cold (< 5m) — priority decays over time | | Pattern detection | Struggling (3+ failures), recovery (fail → success), rapid editing (5+ in 60s) |

src/
├── index.ts           # Entry point + init/demo routing
├── init.ts            # One-command install (codachi init)
├── demo.ts            # Live terminal demo
├── hook.ts            # Claude Code PostToolExecution hook
├── events.ts          # Event classifier (40 categories)
├── mood.ts            # Mood engine (15-tier priority)
├── messages/          # 900+ messages split by category
│   ├── events.ts      #   Event-reactive messages
│   ├── idle.ts        #   Animal idle + body size messages
│   ├── context.ts     #   Velocity, cache, danger, busy
│   ├── social.ts      #   Welcome, tier upgrade, easter eggs
│   └── git.ts         #   Git status + file type messages
├── stdin.ts           # Parse Claude Code JSON input
├── git.ts             # Git status with 2s caching
├── state.ts           # Session, velocity, memory, tiers
├── config.ts          # User configuration
├── identity.ts        # Animal + palette selection (10 palettes)
├── project.ts         # Language detection (21 markers)
├── fs-utils.ts        # Atomic file writes
├── width.ts           # Terminal char width (CJK-aware)
├── types.ts           # TypeScript types
├── animals/           # 5 species × 5 sizes × 5 moods × 4 frames
└── render/            # 3-line ANSI compositor + truecolor

Development

npm install
npm run build          # compile TypeScript + copy locales to dist/
npm run dev            # watch mode
npm test               # 370 tests
npm run test:cov       # coverage report (91%+ lines)
npm run bench          # render p50/p95/p99 benchmark (budget: 50ms)

Record a demo GIF:

bash scripts/record-gif.sh     # requires asciinema + agg
# or
vhs scripts/demo.tape          # requires vhs

Related projects

• ccstatusline — Highly customizable statusline for Claude Code with powerline support, themes, and rich layout options. If codachi's pet is too much personality for your taste, ccstatusline is the polished, configurable alternative.

License

MIT