interspect

interspect

Agent performance profiler and routing optimizer for Claude Code. Collects evidence about flux-drive agent accuracy, proposes routing overrides for underperforming agents, and monitors canary periods. Clavain companion plugin.

Installation

claude plugin add interspect@interagency-marketplace
claude plugin update interspect@interagency-marketplace

Usage

# Core workflow
/interspect              # Analyze evidence, detect patterns, report readiness
/interspect:status       # Overview — sessions, evidence, canaries
/interspect:evidence     # Detailed agent evidence view

# Corrections
/interspect:correction   # Record a manual correction event

# Routing overrides
/interspect:propose      # Propose routing override from ready patterns
/interspect:override     # Apply override directly
/interspect:revert       # Revert override or disable overlays
/interspect:approve      # Approve pending modification

# Diagnostics
/interspect:health       # Signal diagnostics
/interspect:enable-autonomy   # Enable autonomous mode
/interspect:disable-autonomy  # Disable autonomous mode
/interspect:unblock      # Unblock stalled modification

# Skill calibration (add --source-kind=skill to most commands)
/interspect:tune --source-kind=skill <plugin>:<skill>   # Generate a skill overlay
/interspect:status --source-kind=skill                  # Skill calibration view
/interspect:health --source-kind=skill                  # Skill signal coverage

How It Works

Three hooks collect evidence passively:

• SessionStart — records session, consumes kernel events, checks canary alerts
• PostToolUse — records evidence when Task tool is used
• Stop — closes session record

Evidence accumulates in SQLite (.clavain/interspect/interspect.db). When patterns reach counting-rule thresholds, routing overrides can be proposed and applied. Applied overrides enter a canary period (20 uses over 14 days, 20% regression threshold).

Skill Calibration

The same closed loop also tunes skills, not just agents. Every Claude Code Skill invocation captured in ~/.claude/audit.log is drained into the evidence store (source_kind='skill'), scored across four signals (tokens, error, no_redirect, bead_close) against per-skill goal weights, and — when a skill's description triggers too eagerly or too rarely — turned into an overlay at ~/.claude/skill-overlays/<plugin>:<skill>.md that the skill loader merges over the source SKILL.md. Safe-list patches (tighten_description, when_to_use_add) auto-apply under autonomy with canary monitoring; body rewrites and availability changes are always propose-only. Interspect reads only ~/.claude/audit.log for this — tool-time keeps its own events.jsonl untouched.

Architecture

• 12 commands — analysis, override management, canary monitoring, diagnostics
• 3 hooks — passive evidence collection (SessionStart, PostToolUse, Stop)
• 1 core library — hooks/lib-interspect.sh (sourced by all commands and hooks)
• SQLite storage — per-project evidence database
• Routing overrides — .claude/routing-overrides.json (cross-repo contract)

License

MIT