📦 Installation

Globally via npm (Node ≥ 18 required):

npm install -g cigarettes-for-claude

Or straight from this repo:

git clone <this-repo>
cd Cigarettes-For-Claude
npm install -g .

Afterward the commands cigarettes-for-claude and the short alias cfc are available. Electron is the only dependency and gets pulled in during install.

🚀 Usage

cfc            # launch mascot + cigarette as desktop windows
cfc --help     # help

cfc starts both windows detached in the background, prints a short notice, and exits right away — your terminal stays free:

🚬 Cigarettes for Claude is running (desktop). Quit: right-click the cigarette.

🤖 The desktop mascot

A small window that looks exactly like the orange Claude Code CLI logo. Its mood tracks the craving level:

• chill — everything relaxed, the occasional content *vibes* / life's good, man
• jittery — craving is rising, it starts fidgeting: context is getting heavy..., time for a /compact soon
• withdrawal meltdown — heavy context: violent shaking, color shifting toward red, loud demands: /compact. NOW., CONTEXT OVERFLOW — /compact!

🚬 Smoking = /compact

The cigarette is /compact. Compacting the context is the one action that actually shrinks the thing craving is made of (context tokens), so it has no downside — and it keeps craving low without needing to "smoke" often.

A PreCompact hook makes every compaction a cigarette: whether you run /compact yourself or Claude Code auto-compacts, the plugin resets craving, records the smoke, and (if the desktop app is running) triggers the mascot's smoking animation. No fictional cigarette required — the real, useful action is the cigarette.

Zero extra chat tokens. The plugin injects no roleplay or personality into the conversation — Claude just works normally. The only nudge is the /compact suggestion in the statusline (and the desktop mascot), so it never spends tokens generating smoker commentary.

🧩 Claude Code plugin

The plugin measures Claude's context usage in real time, surfaces a craving meter, and suggests /compact when the context gets heavy.

In Claude Code:

/plugin marketplace add /path/to/repo
/plugin install cigarettes-for-claude

Just work normally — when craving climbs, the statusline starts suggesting /compact. Run it and the meter resets. There's also a manual /smoke command that resets the meter without compacting (handy for the desktop toy), but /compact is the real thing.

Optional statusline — the current state right in Claude Code. In ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "node /path/to/repo/plugin/statusline.js"
  }
}

Result: 🚬 ▓▓▓▓▓░░░ Craving 62% · 124k since last smoke · 🚬×3 today — the craving bar, how many tokens have passed since the last cigarette, and (once you've smoked at least once today) the daily cigarette tally. Once craving gets heavy the line ends with · /compact to clear, and during withdrawal the icon blinks and Craving X% becomes WITHDRAWAL!.

📊 Smoke stats & milestones

Every cigarette is counted. Compacting (via the PreCompact hook), /smoke, and dragging a lit cigarette onto the mascot all record the smoke: a lifetime total (cigarettesSmoked) plus a per-day tally (cigarettesToday) that rolls over at midnight (UTC). The daily count shows up in the statusline, and each fresh smoke makes the desktop mascot celebrate with a little burst of floating hearts and a #N today pop — every 5th cigarette gets an extra-big cheer.

⚙️ How it works

Everything hangs off a single state file:

~/.cigarettes-for-claude/state.json

(overridable via CFC_STATE_DIR). The plugin writes how much Claude is working — after every tool call, not just at the end of a turn, so the craving bar and mascot mood update live while Claude works. The mascot, cigarette, and statusline all read from the same file. Deleting it = instant, painless cold turkey.

Craving formula:

craving = clamp(round(tasks * 5 + tokens / 2000), 0, 100)

So +5% per completed task, plus ~1% per 2,000 context tokens burned. Smoking (i.e. /compact, /smoke, or a handover on the desktop) resets both to 0. Because /compact also drops the underlying context, craving stays low far longer afterward.

Tiers (mood):

| Craving | State | Mascot | |-----------|------------|----------------------| | 0–24% | relaxed | chill | | 25–59% | normal | chill | | 60–84% | craving | jittery | | 85–100% | withdrawal | meltdown |

During withdrawal the mascot shakes violently, demands a /compact, and the statusline blinks. Time to run /compact (or /smoke, or drag a cigarette over on the desktop) — or the mascot will come get it itself.

License

MIT © Mika Stiebitz