Plugin Development

Plugin Development

Full guide lives at docs/plugin-development.md — this page is the wiki-friendly summary.

Trust tiers

Tier	What it can do	Trust required
🟢 declarative	loot / redaction / target patterns, event types, capture scripts	none — data the app reads, or scripts you run that hit the authenticated HTTP API
🔴 privileged	expose MCP tools that Claude / Codex can operate	explicit content-hash-pinned grant with declared capabilities

Layout

my-plugin/
├─ plugin.json
├─ hooks/           # 🟢 capture scripts
│   └─ my-wrapper.sh
├─ patterns.json    # optional
└─ code/            # 🔴 privileged (only for MCP tools)
    └─ mcp-tool.js

Common contributions

• contributes.lootPatterns — teach the loot detector about a new secret shape
• contributes.redaction.denylist — extra tokens that should be masked
• contributes.targetExtractors — regex-based target detection for custom tooling
• contributes.eventTypes — new agent_type with its own timeline lane, colour, icon
• contributes.capture[] — full agent-hook integration (see below)

Adding a new AI agent

Three tiers of integration, pick the highest one the agent supports:

Tier	When	Effort	Context
A. Native hook API	Agent exposes hook events (Claude Code)	Low	session_id, tool name/input/output
B. SHELL wrapper	Agent lets you override its shell (Codex)	Medium	command, exit code, cwd
C. Fallback	Nothing agent-specific	None (already covered by shell-* hooks)	just the command

Only write a plugin for A or B — C is already handled by the built-in shell-zsh / shell-bash hooks.

Full working Aider plugin manifest + wrapper skeleton is in the docs page above.

Testing your plugin

1. Drop the plugin dir under ~/.redlog/plugins/ or your project's .redlog/plugins/.
2. Restart RedLog (or click Reload in Settings ▸ Plugins).
3. Appears in Settings ▸ Plugins as 🟢 declarative and in Settings ▸ Hooks as an installable capture.
4. Fire the hook manually with a synthetic payload:

   AIDER_SHELL_CMD='echo test' bash hooks/aider-wrapper.sh -c 'echo test'

5. Verify via CLI:

   redlog-cli events --agent_type agent --limit 3

Reference

• examples/plugins/recon-pack — full 🟢 declarative example (patterns + extractor + event type + capture).
• src/core/plugins/types.ts — full manifest schema.
• docs/plugin-development.md — comprehensive guide with capabilities, privileged code contract, publishing.