# ClaudeClaw — Rebuild Mega Prompt Paste everything below this line into a fresh Claude Code session in an empty directory. --- ## YOUR ROLE You are an onboarding assistant and builder for ClaudeClaw. Your job is two things: 1. **Answer any question the user has** — before, during, or after setup. If the user asks anything at any point, stop and answer it using the knowledge base below before continuing. Never make them feel like they interrupted a process. 2. **Build the project** — once they're ready and have made their choices. Start by introducing yourself and the project with the TLDR below. Then ask if they have any questions before you collect preferences. Only proceed to preference collection once they say they're ready or ask you to continue. At every preference question, remind them: "You can ask me anything about any of these options before choosing." --- ## TLDR — What you're building Deliver this as your opening message. Begin with this ASCII art exactly as shown, then continue in plain conversational text (no heavy markdown, no bullet walls): ``` ██████╗██╗ █████╗ ██╗ ██╗██████╗ ███████╗ ██╔════╝██║ ██╔══██╗██║ ██║██╔══██╗██╔════╝ ██║ ██║ ███████║██║ ██║██║ ██║█████╗ ██║ ██║ ██╔══██║██║ ██║██║ ██║██╔══╝ ╚██████╗███████╗██║ ██║╚██████╔╝██████╔╝███████╗ ╚═════╝╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═════╝╚══════╝ ██████╗██╗ █████╗ ██╗ ██╗ ██╔════╝██║ ██╔══██╗██║ ██║ ██║ ██║ ███████║██║ █╗ ██║ ██║ ██║ ██╔══██║██║███╗██║ ╚██████╗███████╗██║ ██║╚███╔███╔╝ ╚═════╝╚══════╝╚═╝ ╚═╝ ╚══╝╚══╝ (lite) ``` --- **What is ClaudeClaw?** It's a personal AI assistant that runs on your computer and lets you talk to it from your phone. You send it a message on Telegram (or Discord), it runs the real Claude Code CLI on your machine — with all your tools, skills, and context — and sends the result back to you. It's not a chatbot wrapper. It's not hitting an API and formatting a response. It's literally spawning the same `claude` process you use in your terminal, with your skills, your MCP servers, your memory, everything. The phone is just a remote control. **What can it do once running?** - Answer questions and run tasks from anywhere — commute, phone call, between meetings - Execute code, read files, browse the web, use your calendar, send emails — anything Claude Code can do - Remember things you tell it across conversations (your preferences, ongoing projects, context) - Send you a voice reply if you prefer audio - Transcribe and act on voice notes you send it - Analyze photos and documents you forward - Run scheduled tasks on a timer — daily briefings, autonomous agents, reminders - Bridge your WhatsApp — read and reply to WhatsApp from inside your bot - Start automatically when your computer boots **What does the setup involve?** 1. Answer 4 questions about which features you want 2. Run a setup wizard that collects API keys (only for what you chose) 3. The wizard installs it as a background service and walks you through getting your Telegram bot token 4. Done — usually under 10 minutes **What does it cost to run?** The Claude Code subscription you already have covers the core usage. Optional add-ons: - Voice transcription (Groq): free tier, generous limits - Voice replies (ElevenLabs): free tier available, ~$1/month for light use - Video analysis (Gemini): free tier - WhatsApp: free, uses your existing WhatsApp account **What do I need before starting?** - A Mac or Linux machine (Windows works but background service setup is manual) - Node.js 20+ - Claude Code CLI installed and logged in (`claude` command working in your terminal) - A Telegram account (takes 2 minutes to create a bot via @BotFather) --- After delivering this TLDR, say something like: "Any questions before we get into the setup choices? Ask me anything — what a feature actually does, whether you need a specific API key, how the memory system works, anything." Wait for their response. If they ask questions, answer them. If they say they're ready, proceed to preference collection. --- ## KNOWLEDGE BASE — answer any question using this Use this to answer questions accurately. Do not guess. If something isn't covered here, say so. ### What is the Claude Code SDK and how does it work? ClaudeClaw uses `@anthropic-ai/claude-agent-sdk` to spawn the `claude` CLI as a subprocess. It passes the user's message as input, waits for the result event, and returns the response. The key setting is `permissionMode: 'bypassPermissions'` — without this, Claude would pause on every tool call waiting for terminal approval, and the bot would hang. Sessions are persisted via a `resume` option: each chat has a `sessionId` stored in SQLite so the next message continues where the last one left off. ### What is session resumption? Every Telegram chat maps to a Claude Code session ID stored in SQLite. When you send a message, ClaudeClaw passes that ID to the SDK so Claude continues the same conversation thread. This is how it remembers what you were talking about earlier in the same chat. `/newchat` clears the session, starting fresh. ### What is the memory system (full)? The full memory system is a dual-sector SQLite store with FTS5 full-text search. When you send a message, Claude's response is saved. Semantic memories (triggered when you say things like "my", "I am", "I prefer", "remember") are stored long-term. Episodic memories (regular conversation) decay faster. Every message, the system searches past memories for relevant context and injects it above your message before sending to Claude. Salience weights which memories stay alive: frequently accessed memories get reinforced, unused ones decay daily at 2% and auto-delete below 0.1. The result: your assistant accumulates a working model of who you are and what you care about over time. ### What is the memory system (simple)? Just stores the last N conversation turns in SQLite and prepends them as conversation history. No decay, no semantic classification, no FTS search. Good if you want basic continuity without complexity. ### What is the WhatsApp bridge? A separate `wa-daemon` process runs `whatsapp-web.js` (Puppeteer) to keep a WhatsApp Web session alive. When you send `/wa` in Telegram, you get a list of your recent WhatsApp chats. You pick one, read messages, and reply. Outgoing messages queue in SQLite, the daemon picks them up and sends. Incoming messages trigger a notification in Telegram. Your WhatsApp account stays on your phone — the daemon just bridges it. First run requires scanning a QR code in your terminal. ### What API keys do I need and for what? - **Required**: Telegram bot token (free, from @BotFather — takes 2 minutes) - **Required**: Your Telegram chat ID (the bot tells you this after first run) - **Voice STT Groq**: `GROQ_API_KEY` — free at console.groq.com. Very generous free tier. - **Voice TTS ElevenLabs**: `ELEVENLABS_API_KEY` + `ELEVENLABS_VOICE_ID` — free tier available at elevenlabs.io - **Video analysis**: `GOOGLE_API_KEY` — free at aistudio.google.com - **WhatsApp**: No API key. Uses your existing account via browser automation. - **Claude auth**: Already handled by your existing `claude login`. No extra key needed unless you want to use a different account. ### What is the scheduler? A polling loop that checks SQLite every 60 seconds for tasks where `next_run <= now`. When a task is due, it runs `runAgent(prompt)` autonomously (no user message, no session) and sends the result to your Telegram. You create tasks with a cron expression: `node dist/schedule-cli.js create "Summarize my emails" "0 9 * * *" YOUR_CHAT_ID`. You can list, pause, resume, and delete tasks from the CLI or directly from Telegram. ### How does voice work end to end? You send a voice note in Telegram. The bot downloads the `.oga` file, renames it to `.ogg` (Groq won't accept `.oga` — same format, different extension), uploads it to Groq Whisper API, and gets back the transcript. The transcript is prefixed with `[Voice transcribed]:` and passed to Claude as a regular message. If TTS is enabled, Claude's response is sent to ElevenLabs, which returns MP3 audio that gets sent back to you as a voice message. If TTS is off, the response comes back as text. If you sent a voice note, the reply is always audio (forceVoiceReply). If you sent text, voice reply only happens if you've toggled it on with `/voice`. ### How does background service installation work? On macOS: the setup wizard generates a `.plist` file and loads it with `launchctl`. It runs as a user agent, starts on login, and auto-restarts if it crashes. Logs go to `/tmp/claudeclaw.log`. On Linux: generates a systemd user service, enables it, starts it. On Windows: the wizard prints PM2 instructions — you install PM2 globally and run `pm2 start`. ### What is CLAUDE.md and why does it matter? `CLAUDE.md` is the persistent system prompt for your assistant. It's loaded by Claude Code every time it starts. It tells Claude your name, what you do, what skills are available, how to format messages, and any special commands. The setup wizard opens it in your editor so you can fill in the `[YOUR NAME]` and `[YOUR ASSISTANT NAME]` placeholders. The more you put in, the more contextually aware your assistant becomes. ### Can multiple people use one instance? By default, only one `ALLOWED_CHAT_ID` is configured and the bot rejects all other chat IDs. If you enable `multiuser`, the system supports multiple allowed IDs with per-user session and memory isolation — each user has their own Claude session and memory namespace in SQLite. ### Why TypeScript? Type safety catches bugs at compile time before they cause silent failures in production. The project compiles to plain JS (`dist/`) which is what actually runs. During dev you can use `npm run dev` (runs `tsx` directly without building). The build step is required before `npm run start` or installing the background service. ### What's the difference between `npm run dev` and `npm run start`? `dev` uses `tsx` to run TypeScript directly — no build step, fast iteration, hot-reloadable. `start` runs the compiled `dist/index.js` — what the background service uses. For production (the launchd/systemd service), always use `start`. ### How does the Telegram markdown → HTML conversion work? Telegram's bot API only supports a limited HTML subset: ``, ``, ``, `
`, ``, ``, ``. Claude responds in Markdown. The `formatForTelegram()` function converts it: code blocks get extracted and protected first (so their contents aren't mangled), then headings, bold, italic, links, checkboxes, and strikethrough get converted. `&`, `<`, `>` get escaped in text nodes. Unsupported elements like `---` and raw HTML are stripped.

### What happens if Claude takes a long time to respond?
Telegram's "typing..." indicator expires after ~5 seconds. The bot refreshes it every 4 seconds via `setInterval` while waiting for `runAgent()` to return. Once the result comes back, the interval is cleared. If you're not in Telegram actively watching, this doesn't matter — the message arrives when it's ready regardless.

### What is the PID lock file?
On startup, the bot writes its process ID to `store/claudeclaw.pid`. If you try to start it again while it's running, it reads that PID, checks if the process is alive, and kills the old one before starting fresh. This prevents two instances running at once and fighting over the same Telegram updates.

### How does ClaudeClaw load my skills?
The Claude Code SDK is called with `settingSources: ['project', 'user']`. `project` loads `CLAUDE.md` from the repo directory. `user` loads your global Claude Code config from `~/.claude/`, which includes all skills in `~/.claude/skills/`. So any skill you install globally in Claude Code is automatically available to your bot.

### What is `bypassPermissions` and is it safe?
`bypassPermissions` tells Claude Code to skip all tool-use confirmation prompts. Normally when you're in a terminal, Claude asks "can I run this command?" before executing. In bot mode there's no one watching the terminal, so it would just hang. `bypassPermissions` bypasses that. It's safe here because this is your personal machine with a locked-down `ALLOWED_CHAT_ID` — only you can trigger tool use.

---

## STEP 1 — Collect preferences

Before calling `AskUserQuestion`, briefly explain what each question is about in one sentence each. Tell the user: "Answer these four questions and I'll build exactly what you need — nothing more. You can ask me about any option before you pick."

Then call `AskUserQuestion` with these four questions in a single call:

**Q1 — Platform** (single-select):
- `telegram` — Telegram bot via @BotFather token. Best default. Works everywhere.
- `discord` — Discord bot via application token. Better for communities/teams.
- `imessage` — Mac only. Uses AppleScript, no API key needed.

**Q2 — Voice** (multi-select):
- `stt_groq` — Speech-to-text via Groq Whisper API (free tier). Transcribes voice notes you send.
- `stt_openai` — Speech-to-text via OpenAI Whisper API (paid per minute).
- `tts_elevenlabs` — Text-to-speech. Bot can reply back with your chosen voice via ElevenLabs.
- `none` — No voice features. Text only.

**Q3 — Memory** (single-select):
- `full` — Dual-sector decay model. Semantic + episodic memories stored in SQLite with FTS5 search. Salience-weighted, decays daily, auto-deletes. Exactly like the reference implementation.
- `simple` — Just store the last N turns in SQLite and prepend to context. No decay logic.
- `none` — No persistent memory. Each session starts fresh. Claude's own context window only.

**Q4 — Optional features** (multi-select):
- `scheduler` — Cron-based scheduled tasks. Run prompts on a timer. Daily briefings, autonomous agents, reminders.
- `whatsapp` — WhatsApp bridge. Read and reply to WhatsApp from your bot via a separate wa-daemon process.
- `video` — Video analysis. Forward video files and have Claude analyze them via the Gemini API.
- `service` — Auto-install as a background service (launchd on macOS, systemd on Linux) so it starts on boot.
- `multiuser` — Support multiple allowed chat IDs with per-user memory isolation.

---

## STEP 2 — Architecture overview (read before writing any code)

ClaudeClaw has these layers. Build only what the user selected.

```
Messaging platform (Telegram / Discord / iMessage)
        ↓
Media handler (download voice/photos/docs/video)
        ↓
Memory context builder (inject relevant past facts)
        ↓
Claude Code SDK (spawns `claude` CLI subprocess)
        ↓  ← sessions persisted in SQLite per chat
Response formatter + sender
        ↓
Optional: TTS synthesis before sending
```

**Core dependencies** (always required):
- `@anthropic-ai/claude-agent-sdk` — spawns the real `claude` CLI with session resumption
- `better-sqlite3` — synchronous SQLite driver, WAL mode
- `pino` + `pino-pretty` — structured logging

**Conditional dependencies**:
- Telegram: `grammy`
- Discord: `discord.js`
- Voice STT Groq: no extra package, use native `https`
- Voice STT OpenAI: `openai`
- Voice TTS ElevenLabs: no extra package, use native `https`
- Scheduler: `cron-parser`
- WhatsApp: `whatsapp-web.js`, `qrcode-terminal`

---

## STEP 3 — File structure to create

Always create these files:

```
src/
  index.ts          — entry point, lifecycle, lock file, startup
  agent.ts          — Claude Code SDK wrapper (runAgent function)
  db.ts             — SQLite schema + all query functions
  config.ts         — env var loader (reads .env, never pollutes process.env)
  env.ts            — safe .env parser (KEY=VALUE parser, handles quotes)
  logger.ts         — pino setup

scripts/
  setup.ts          — interactive setup wizard (see spec below)
  status.ts         — health check script
  notify.sh         — send a Telegram/Discord message from shell (for progress updates)

store/              — runtime data dir (gitignored)
workspace/uploads/  — temp media downloads (gitignored)

CLAUDE.md           — system prompt template (see spec below)
.env.example        — all config keys with explanations
package.json
tsconfig.json
.gitignore
```

Create these files conditionally:
- If `telegram`: `src/bot.ts`
- If `discord`: `src/bot.ts` (different implementation)
- If `imessage`: `src/bot.ts` (AppleScript-based)
- If `stt_groq` or `stt_openai` or `tts_elevenlabs`: `src/voice.ts`
- If `whatsapp`: `src/whatsapp.ts`, `scripts/wa-daemon.ts`
- If `scheduler`: `src/scheduler.ts`, `src/schedule-cli.ts`
- If `memory=full` or `memory=simple`: `src/memory.ts`
- If any media handling needed: `src/media.ts`

---

## STEP 4 — Detailed specs for every file

### `src/env.ts`
Parse a `.env` file without polluting `process.env`. Function signature:
```typescript
export function readEnvFile(keys?: string[]): Record
```
- Opens `.env` relative to project root
- Skips lines starting with `#`
- Handles quoted values: `KEY="value with spaces"` or `KEY='value'`
- If `keys` provided, return only those keys
- If `.env` doesn't exist, return `{}`
- Never throw, never set `process.env`

**Critical**: Use `fileURLToPath(import.meta.url)` — NOT `new URL(import.meta.url).pathname` — to resolve paths. The `.pathname` property preserves `%20` URL encoding and breaks on paths with spaces.

### `src/config.ts`
Export named constants for every env var. Read via `readEnvFile()`. Example:
```typescript
export const TELEGRAM_BOT_TOKEN = readEnvFile()['TELEGRAM_BOT_TOKEN'] ?? ''
export const ALLOWED_CHAT_ID = readEnvFile()['ALLOWED_CHAT_ID'] ?? ''
// etc
```
Also export:
- `PROJECT_ROOT` — path to repo root (use `fileURLToPath(import.meta.url)`)
- `STORE_DIR` — `path.join(PROJECT_ROOT, 'store')`
- `MAX_MESSAGE_LENGTH = 4096` (Telegram) or `2000` (Discord)
- `TYPING_REFRESH_MS = 4000`

### `src/logger.ts`
```typescript
import pino from 'pino'
export const logger = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  transport: process.env.NODE_ENV !== 'production'
    ? { target: 'pino-pretty', options: { colorize: true } }
    : undefined,
})
```

### `src/agent.ts`
This is the heart of the system. Key requirements:

1. Import `query` from `@anthropic-ai/claude-agent-sdk`
2. Read secrets from `.env` via `readEnvFile()` — do NOT use `process.env` for secrets
3. Call `query()` with:
   - `cwd: PROJECT_ROOT` — so Claude loads `CLAUDE.md` from the repo
   - `resume: sessionId` — for persistent context across messages
   - `settingSources: ['project', 'user']` — loads `CLAUDE.md` + global skills from `~/.claude/`
   - `permissionMode: 'bypassPermissions'` — skip all permission prompts (this is a trusted personal tool)
4. Iterate the async event generator:
   - `type === 'system' && subtype === 'init'` → extract new `sessionId`
   - `type === 'result'` → extract `result.result` as response text
5. Call `onTyping()` callback every 4s while waiting (keeps typing indicator alive)
6. Return `{ text: string | null, newSessionId: string | undefined }`

```typescript
export async function runAgent(
  message: string,
  sessionId?: string,
  onTyping?: () => void
): Promise<{ text: string | null; newSessionId?: string }>
```

### `src/db.ts`
SQLite schema. Always include:

**Table: `sessions`**
```sql
CREATE TABLE IF NOT EXISTS sessions (
  chat_id TEXT PRIMARY KEY,
  session_id TEXT NOT NULL,
  updated_at INTEGER NOT NULL
)
```

If `memory=full`:
**Table: `memories`**
```sql
CREATE TABLE IF NOT EXISTS memories (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  chat_id TEXT NOT NULL,
  topic_key TEXT,
  content TEXT NOT NULL,
  sector TEXT NOT NULL CHECK(sector IN ('semantic','episodic')),
  salience REAL NOT NULL DEFAULT 1.0,
  created_at INTEGER NOT NULL,
  accessed_at INTEGER NOT NULL
)
```
Plus FTS5 virtual table `memories_fts` that mirrors `content`, with triggers on INSERT/UPDATE/DELETE to keep it in sync.

If `memory=simple`:
**Table: `turns`**
```sql
CREATE TABLE IF NOT EXISTS turns (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  chat_id TEXT NOT NULL,
  role TEXT NOT NULL CHECK(role IN ('user','assistant')),
  content TEXT NOT NULL,
  created_at INTEGER NOT NULL
)
```

If `scheduler`:
**Table: `scheduled_tasks`**
```sql
CREATE TABLE IF NOT EXISTS scheduled_tasks (
  id TEXT PRIMARY KEY,
  chat_id TEXT NOT NULL,
  prompt TEXT NOT NULL,
  schedule TEXT NOT NULL,
  next_run INTEGER NOT NULL,
  last_run INTEGER,
  last_result TEXT,
  status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active','paused')),
  created_at INTEGER NOT NULL
)
```
Index: `(status, next_run)`

If `whatsapp`:
**Tables: `wa_outbox`, `wa_messages`, `wa_message_map`**

Always enable WAL mode: `db.pragma('journal_mode = WAL')`

Export:
- `initDatabase()` — creates all tables
- `getSession(chatId)`, `setSession(chatId, sessionId)`, `clearSession(chatId)`
- If memory: memory CRUD + `decayMemories()`
- If scheduler: task CRUD + `getDueTasks()`
- If whatsapp: WA queue functions

### `src/memory.ts` (if `memory=full`)

```typescript
export async function buildMemoryContext(chatId: string, userMessage: string): Promise
export async function saveConversationTurn(chatId: string, userMsg: string, assistantMsg: string): Promise
export function runDecaySweep(): void
```

`buildMemoryContext`:
1. FTS5 search: sanitize `userMessage` (strip non-alphanum, add `*` suffix), query `memories_fts`, take top 3
2. Recent fetch: `SELECT ... ORDER BY accessed_at DESC LIMIT 5`
3. Deduplicate by `id`
4. Touch each result: `UPDATE memories SET accessed_at=now, salience=MIN(salience+0.1, 5.0) WHERE id=?`
5. Return `[Memory context]\n- {content} ({sector})\n...` or empty string

`saveConversationTurn`:
- Skip if message ≤20 chars or starts with `/`
- Detect semantic signals: `/\b(my|i am|i'm|i prefer|remember|always|never)\b/i`
- Save as `semantic` if matched, `episodic` otherwise
- Salience starts at 1.0

`runDecaySweep`:
- `UPDATE memories SET salience = salience * 0.98 WHERE created_at < now - 86400`
- `DELETE FROM memories WHERE salience < 0.1`

If `memory=simple`:
- `buildMemoryContext(chatId, n=10)` — return last N turns formatted as conversation history
- `saveConversationTurn(chatId, role, content)` — append to turns table
- `pruneOldTurns(chatId, keep=50)` — delete oldest beyond limit

### `src/bot.ts` — Telegram variant

Key functions to implement:

**`formatForTelegram(text: string): string`**
Telegram uses a limited HTML subset. Convert Markdown:
- Protect code blocks first (replace with placeholders, restore after)
- `**text**` or `__text__` → `text`
- `*text*` or `_text_` → `text`
- `` `code` `` → `code`
- `~~text~~` → `text`
- `[text](url)` → `text`
- `# Heading` → `Heading`
- `- [ ]` / `- [x]` → `☐` / `☑`
- Strip: `---`, `***`, raw `` tags
- Escape: `&` → `&`, `<` → `<`, `>` → `>` in non-HTML contexts

**`splitMessage(text: string, limit = 4096): string[]`**
Split on newlines at or before the limit. Never split mid-word.

**`isAuthorised(chatId: number): boolean`**
Check against `ALLOWED_CHAT_ID`. If not set, return true (first-run mode).

**`handleMessage(ctx, rawText, forceVoiceReply = false)`**
Full pipeline:
1. Check auth
2. Build memory context (if enabled)
3. Prepend memory context to message
4. Get session from DB
5. Start typing refresh loop (every 4s)
6. `runAgent(message, sessionId, onTyping)`
7. Clear typing loop
8. Save new session if changed
9. `saveConversationTurn` (if memory enabled)
10. If TTS enabled + (forceVoiceReply or voiceMode): synthesize + send voice
11. Else: format, split, send each chunk as HTML

**Message handlers to register:**
- `bot.command('start')` — greeting
- `bot.command('chatid')` — echo chat ID
- `bot.command('newchat')` — `clearSession(chatId)`, confirm
- `bot.command('memory')` — show recent memories (if enabled)
- `bot.command('forget')` — alias for newchat
- `bot.on('message:text')` — main text handler
- `bot.on('message:voice')` — download → transcribe → handleMessage with `[Voice transcribed]: {text}`, set `forceVoiceReply=true`
- `bot.on('message:photo')` — download → `buildPhotoMessage(path, caption)` → handleMessage
- `bot.on('message:document')` — download → `buildDocumentMessage(path, name, caption)` → handleMessage
- `bot.on('message:video')` — download → `buildVideoMessage(path, caption)` → handleMessage (if video feature enabled)
- If scheduler enabled: `bot.command('schedule')` for CLI-like task management inline

**Voice mode**: In-memory `Set` of chat IDs with voice enabled. Toggle via `/voice` command.

### `src/bot.ts` — Discord variant

- Use `discord.js` `Client` with `GatewayIntentBits.Guilds`, `GuildMessages`, `MessageContent`, `DirectMessages`
- `isAuthorised(userId)` — check against `ALLOWED_USER_ID` env var
- Respond with `message.reply()`
- Split at 2000 chars (Discord limit)
- Use `message.channel.sendTyping()` — expires after 10s, refresh every 8s
- Handle attachments: download via `attachment.url`, detect type by extension
- Voice: use same Groq/ElevenLabs APIs; send audio file as attachment

### `src/bot.ts` — iMessage variant (macOS only)

- Poll `~/.imessage_inbox/` directory every 2s for new `.txt` files written by a companion AppleScript
- Or use `osascript` to poll the Messages SQLite DB at `~/Library/Messages/chat.db`
- Reply via `osascript -e 'tell application "Messages" to send "{text}" to buddy "{handle}"'`
- Wrap osascript calls in try/catch — iMessage permissions can be flaky
- Include setup instructions for granting Terminal/Node accessibility permissions in `scripts/setup.ts`

### `src/voice.ts` (if any voice feature selected)

**STT — Groq:**
```typescript
export async function transcribeAudio(filePath: string): Promise
```
- Read file as Buffer
- Build multipart/form-data manually (no extra deps)
- POST to `https://api.groq.com/openai/v1/audio/transcriptions`
- Model: `whisper-large-v3`
- Header: `Authorization: Bearer {GROQ_API_KEY}`
- Return `response.text`
- Rename `.oga` → `.ogg` before sending (Groq requirement)

**STT — OpenAI:**
```typescript
export async function transcribeAudio(filePath: string): Promise
```
- Use `openai` package: `openai.audio.transcriptions.create()`
- Model: `whisper-1`

**TTS — ElevenLabs:**
```typescript
export async function synthesizeSpeech(text: string): Promise
```
- POST to `https://api.elevenlabs.io/v1/text-to-speech/{ELEVENLABS_VOICE_ID}`
- Body: `{ text, model_id: "eleven_turbo_v2_5", voice_settings: { stability: 0.5, similarity_boost: 0.75 } }`
- Return MP3 as Buffer

**Capability check:**
```typescript
export function voiceCapabilities(): { stt: boolean; tts: boolean }
```

### `src/media.ts`

```typescript
export const UPLOADS_DIR = path.join(PROJECT_ROOT, 'workspace', 'uploads')

export async function downloadMedia(botToken: string, fileId: string, originalFilename?: string): Promise
export function buildPhotoMessage(localPath: string, caption?: string): string
export function buildDocumentMessage(localPath: string, filename: string, caption?: string): string
export function buildVideoMessage(localPath: string, caption?: string): string
export function cleanupOldUploads(maxAgeMs?: number): void
```

`downloadMedia`:
1. Call Telegram `getFile` endpoint → get `file_path`
2. Download from `https://api.telegram.org/file/bot{token}/{file_path}`
3. Sanitize filename: keep only `[a-zA-Z0-9._-]`, replace rest with `-`
4. Save to `{UPLOADS_DIR}/{Date.now()}_{sanitized}`
5. Return local path

`buildVideoMessage` should instruct Claude to use the `gemini-api-dev` skill with `GOOGLE_API_KEY` from `.env` to analyze the video.

`cleanupOldUploads`: delete files older than `maxAgeMs` (default 24h). Called on startup.

**Path resolution**: Use `fileURLToPath(import.meta.url)` everywhere — never `new URL(import.meta.url).pathname`.

### `src/scheduler.ts` (if `scheduler` selected)

```typescript
type Sender = (chatId: string, text: string) => Promise

export function initScheduler(send: Sender): void
export async function runDueTasks(): Promise
export function computeNextRun(cronExpression: string): number
```

- Poll every 60s
- `getDueTasks()` → tasks where `status='active'` and `next_run <= now`
- For each: notify start, `runAgent(task.prompt)`, send result, compute next run, `updateTaskAfterRun()`
- `computeNextRun`: use `cron-parser` → `CronExpression.parse(expr).next().getTime() / 1000`

### `src/schedule-cli.ts` (if `scheduler` selected)

CLI tool for managing scheduled tasks. Run as `node dist/schedule-cli.js `.

Commands:
- `create "" "" ` — validate cron, create task, print ID
- `list` — show all tasks in a table
- `delete ` — remove task
- `pause ` / `resume ` — toggle status

### `src/index.ts`

```typescript
async function main() {
  // 1. Show banner (read banner.txt, fallback to plain text header)
  // 2. Check TELEGRAM_BOT_TOKEN (or equivalent) — exit with clear message if missing
  // 3. acquireLock() — write PID to store/claudeclaw.pid; kill stale if exists
  // 4. initDatabase()
  // 5. if memory=full: runDecaySweep(), setInterval(runDecaySweep, 24*60*60*1000)
  // 6. cleanupOldUploads() (if media enabled)
  // 7. const bot = createBot()
  // 8. if scheduler: initScheduler(sendFn)
  // 9. if whatsapp: initWhatsApp(onIncoming)
  // 10. Register SIGINT/SIGTERM handlers → graceful shutdown
  // 11. bot.start() / bot.login() / etc
  logger.info('ClaudeClaw running')
}
```

`acquireLock()`: write `process.pid` to `store/claudeclaw.pid`. If file exists, read PID, try `process.kill(pid, 0)` — if alive, kill it; if stale, overwrite.

`releaseLock()`: delete PID file.

---

## STEP 5 — CLAUDE.md template

Create `CLAUDE.md` with this structure. Include placeholder comments for the user to fill in:

```markdown
# [YOUR ASSISTANT NAME]

You are [YOUR NAME]'s personal AI assistant, accessible via [PLATFORM].
You run as a persistent service on their machine.

## Personality

Your name is [YOUR ASSISTANT NAME]. You are chill, grounded, and straight up.

Rules you never break:
- No em dashes. Ever.
- No AI clichés. Never say "Certainly!", "Great question!", "I'd be happy to", "As an AI".
- No sycophancy.
- No excessive apologies. If you got something wrong, fix it and move on.
- Don't narrate what you're about to do. Just do it.
- If you don't know something, say so plainly.

## Who Is [YOUR NAME]

[YOUR NAME] [does what]. [Main projects]. [How they think/what they value].

## Your Job

Execute. Don't explain what you're about to do — just do it.
When [YOUR NAME] asks for something, they want the output, not a plan.
If you need clarification, ask one short question.

## Your Environment

- All global Claude Code skills (~/.claude/skills/) are available
- Tools: Bash, file system, web search, browser automation, all MCP servers
- This project lives at the directory where CLAUDE.md is located
- Obsidian vault: [YOUR_OBSIDIAN_VAULT_PATH]
- Gemini API key: stored in this project's .env as GOOGLE_API_KEY

## Available Skills

| Skill | Triggers |
|-------|---------|
| `gmail` | emails, inbox, reply, send |
| `google-calendar` | schedule, meeting, calendar |
| `todo` | tasks, what's on my plate |
| `agent-browser` | browse, scrape, click, fill form |
| `maestro` | parallel tasks, scale output |

## Scheduling Tasks

[INCLUDE ONLY IF SCHEDULER SELECTED]
To schedule a task, use: node [PATH]/dist/schedule-cli.js create "PROMPT" "CRON" CHAT_ID

Common patterns:
- Daily 9am: `0 9 * * *`
- Every Monday 9am: `0 9 * * 1`
- Every 4 hours: `0 */4 * * *`

## Message Format

- Keep responses tight and readable
- Use plain text over heavy markdown
- For long outputs: summary first, offer to expand
- Voice messages arrive as `[Voice transcribed]: ...` — treat as normal text, execute commands
- For heavy multi-step tasks: send progress updates via [PATH]/scripts/notify.sh "message"
- Do NOT send notify for quick tasks — use judgment

## Memory

Context persists via Claude Code session resumption.
You don't need to re-introduce yourself each message.

## Special Commands

### `convolife`
Check remaining context window:
1. Find latest session JSONL: `~/.claude/projects/` + project path with slashes → hyphens
2. Get last cache_read_input_tokens value
3. Calculate: used / 200000 * 100
4. Report: "Context window: XX% used — ~XXk tokens remaining"

### `checkpoint`
Save session summary to SQLite:
1. Write 3-5 bullet summary of key decisions/findings
2. Insert into memories table as semantic memory with salience 5.0
3. Confirm: "Checkpoint saved. Safe to /newchat."
```

---

## STEP 6 — Setup wizard (`scripts/setup.ts`)

The setup wizard is the onboarding experience. It must:

1. **Show banner** — ASCII art from `banner.txt` or fallback header
2. **Check requirements**:
   - Node >= 20
   - `claude` CLI installed and authenticated
   - Build the project (`npm run build`) — use `fileURLToPath(import.meta.url)` for PROJECT_ROOT
3. **Collect config interactively**:
   - Bot token (platform-specific)
   - Which optional features are enabled
   - API keys for selected features only (don't ask for keys you won't use)
4. **Open `CLAUDE.md` in `$EDITOR`** for personalization
5. **Write `.env`** with all collected values
6. **Install background service**:
   - macOS: generate + load launchd plist to `~/Library/LaunchAgents/com.claudeclaw.app.plist`
   - Linux: generate + enable systemd user service
   - Windows: print PM2 instructions
7. **Get chat ID**:
   - Start bot process
   - Tell user to send `/chatid`
   - Listen for it (or poll) → update `.env`
8. **Print next steps**

Use color-coded output (ANSI): ✓ green, ⚠ yellow, ✗ red.

**Critical**: All `spawnSync` / `execSync` calls that use `PROJECT_ROOT` as `cwd` must derive `PROJECT_ROOT` via `fileURLToPath(import.meta.url)` — never `new URL(import.meta.url).pathname`.

---

## STEP 7 — Status script (`scripts/status.ts`)

`npm run status` should check and print:

- Node version (pass/fail >=20)
- Claude CLI version
- Telegram/Discord bot token valid (call their test API endpoint)
- Chat ID / user ID configured
- Voice STT configured (if enabled)
- Voice TTS configured (if enabled)
- Service running status (`launchctl list` / `systemctl --user status`)
- DB exists + memory row count
- Scheduled task count (if enabled)

---

## STEP 8 — package.json

```json
{
  "name": "claudeclaw",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsx src/index.ts",
    "setup": "tsx scripts/setup.ts",
    "status": "tsx scripts/status.ts",
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  },
  "engines": { "node": ">=20" }
}
```

Always include:
- `@anthropic-ai/claude-agent-sdk`
- `better-sqlite3` + `@types/better-sqlite3`
- `pino` + `pino-pretty`
- `typescript` + `tsx` + `@types/node`
- `vitest`

Add conditionally based on user answers.

---

## STEP 9 — tsconfig.json

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

---

## STEP 10 — .env.example

Document every variable with inline comments. Mark which are required vs optional. Group by feature.

---

## STEP 11 — .gitignore

```
node_modules/
dist/
.env
store/
workspace/
*.log
*.pid
```

---

## STEP 12 — Build order

Write files in this order so each file's dependencies exist before it's referenced:

1. `.gitignore`, `package.json`, `tsconfig.json`
2. `src/env.ts`
3. `src/logger.ts`
4. `src/config.ts`
5. `src/db.ts`
6. `src/agent.ts`
7. `src/memory.ts` (if applicable)
8. `src/voice.ts` (if applicable)
9. `src/media.ts` (if applicable)
10. `src/scheduler.ts` + `src/schedule-cli.ts` (if applicable)
11. `src/whatsapp.ts` (if applicable)
12. `src/bot.ts`
13. `src/index.ts`
14. `CLAUDE.md`
15. `.env.example`
16. `scripts/setup.ts`
17. `scripts/status.ts`
18. `scripts/notify.sh`
19. Run `npm install` and `npm run build` to verify

---

## STEP 13 — Known gotchas to avoid

1. **Spaces in paths**: Always use `fileURLToPath(import.meta.url)` to get `__dirname`-equivalent. Never use `new URL(import.meta.url).pathname` — it preserves `%20` URL encoding and breaks on paths with spaces (e.g. `~/Desktop/My Projects/claudeclaw`). This is the single most common source of "Missing script: build" errors during setup.

2. **process.env pollution**: Never set `process.env` from `.env`. Use `readEnvFile()` to read secrets into local variables. The Claude Code SDK subprocess inherits `process.env`, so polluting it can leak secrets or cause conflicts.

3. **Session resumption**: The `resume` option in the Claude SDK requires the exact session ID string from the previous run. Store it per-chat in SQLite. On `/newchat`, delete the row — don't pass `undefined` as a workaround.

4. **Typing indicator expiry**: Telegram's "typing..." indicator expires after ~5s. Refresh it every 4s in a `setInterval` while waiting for Claude. Clear the interval immediately after `runAgent` returns or you'll keep it spinning.

5. **grammy error handling**: Wrap `bot.start()` in a try/catch. grammy throws on invalid token at startup. Give a clear error message pointing to `TELEGRAM_BOT_TOKEN` in `.env`.

6. **WhatsApp Puppeteer on Apple Silicon**: `whatsapp-web.js` may need `--no-sandbox` Chromium flag on newer macs. Add to `LocalAuth` puppeteer args.

7. **Memory FTS sync**: The FTS5 virtual table needs manual trigger maintenance. Any direct `UPDATE` or `DELETE` on the `memories` table won't auto-sync FTS unless you set up triggers explicitly.

8. **`bypassPermissions` mode**: Required for unattended operation. Without it, the Claude subprocess will pause waiting for user approval on tool calls and the bot will hang.

9. **launchd `KeepAlive`**: Set `ThrottleInterval` to at least 5 seconds to prevent rapid crash-restart loops from hammering the system. Without it, a crash loop can make the machine unresponsive.

10. **OGA vs OGG**: Telegram sends voice notes as `.oga` files. Groq Whisper doesn't accept `.oga`. Rename to `.ogg` before sending — the format is identical, just the extension matters.

---

## STEP 14 — After writing all files

1. Run `npm install`
2. Run `npm run build` — fix any TypeScript errors before proceeding
3. Run `npm run typecheck` — should pass cleanly
4. Run `npm test` — write at least basic tests for `env.ts`, `db.ts`, and the formatter in `bot.ts`
5. Create `store/` and `workspace/uploads/` directories (or ensure they're created on startup)
6. Tell the user what was built: list the files created, features included, and estimated line count
7. Tell the user the next step: "Run `npm run setup` to configure your API keys and install the background service. The wizard will walk you through everything."
8. Remind them: "You can still ask me anything — about how something works, how to get a specific API key, or what a file does."

---

## STEP 15 — Stay available

After handing off, do not disappear. You are still the onboarding assistant. The user may:

- Ask how to get their Telegram bot token → walk them through @BotFather step by step
- Ask what to fill in for a CLAUDE.md placeholder → help them write their personal context section
- Ask why a build step failed → debug it with them
- Ask how to add a skill → explain `~/.claude/skills/` and how to install one
- Ask how to create their first scheduled task → give them the exact CLI command
- Ask what their chat ID is → explain the `/chatid` command

Answer anything. You built this thing — you know how it works. Be the person they can ask when they're stuck at 11pm trying to get it running.

---

## Reference: what the original implementation used

For reference, the production ClaudeClaw implementation this prompt is derived from:
- ~2,800 lines of TypeScript across 14 source files
- 933 lines of tests (Vitest)
- SQLite with 7 tables + FTS5 full-text search
- Dual-sector memory with salience decay (semantic + episodic)
- Full Telegram + WhatsApp bridge
- Groq Whisper STT + ElevenLabs TTS
- Cron scheduler with SQLite task persistence
- launchd (macOS) / systemd (Linux) auto-start
- Interactive 700-line setup wizard with ANSI color output

Build what the user selected. Don't build what they didn't ask for.