ebi-agent-chat-relay: Instructions file for Claude Code

claude-code-discord-bridge (ccdb)

Discord frontend for Claude Code CLI. This is a framework (OSS library), not a personal bot.

略称: ccdb (claude-code-discord-bridge)

Framework vs Instance

• claude-code-discord-bridge (this repo) = reusable OSS framework. No personal config, no secrets, no server-specific logic.
• Personal instances (e.g. EbiBot) use the custom Cog loader (CUSTOM_COGS_DIR / --cogs-dir) to add their own Cogs. See examples/ebibot/ for the reference implementation.
• When adding features: if it's useful to anyone → add here. If it's personal workflow → add as a custom Cog.

Zero-Config Principle (Critical)

Consumers must get new features by updating the package alone — no code changes required.

• New features should be enabled by default (auto-discovery, sensible defaults)
• New constructor parameters must have backward-compatible defaults (= None)
• If a feature requires consumers to wire something up, the design is wrong — fix it in ccdb
• Consumers should NEVER need to copy, wrap, or subclass ccdb Cogs. If they do, ccdb is missing an extension point

Architecture

• Python 3.12+ with discord.py v2
• Cog pattern for modular features
• Repository pattern for data access (SQLite via aiosqlite)
• asyncio.subprocess for Claude Code CLI invocation (never shell=True)

Key Design Decisions

1. CLI spawn, not API: We invoke claude -p --output-format stream-json as a subprocess, not the Anthropic API directly. This gives us all Claude Code features (CLAUDE.md, skills, tools, memory) for free.
2. Thread = Session: Each Discord thread maps 1:1 to a Claude Code session ID. Replies in a thread continue the same session via --resume.
3. Emoji reactions for status: Non-intrusive progress indication on the user's message. Debounced to avoid Discord rate limits.
4. Fence-aware chunking: Never split messages inside a code block. The logic lives in claude_code_core/rendering/ and is driven by SurfaceCapabilities, not by Discord's numbers — a surface with a 100 KB limit sends the same answer as one message instead of inheriting Discord's 2,000-character fragmentation.
5. Installable package: claude_discord is a proper Python package. Consumers install via uv add git+... or pip install git+..., not by copying files.
6. Shared run helper: cogs/_run_helper.py centralizes Claude CLI execution logic used by both ClaudeChatCog and SkillCommandCog.
7. REST API as the control plane: Claude Code subprocesses communicate back to ccdb via REST API (CCDB_API_URL env var), not via stdout markers or special output formats. This makes the interface explicit, testable, and usable by external systems (GitHub Actions, etc.). See ext/api_server.py.
8. SQLite-backed dynamic scheduler: Scheduled tasks are stored in scheduled_tasks DB table and executed by a single discord.ext.tasks master loop (every 30s). Tasks are registered at runtime via REST API — no code changes needed to add new tasks. discord.ext.tasks decorators are only used for the master loop, not per-task (they're static/compile-time constructs).
9. Claude handles "what", ccdb handles "when": For scheduled tasks, ccdb only manages the schedule. All domain logic (what to check, how to deduplicate, what to post) lives in the Claude prompt. No GitHub/AzureDevOps-specific code in ccdb itself.
10. CLI env overlay (CCDB_CLI_ENV_FILE): Optional KEY=VALUE file read on every CLI spawn to inject env vars into the subprocess. Enables live configuration changes (e.g., switching to Azure Foundry) without restarting the bot. The file is read by _build_env() in runner.py.
11. Model suggestions are discovered, not hardcoded (model_catalog.py): the /model autocomplete asks GET /v1/models (reusing the CLI's own credentials) instead of shipping a constant that goes stale on every model launch. This is the only sanctioned direct Anthropic API call, and it is strictly non-essential: no credentials, no network, a 3P provider, or CCDB_MODEL_DISCOVERY=0 all degrade to the static SUGGESTED_MODELS fallback. Never let it raise into a command path, and never log the token. Codex is discovered too, but without a second vendor call: the Codex CLI already fetches its own catalog and writes it to $CODEX_HOME/models_cache.json, so codex_model_choices() reads that file. A new generation (gpt-6-astra) appears as soon as the CLI has seen it, and decision 13's "ccdb does not phone home" still holds.