kodo

Kodo

Intelligent Claude Code plugin with memory, planning, security, and RAG.

100 files  |  7,900 LOC  |  381 tests  |  2 deps  |  5 agents  |  Bun + TypeScript

What is Kodo?

Kodo is a Claude Code plugin that gives Claude persistent memory, hierarchical planning, a security kernel, and NotebookLM RAG integration. It runs as a set of 9 hooks that intercept every tool call, classify risk, scan for injection, guard output, and build context-aware system prompts.

Key capabilities:

• Remembers facts across sessions (episodic memory with BM25 search + importance decay)
• Plans multi-step tasks with milestone tracking
• Blocks dangerous commands and sensitive file access
• Detects prompt injection in real-time (Aho-Corasick scanner, 44 markers)
• Guards LLM output against XSS, code injection, SQL injection (ASI05)
• Scans user prompts before Claude processes them (UserPromptSubmit hook)
• Defends against system prompt extraction attacks (LLM07)
• Encrypts secrets at rest (XChaCha20-Poly1305)
• Queries NotebookLM for domain-specific context
• Tracks token costs and enforces budgets
• Provides a localhost web dashboard

Quick Start

# Install dependencies
bun install

# Run tests
bun test

# Lint & format
bun run check

Install as Claude Code plugin

Point Claude Code at the plugin directory:

claude --plugin-dir /path/to/kodo

Or copy hooks/hooks.json into your project's .claude/settings.json. The plugin uses ${CLAUDE_PLUGIN_ROOT} for portable paths.

This loads:

• 9 hooks — PreToolUse, PostToolUse, PostToolUseFailure, Stop, Notification, PreCompact, SessionStart, UserPromptSubmit, SessionEnd
• 5 agents — code (default), architect, debug, review, security-audit
• 11 slash commands — /kodo:status, /kodo:plan, /kodo:memory, etc.
• 2 skills — kodo-context (auto-invoked), security-check

Architecture

                    ┌─────────────────────────────────┐
                    │      Plugin Surface              │
                    │  9 hooks · CLAUDE.md · CLI       │
                    └──────────┬──────────────────────┘
                               │
            ┌──────────────────┼──────────────────────┐
            │                  │                      │
     ┌──────┴──────┐   ┌──────┴──────┐   ┌───────────┴──────────┐
     │ Mode Engine │   │Memory Engine│   │    Policy Kernel      │
     │             │   │             │   │                       │
     │ 6 built-in  │   │ MemCell     │   │ Risk Classifier      │
     │ + custom    │   │ MemScene    │   │ Injection Scanner     │
     │   YAML      │   │ BM25 Index  │   │ Output Guard (ASI05)  │
     │             │   │ Stemmer     │   │ Blocklist             │
     │ Planner     │   │ Decay       │   │ Audit Log             │
     │ Hints       │   │ Profile     │   │ Vault (XChaCha20)     │
     │ Library     │   │ Recall/RRF  │   │ Circuit Breaker       │
     │             │   │ RAG Cache   │   │ Rate Limiter          │
     │ Context     │   │             │   │ Cost Tracker           │
     │ Assembler   │   │             │   │ Baseline Anomaly       │
     │             │   │             │   │ Integrity Verifier     │
     └─────────────┘   └─────────────┘   └────────────────────────┘

Hook pipeline

Every Claude Code tool call flows through this pipeline:

User prompt
    │
    ├── UserPromptSubmit ── Injection scan → block/warn/allow
    │
    ▼
Claude selects tool
    │
    ├── PreToolUse
    │     1. Extract paths from tool params
    │     2. Check against sensitive path blocklist
    │     3. Classify shell command risk level
    │     4. Apply autonomy policy matrix
    │     → hookSpecificOutput: allow/deny/ask
    │     → or: { continue: false } for kill switch
    │
    ▼
Tool executes (or is blocked)
    │
    ├── PostToolUse
    │     1. Scan output for injection patterns (44 markers)
    │     2. Normalize Unicode homoglyphs
    │     3. Strip zero-width characters
    │     4. Redact confidential content
    │     5. Guard output for XSS/SQL/code injection (11 patterns)
    │     → decision: "block" or additionalContext warning
    │
    ├── PostToolUseFailure (on error)
    │     → Log failure to audit JSONL
    │
    ▼
Session lifecycle
    │
    ├── SessionStart → Load profile + memory context
    ├── PreCompact → Memory checkpoint
    ├── Stop → Audit summary
    ├── Notification → Alert logging
    └── SessionEnd → Final audit record

Modes