llms.txt

# BlackCat — AI Setup Contract

## What is BlackCat

BlackCat is a Go-based AI agent that orchestrates OpenCode CLI via messaging channels (Telegram, Discord, WhatsApp). Deploy BlackCat alongside OpenCode on a server, then interact with your development environment through natural language messages.

## Prerequisites

- Go 1.25+ with CGO_ENABLED=1 (required for WhatsApp SQLite support)
- OpenCode CLI installed and running (listens on http://127.0.0.1:4096)
- At least one messaging channel credential:
  - Telegram bot token, or
  - Discord bot token, or
  - WhatsApp credentials
- At least one LLM provider API key

## Installation

```bash
go install github.com/startower-observability/blackcat@latest
blackcat onboard           # interactive config wizard — creates ~/.blackcat/config.yaml
blackcat start             # starts daemon via systemctl --user
blackcat status            # verify daemon is running
```

## Configuration

Configuration path: `~/.blackcat/config.yaml`

Key environment variables (all prefixed with `BLACKCAT_`):

| Variable | Description |
|----------|-------------|
| `BLACKCAT_LLM_PROVIDER` | LLM provider: openai, anthropic, gemini, copilot, antigravity, openrouter, ollama, zen |
| `BLACKCAT_LLM_APIKEY` | API key for the LLM provider |
| `BLACKCAT_CHANNELS_TELEGRAM_TOKEN` | Telegram bot token |
| `BLACKCAT_CHANNELS_DISCORD_TOKEN` | Discord bot token |
| `BLACKCAT_CHANNELS_WHATSAPP_TOKEN` | WhatsApp token |
| `BLACKCAT_VAULT_PASSPHRASE` | Vault encryption passphrase |
| `BLACKCAT_ZEN_APIKEY` | Zen/OpenCode.ai API key |
| `BLACKCAT_OPENCODE_PASSWORD` | OpenCode daemon password |
| `BLACKCAT_WHISPER_GROQAPIKEY` | Groq API key for voice-to-text (Whisper) |

## Service Bootstrap

Commands to manage the BlackCat daemon:

```bash
blackcat start             # start daemon
blackcat stop              # stop daemon
blackcat restart           # restart after config changes
blackcat status            # show running state
blackcat doctor            # full system diagnostic
blackcat health            # quick health check (JSON)
```

Systemd commands (use `--user`, NOT sudo):

```bash
systemctl --user status blackcat
systemctl --user start blackcat
systemctl --user stop blackcat
systemctl --user restart blackcat
```

## Channel Setup

```bash
blackcat channels add      # interactive channel wizard
blackcat channels list     # list configured channels
blackcat channels login    # authenticate channel session (e.g. WhatsApp QR scan)
blackcat channels status   # verify channel connection
```

## Health Verification

After setup, verify the system is healthy:

```bash
blackcat health            # expect JSON: {"status":"healthy","scheduler":"...","whatsapp":"connected",...}
blackcat doctor            # full diagnostic with detailed status per subsystem
```

## Built-in Skills

BlackCat ships with built-in skills for social media and productivity. Skills are auto-loaded but silently skipped when prerequisites are not met.

| Skill | Required Bins | Required Env Vars |
|-------|--------------|-------------------|
| Threads | — | `THREADS_ACCESS_TOKEN` |
| Twitter/X | `bird` | `TWITTER_AUTH_TOKEN` |
| LinkedIn | `python3` | `LINKEDIN_LI_AT`, `LINKEDIN_JSESSIONID` |
| Facebook | — | `FACEBOOK_PAGE_TOKEN` |
| TikTok | — | `TIKTOK_ACCESS_TOKEN` |
| Google Workspace | `gws` (Node 18+) | — (uses `gws auth setup`) |
| Whisper Voice | — | `BLACKCAT_WHISPER_GROQAPIKEY` (+ `whisper.enabled: true` in config) |

Run `blackcat doctor` to verify skill prerequisites.

### Voice Transcription (Whisper)

Enable voice-to-text transcription for Telegram, Discord, and WhatsApp voice messages.

**How to enable:**
1. Set `whisper.enabled: true` in `~/.blackcat/config.yaml`
2. Set the environment variable: `BLACKCAT_WHISPER_GROQAPIKEY=<your-groq-api-key>`

**Full config example:**
```yaml
whisper:
  enabled: true
  model: whisper-large-v3-turbo   # recommended
```

**Where to get the key:** https://console.groq.com → API Keys

**Verify with:** `blackcat doctor` — shows "Voice Transcription" check as pass/fail

## Scheduler Configuration

Configured in `~/.blackcat/config.yaml` under the `scheduler:` section.

Cron format: 6-field (seconds-first): `S M H D Month Weekday`

Example configuration:

```yaml
scheduler:
  enabled: true
  jobs:
    - name: morning-greeting
      schedule: "0 0 6 * * *"   # 06:00 daily
      deliver:
        channel: whatsapp
        channelId: "6281234567890@s.whatsapp.net"
        message: "Good morning!"
```

Check scheduler status via:
- `blackcat health` — shows scheduler status and task count
- `blackcat doctor` — detailed scheduler diagnostics

There is NO `blackcat scheduler` CLI subcommand. Configuration is YAML-only.

## Failure Diagnostics

| Symptom | Diagnosis |
|---------|-----------|
| Daemon won't start | Run `blackcat doctor`, verify OpenCode is running at 127.0.0.1:4096 |
| WhatsApp disconnected | Run `blackcat channels login` for QR scan re-auth |
| LLM errors | Verify API key via env var, check `blackcat doctor` |
| CGO errors on build | Ensure CGO_ENABLED=1 and C compiler installed (gcc/clang) |
| Permission denied | Ensure using `systemctl --user` not `sudo systemctl` |

## Do / Don't

- DO use `systemctl --user` — NEVER `sudo systemctl`
- DO use `go test -tags nospa ./...` — NOT `go test ./...`
- DO keep `deploy/deploy.env` out of git — MUST NEVER be committed
- DO run `blackcat health` after every config change
- DON'T look for `blackcat scheduler` CLI — it doesn't exist; use health/doctor
- DON'T commit secrets or API keys to the repo
- DON'T use emojis in commit messages or documentation
- DO install Node.js 18+ if using Google Workspace CLI skill
- DO run `gws auth setup` before using Google Workspace skill
- DON'T expect social media skills without setting their env vars

## Built-in Skills (Phase 2)

The following additional built-in skills are available when prerequisites are met:

- veo3-video-gen: Requires uv, ffmpeg, GEMINI_API_KEY
- nano-banana-pro: Requires uv, GEMINI_API_KEY
- document-processing: Requires python3
- capability-evolver: Requires node
- reddit-scraper: Requires python3
- prompt-guard: Requires python3
- marketplace-installer: Requires npx

## Marketplace Integration

- MarketplaceDir config field: path relative to workspace dir (default: "marketplace")
- AllowExternalInstall config field: bool, default false (security gate for npx installs)
- MaxSkillsInPrompt config field: max skills injected into LLM context (default: 50)
- MaxSkillFileBytes config field: max bytes per skill file (default: 262144)
- Both built-in skills dir and marketplace dir are watched for live reload
- Skills exceeding MaxSkillFileBytes are silently skipped
- Skills are deduplicated by name across directories (built-in wins on conflict)

## Phase 3 Features

### Provider Fallback
- Config: llm.fallback ([]string, default empty)
- Valid provider names: openai, copilot, antigravity, gemini, zen
- Behavior: if primary provider fails, fallback providers are tried in order
- ErrContextLength is NOT retried via fallback — returned immediately to caller
- Per-provider retry: 3 attempts before moving to next fallback
- If all fallbacks fail, returns joined error from all providers
- Zero-value (empty fallback list) preserves existing behavior exactly

### Budget Controls
- Config section: budget.*
- budget.enabled (bool, default false): master switch for budget enforcement
- budget.daily_limit_usd (float64, default 0 = unlimited): daily spend cap in USD
- budget.monthly_limit_usd (float64, default 0 = unlimited): monthly spend cap in USD
- budget.warn_threshold (float64, default 0.8): fraction of limit at which warnings are emitted
- Pricing model: flat rates — $2.00/M input tokens, $8.00/M output tokens (no per-model pricing)
- BudgetExceeded status: request rejected, user notified via channel
- BudgetWarning status: slog.Warn emitted, processing continues
- Budget check runs BEFORE each message is processed; read-only (no DB writes on check)

### Skill Versioning
- Frontmatter field: version (string, optional) — must be vMAJOR.MINOR.PATCH semver
- ValidateVersion() uses golang.org/x/mod/semver.Canonical for validation
- Empty version string is valid (unversioned skill)

### Skill Dependencies
- Frontmatter field: depends_on ([]string, optional) — list of skill names
- Dependency resolution: Kahn's algorithm (topological sort), deterministic (alphabetical tie-breaking)
- Missing dependency: skill silently removed (graceful degradation, not error)
- Circular dependency: detected via DFS, logged as error, original eligible list returned unchanged

### Skill Install Hints
- Frontmatter field: install (string, optional) — install command hint for ineligible skills
- install field is NEVER exposed in FormatForInjection() output (runtime only)
- Shown by blackcat doctor Check 15 for ineligible skills that have an install hint

### Flexible Prerequisites (anyBins)
- Frontmatter field: requires.any_bins ([][]string, optional) — list of binary groups
- Within each group: OR semantics (any binary in the group satisfies the group)
- Across groups: AND semantics (all groups must be satisfied)
- Example: [[python3, python], [node, nodejs]] = (python3 OR python) AND (node OR nodejs)
- Empty any_bins: always satisfied (no constraint)
- getBinaryVersion(name) utility: probes --version/-v/version flags, extracts semver from output

### Marketplace Registry
- File: registry.json in marketplace directory (skills.marketplace_dir)
- Schema: {"skills": [{"name":"...","version":"...","description":"...","install":"...","author":"...","license":"..."}]}
- LoadRegistry(marketplaceDir): returns empty Registry (not error) when registry.json absent
- InstalledStatus(loaded []Skill): compares registry versions against loaded skills
- Statuses: "not-installed", "installed", "update-available"
- Version comparison uses ValidateVersion() canonical form
- Empty versions (either registry or installed): reports "installed" without version comparison

## Do / Don't (Phase 3 additions)
- DO configure llm.fallback for resilience against provider outages
- DO set budget limits in production deployments (budget.enabled: true)
- DON'T use fallback with antigravity as primary — requires special ToS config not supported in fallback chain
- DO use version field in marketplace skills for update-available detection
- DON'T expect install hint to appear in the LLM context — it is doctor-only
- DO run blackcat doctor after adding new marketplace skills to verify eligibility

## v1.3.1 Fixes and Additions

1. **Config auto-load fix**: `blackcat doctor` and all commands now correctly load `~/.blackcat/config.yaml` (previously looked for `~/.blackcat.yaml` — missing the subdirectory). No user action required; this is transparent.

2. **Extended `blackcat doctor` skill checks**: Doctor now checks 14 additional skills beyond the 7 social media skills: Voice Transcription (Whisper), and Phase 2 skills (veo3-video-gen, nano-banana-pro, document-processing, capability-evolver, reddit-scraper, prompt-guard, marketplace-installer). Doctor also shows install hints for ineligible skills that have an `install` field in their frontmatter.

3. **`blackcat onboard` Step 5 — Skills setup**: The onboard wizard now has a 5th step (relabeled from 4-step to 5-step flow) that interactively walks users through setting up built-in skills. For each skill, it shows prerequisites and provides setup instructions. Users can skip or configure each skill individually.

## Role-Based Routing (Phase 4)

### How ClassifyMessage Works
- Sorts roles by priority (ascending) — lower number = higher priority
- Iterates through sorted roles and checks if any keyword matches the user message
- First match wins and determines the role for that message
- Falls back to oracle role if no keywords match

### The 7 Built-in Roles

| Role | Priority | Domain |
|------|----------|--------|
| phantom | 10 | Infrastructure and DevOps automation |
| astrology | 20 | Cryptocurrency and Web3 |
| wizard | 30 | Coding, software development, architecture |
| artist | 40 | Creative work, design, visual tasks |
| scribe | 50 | Documentation, writing, note-taking |
| explorer | 60 | Research, information gathering, web search |
| oracle | 100 | General fallback, complex reasoning, orchestration |

### Configuring Custom Roles

Add custom roles in `~/.blackcat/config.yaml` under the `roles:` section:

```yaml
roles:
  - name: my-role
    model: claude-3-5-sonnet
    provider: anthropic
    temperature: 0.7
    system_prompt: "You are a specialized assistant for X..."
    keywords:
      - keyword1
      - keyword2
    allowed_tools:
      - Bash
      - Read
    priority: 25
```

### RoleConfig Struct Fields

- `name` (string): Unique identifier for the role
- `model` (string): LLM model name (e.g., claude-3-5-sonnet, gpt-4o)
- `provider` (string): LLM provider (openai, anthropic, gemini, etc.)
- `temperature` (float64): Sampling temperature (0.0-1.0)
- `system_prompt` (string): System prompt prepended to each message
- `keywords` ([]string): Trigger words that route messages to this role
- `allowed_tools` ([]string): Tool names this role can invoke (empty = all tools)
- `priority` (int): Lower number = higher priority (default: 100)

### Per-Role Model and Provider Setup

Configure different LLM models and providers for each role.

**Important:** There is **NO CLI command** for per-role model/provider configuration. It is YAML-only.

**Configuration:**
1. Edit `~/.blackcat/config.yaml` under the `roles:` section
2. The config watcher **hot-reloads** automatically — no `blackcat restart` needed after saving
3. Each role supports these override fields: `model`, `provider`, `temperature`, `system_prompt`

**Example — different roles using different models/providers:**
```yaml
roles:
  - name: phantom
    priority: 10
    model: "gpt-4.1-mini"         # fast, tool-focused for infra tasks
    provider: "openai"
    keywords: [deploy, docker, k8s, server, systemd]
  - name: wizard
    priority: 30
    model: "claude-sonnet-4-5"    # deep reasoning for coding
    provider: "anthropic"
    temperature: 0.2
    keywords: [code, refactor, debug, build]
  - name: artist
    priority: 40
    model: "gemini-2.0-flash"     # fast and cheap for creative tasks
    provider: "gemini"
    keywords: [post, tweet, thread, image]
```

**Verify with:** `blackcat doctor` — shows active role count and configuration

## RTK Integration (Phase 4)

### What RTK Is
- RTK (Rust Token Killer) is a token-saving wrapper for shell commands
- Filters verbose command output, showing only the essential information
- Reduces token usage by 60-90% on common development operations
- Works with cargo, tsc, lint, prettier, next, vitest, playwright, pnpm, npm, npx, prisma, docker, kubectl, git, gh, and more

### How wrapWithRTK Works
- Intercepts Bash tool calls in the OpenCode agent
- Wraps the command with RTK filtering logic
- Returns condensed output grouped by file, error, or status
- Preserves exit codes and error detection

### Enabling RTK

Set `rtk.enabled: true` in `~/.blackcat/config.yaml`:

```yaml
rtk:
  enabled: true
  commands:
    - cargo
    - tsc
    - lint
    - prettier
    - next
    - vitest
    - playwright
    - pnpm
    - npm
    - npx
    - prisma
    - docker
    - kubectl
    - git
    - gh
    - ls
    - grep
    - find
```

### RTKConfig Struct Fields

- `enabled` (bool): Master switch for RTK integration (default: false)
- `commands` ([]string): List of command prefixes to intercept and filter

Default commands when enabled: cargo, tsc, lint, prettier, next, vitest, playwright, pnpm, npm, npx, prisma, docker, kubectl, git, gh, ls, grep, find