# derp - Backlog

## Core

- [x] Multi-server support (per-server config, shared plugins)
- [x] Stable plugin API (versioned, breaking change policy)
- [x] Paste overflow (auto-paste long output to FlaskPaste)
- [x] URL shortener integration (shorten URLs in subscription announcements)
- [x] Webhook listener (HTTP endpoint for push events to channels)
- [x] Granular ACLs (per-command: trusted, operator, admin)

## LLM Bridge

Goal: let an LLM agent interact with the bot over IRC in real-time,
with full machine access (bash, file ops, etc.).

### Architecture

Owner addresses the bot on IRC. A bridge daemon reads addressed
messages, feeds them to an LLM with tool access, and writes replies
back through the bot. The bot already has `owner` config
(`[bot] owner` hostmask patterns) to gate who can trigger LLM
interactions.

```
IRC -> bot stdout (addressed msgs) -> bridge -> LLM API -> bridge -> bot inbox -> IRC
```

### Approach options (ranked)

1. **Claude Code Agent SDK** (clean, non-trivial)
   - Custom Python agent using `anthropic` SDK with `tool_use`
   - Define tools: bash exec, file read/write, web fetch
   - Persistent conversation memory across messages
   - Full control over the event loop -- real-time IRC is natural
   - Tradeoff: must implement and maintain tool definitions

2. **Claude Code CLI per-message** (simple, stateless)
   - `echo "user said X" | claude --print --allowedTools bash,read,write`
   - Each invocation is a cold start with no conversation memory
   - Simple to implement but slow startup, no multi-turn context
   - Could pass conversation history via system prompt (fragile)

3. **Persistent Claude Code subprocess** (hack, fragile)
   - Long-running `claude` process with stdin/stdout piped
   - Keeps context across messages within a session
   - Not designed for this -- output parsing is brittle
   - Session may drift or hit context limits

### Bot-side plumbing needed

- `--llm` CLI flag: route logging to file, stdout for addressed msgs
- `_is_addressed()`: DM or nick-prefixed messages
- `_is_owner()`: only owner hostmasks trigger LLM routing
- Inbox file polling (`/tmp/llm-inbox`): bridge writes `<target> <msg>`
- `llm-send` script: line splitting (400 char), FlaskPaste overflow
- Stdout format: `HH:MM [#chan] <nick> text` / `HH:MM --- status`
- Only LLM-originated replies echoed to stdout (not all bot output)

### Previous attempt (reverted)

The `--llm` mode was implemented and tested (commit ea6f079, reverted
in 6f1f4b2). The stdout/stdin plumbing worked but Claude Code CLI
cannot act as a real-time daemon -- each tool call is a blocking
round-trip, making interactive IRC conversation impractical. The code
is preserved in git history for reference.

## Plugins -- Security/OSINT

- [x] `emailcheck` -- SMTP VRFY/RCPT TO verification
- [x] `canary` -- canary token generator/tracker
- [x] `virustotal` -- hash/URL/IP/domain lookup (free API)
- [x] `abuseipdb` -- IP abuse confidence scoring (free tier)
- [x] `jwt` -- decode tokens, show claims/expiry, flag weaknesses
- [x] `mac` -- OUI vendor lookup (local IEEE database)
- [x] `pastemoni` -- monitor paste sites for keywords
- [x] `internetdb` -- Shodan InternetDB host recon (free, no API key)

## Plugins -- Utility

- [x] `paste` -- manual paste to FlaskPaste
- [x] `shorten` -- manual URL shortening
- [x] `cron` -- scheduled bot commands on a timer

## Testing

- [x] Plugin command unit tests (encode, hash, dns, cidr, defang)
- [x] CI pipeline (Gitea Actions)