Cheesyboy

Prerequisites

Before installing Cheesyboy, make sure you have the following:

• macOS or Linux (Windows is listed in the package manifest but macOS is the primary supported platform)
• Node.js 18 or higher — check with node --version
• npm — bundled with Node.js; check with npm --version
• Claude Code installed and initialized (the ~/.claude/ directory must exist)
• A Telegram account — you'll create a bot during setup
• A Cheesyboy license key — purchase at cheesyboy.com for $9.99 (lifetime)

---

Get Your API Keys

You need two values from Telegram before running the setup wizard.

1. Telegram Bot Token

1. Open Telegram and search for @BotFather

2. Start a chat and send /newbot

3. Follow the prompts — choose a name and a username ending in bot

4. BotFather will reply with a token that looks like:

   110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw
   

5. Copy and save this — it's your TELEGRAM_BOT_TOKEN

2. Telegram Chat ID

1. Open Telegram and search for @userinfobot
2. Start a chat and send /start
3. The bot will reply with your numeric user ID, e.g. 123456789
4. Copy this — it's your TELEGRAM_CHAT_ID

3. Cheesyboy License Key

After purchasing at cheesyboy.dev, you'll receive a license key by email in the format:

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Keep this handy — the setup wizard will ask for it.

---

Installation

Option A — One-command installer (recommended)

bash <(curl -fsSL https://cheesyboy.dev/install.sh)

This script handles the full setup including dependencies and service registration.

Option B — npm global install

npm install -g @selucas12/cheesy

Then run the interactive setup wizard:

cheesy init

The wizard will:

1. Check that Node.js ≥ 18 is installed and ~/.claude/ exists
2. Prompt for your Telegram bot token and chat ID
3. Install the bot files to ~/.ccgram/
4. Merge the required hooks into ~/.claude/settings.json
5. Register and start a background service (launchd on macOS, systemd on Linux)
6. Prompt for your license key

Option C — Headless / automated install

If you want to skip all interactive prompts, export the required variables before running cheesy init:

export LICENSE_KEY=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
export TELEGRAM_BOT_TOKEN=110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw
export TELEGRAM_CHAT_ID=123456789

cheesy init

---

Configuration

Cheesyboy stores its configuration in ~/.ccgram/.env. The setup wizard populates this file automatically, but you can edit it manually if needed.

| Variable | Description | Where to get it | |----------|-------------|-----------------| | TELEGRAM_BOT_TOKEN | The HTTP API token for your Telegram bot | @BotFather on Telegram | | TELEGRAM_CHAT_ID | Your personal Telegram numeric user ID | @userinfobot on Telegram | | LICENSE_KEY | Your LemonSqueezy license key for Cheesyboy | Email receipt after purchasing at cheesyboy.dev |

A template for the .env file is available at ~/.ccgram/.env.example after installation.

---

Running the Bot

Start (production)

The setup wizard registers Cheesyboy as a background service that starts automatically. To start it manually:

cheesy start

Stop

cheesy stop

Check status

cheesy status

Activate a license (if skipped during setup)

cheesy license activate XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Development / testing mode (no license required)

If you want to run without a license key for local testing:

cheesy init --dev

This writes a dev marker at ~/.ccgram/.license-dev and bypasses license validation. To switch to a real license later:

cheesy license activate XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

The dev marker is cleared automatically once a valid license is activated.

---

Testing

After the bot is running, verify the integration end to end:

1. Check the bot is alive — send /start to your bot in Telegram. It should reply with a welcome message.

2. Check Claude Code hook installation — confirm the hooks were written to Claude's settings:

   cat ~/.claude/settings.json | grep -A 5 "hooks"
   

   You should see Cheesyboy hook entries in the output.

3. Check the background service — confirm the bot process is running:

   cheesy status
   

4. Trigger a live event — open a Claude Code session in your terminal and run a task that requires a permission prompt (e.g., writing a file). You should receive a Telegram message with Allow / Deny / Always / Defer buttons within a few seconds.

5. Check session status from Telegram — send /status to your bot. It should reply with the current model, git branch, session ID, and context window usage.

---

Troubleshooting

| Problem | Likely cause | Fix | |---------|-------------|-----| | cheesy: command not found after npm install | npm global bin directory is not in your PATH | Run npm bin -g to find the global bin path, then add it to your shell profile (e.g., export PATH="$(npm bin -g):$PATH" in ~/.zshrc) | | Bot starts but Telegram messages never arrive | Wrong TELEGRAM_CHAT_ID or TELEGRAM_BOT_TOKEN | Double-check both values in ~/.ccgram/.env against what BotFather and @userinfobot provided. Restart with cheesy stop && cheesy start after editing | | cheesy start exits immediately with a license error | No valid license activated and not in dev mode | Run cheesy license activate <YOUR_KEY> with the key from your email, or run cheesy init --dev for local testing | | Permission prompts appear in terminal but not in Telegram | Claude Code hooks were not installed correctly | Re-run cheesy init and confirm it reports merging hooks into ~/.claude/settings.json. Check that file contains the hook entries manually | | Bot was working, then stopped after a system restart | Background service not registered or failed to load | Run cheesy status to check. If the service is not running, run cheesy start. If the service is missing, re-run cheesy init to re-register it | | ~/.claude/ does not exist error during init | Claude Code has not been run yet | Launch Claude Code at least once so it initializes its config directory, then re-run cheesy init |

For issues not covered here, check the GitHub issue tracker or the project README for additional details.