# ghost-code

> Ghostty + Claude Code Telegram bridge

Get notified on your phone when Claude finishes a task or needs input — reply to inject text back into the terminal, or chat with Claude directly via streaming responses. Hooks into Claude Code's lifecycle events with a single binary.

## Features

- Task completion summaries via Telegram (silent notifications)
- Attention request forwarding with details
- Tool approval via inline Allow/Deny buttons
- Real-time statusline (model, cost, plan usage, context, aid stats)
- Streaming chat — send messages to Claude from Telegram
- Session reply — inject text into originating Ghostty tab
- Multi-machine support with hostname identification
- Noise filtering for quota recovery and system events
- Sleep prevention with automatic caffeinate
- Single-instance flock-based daemon with graceful shutdown

## Architecture

```
src/
  main.rs          Entry point: dispatches to hook handlers or bot daemon
  config.rs        Config loading from .env
  telegram.rs      Telegram Bot API client
  usage.rs         Cost tracking
  plan_usage.rs    Plan usage limit parsing
  hook/
    mod.rs         Spool I/O, fast handlers, utilities
    format.rs      Text extraction, formatting, hostname
    process.rs     Stop/notification/pre-tool-use processors
    session.rs     Session mapping, pending replies, consolidation
    terminal.rs    Ghostty tab detection and title management
  bot/
    mod.rs         Daemon lifecycle, signal handling, spool processing
    callbacks.rs   Callback query handler (approvals)
    commands.rs    Slash commands (/help, /sessions, /dir, etc.)
    messages.rs    Message routing, dedup, Ghostty injection
    polling.rs     JSONL response polling, plan notifications
    status.rs      Statusline data (costs, plan limits, tool savings)
    streaming.rs   Claude CLI streaming output
```

Hook handlers use a fast spool-to-disk path (no config load, no network) so Claude Code is never blocked. The bot daemon processes spool files asynchronously.

## Hook Types

- **Stop**: Task completion — sends summary with cost and duration
- **Notification**: Attention requests — forwards details with context
- **PreToolUse**: Tool approval — inline Allow/Deny keyboard buttons
- **StatusLine**: Real-time metrics — model, cost, plan usage, context window

## Configuration

Required environment variables:
- `TELEGRAM_BOT_TOKEN` — Telegram Bot API token from @BotFather
- `TELEGRAM_CHAT_ID` — Target chat ID for notifications

Optional:
- `GHOST_CODE_LOG_LEVEL` — Log verbosity (default: info)
- `GHOST_CODE_SPOOL_DIR` — Custom spool directory path

## Install

```
cargo install ghost-code
ghost-code setup
```

## Links

- Homepage: https://ghost-code.agent-tools.org
- Repo: https://github.com/sunoj/ghost-code
- License: MIT
- Parent: https://agent-tools.org