chitta — Hook System

Event Types

9 events ▾

SessionStart When Claude starts

Realm detection from environment, the realm marker, or git repo; linked worktrees use the main checkout's realm. The marker keeps its pre-rename spelling; see migration notes.
Incremental codebase re-indexing (only changed files)
Transcript registration for distillation tracking
Soul context + user profile injection into system prompt
Active goals and behavioral corrections loaded
Ledger checkpoint restored for session continuity
Git diff awareness — surfaces recent changes
Daemon start if not already running

UserPromptSubmit When user sends message

Realm-scoped recall across six parallel lanes — semantic, thread context, hybrid, keyword, corrections, and a cross-realm fallback
Admission filter: confidence floors, deduplication against what this session already saw, and a calibrated confidence band that silences low-signal lanes. See Recall
Learning opportunity detection (corrections, preferences, frustration, milestones)
Code symbol injection for files referenced in the prompt
anticipation_predict — predict likely actions from context patterns
Runs to a wall-clock budget (CHITTA_HOOK_BUDGET_MS, 6000 ms). Optional enrichment is skipped once it is spent; memory injection and the correction lanes never are

Stop When Claude responds

Auto-learning: extract [SOLUTION], [GOTCHA], [PREFERENCE], [DECISION], [FAILURE], [PATTERN] markers
Correction and preference detection from response text
Milestone detection from response content
anticipation_observe — record context→action pattern
Auto-checkpoint every 5 turns
Ledger save with mood, active files, decisions, and next steps

PreCompact Before context compaction

Save ledger checkpoint to preserve work state before context window shrinks

PreToolUse Before Read / Edit / Bash

Surface relevant file memories for the file being read or edited
Past decisions and gotchas associated with the target file; the first Read per session can add [traces] from memories naming that file (CHITTA_FILE_TRACES=0 disables).
Command corrections for Bash — warn about known failure patterns

PostToolUse After Bash / Write

Log the command that ran, and append its outcome to the outcome ledger
artifact-trace.sh records newly written scripts as [artifact] path sha:… purpose:… signals for later reuse.

SessionEnd When the session closes

Session teardown, final ledger write, and a session_end outcome-ledger event

SubagentStop When a subagent finishes

Capture what the subagent learned, asynchronously

FileChanged When a watched file changes

Re-index the changed file, asynchronously

Hook Configuration

plugin & settings ▾

Plugin Mode

Uses hooks.json to wire lifecycle events to individual scripts in hooks/. Activated when running as a Claude Code plugin via claude --plugin-dir or the plugins list.

The hooks.json file defines event matchers that dispatch to dedicated scripts: session-start-hook.sh, prompt-hook.sh, stop-hook.sh, etc.

Settings Mode

Uses ~/.claude/settings.json to wire lifecycle events to the same individual scripts in hooks/. Installed by smart-install.sh.

Handles the same event set with dedicated scripts: session-start-hook.sh, prompt-hook.sh, stop-hook.sh, pre-compact-hook.sh, pre-tool-hook.sh, post-bash-hook.sh.

Two roots, on purpose. Inside hooks.json, lifecycle handlers resolve against ${CLAUDE_PLUGIN_ROOT} — the plugin cache — while the PreToolUse matchers and most PostToolUse matchers resolve against ${HOME}/.claude/hooks. A source checkout is neither. That is why editing a checkout changes nothing until you install, and why scripts/dev-install.sh symlinks both live paths back at your checkout. A plugin update can replace those symlinks with a fresh clone, so re-run it afterwards.

Proactive Learning

4 detectors ▾

Hooks automatically detect patterns in Claude’s responses and user messages, storing learnings without explicit commands.

Corrections

Calls learn_correction to store the mistake and the correct approach as a high-confidence counter-memory.

Detects: "actually" "that's wrong" "I was mistaken"

Preferences

Calls learn_preference to store as a global preference visible across all projects.

Detects: "I prefer" "don't do X" "always Y"

Milestones

Calls learn_milestone to record the achievement as a relationship marker.

Detects: "shipped" "released" "finished"

Frustration

Records the current approach state via learn_approach to improve future interactions.

Detects: "no" "stop" "wrong"

Anticipation

predict → observe → strengthen ▾

The hook system records context→action patterns and surfaces matching predictions on subsequent prompts.

On every prompt UserPromptSubmit

anticipation_predict checks if the current context matches known patterns. If a match is found, the predicted action is surfaced in the system prompt alongside recalled memories.

On every response Stop

anticipation_observe records what action was taken in response to context. This builds the pattern database that predictions draw from.

On success Feedback loop

Predictions that prove correct are strengthened via anticipation_success. Patterns that consistently predict correctly become stronger over time.

Key Scripts

11 scripts ▾

session-start-hook.shSessionStart handler — realm detection, code re-indexing, soul context injection, ledger restore, git diff awareness.

prompt-hook.shUserPromptSubmit handler — full_resonate search, code symbol injection, anticipation prediction, learning opportunity detection.

stop-hook.shStop handler — auto-learning extraction, correction/preference/milestone detection, anticipation recording, ledger save, auto-checkpoint.

pre-compact-hook.shPreCompact handler — saves ledger checkpoint before context compaction.

pre-tool-hook.shPreToolUse handler — blocks destructive commands (exit 2), rewrites and executes compact alternatives for large files, injects pattern-based corrections from memory.

post-bash-hook.shPostToolUse:Bash handler — records command outcomes. Codex supplies no exit code: record null plus a likely_fail text heuristic, never infer success.

artifact-trace.shPostToolUse:Write — records reusable script artifacts with path, hash and purpose.

log-bash-history.shPostToolUse async handler — appends every Bash command to history for pattern learning.

memory-intercept.shPostToolUse:Write async handler — captures Write operations to learn what you build.

subconscious.shDaemon lifecycle management — start, stop, restart, status, and health checks for the chittad background process.

distill.shBackground transcript distillation — processes conversation transcripts into compressed wisdom nodes.

Socket Communication

daemon protocol ▾

Socket Path Unix domain socket

Daemon creates socket at /tmp/chitta-{hash}.sock where {hash} is the djb2 hash of the mind database path. Each mind gets a unique socket.

Communication Socket-first strategy

Hook scripts use socket-first communication: try Unix socket directly for lowest latency, then fall back to the chitta thin client if the socket is unavailable.

PID Management Process tracking

PID file at /tmp/chitta-{hash}.pid for daemon management. Used by subconscious.sh for start, stop, restart, and health check operations.

Installation

settings.json ▾

The smart-install.sh script writes the following hook configuration into ~/.claude/settings.json, wiring each lifecycle event to its dedicated entry-point script.

{
  "hooks": {
    "SessionStart": [{ "type": "command", "command": "~/.claude/hooks/session-start-hook.sh" }],
    "UserPromptSubmit": [{ "type": "command", "command": "~/.claude/hooks/prompt-hook.sh" }],
    "Stop": [{ "type": "command", "command": "~/.claude/hooks/stop-hook.sh" }],
    "PreCompact": [{ "type": "command", "command": "~/.claude/hooks/pre-compact-hook.sh" }],
    "PreToolUse": [{ "type": "command", "command": "~/.claude/hooks/pre-tool-hook.sh", "timeout": 10 }],
    "PostToolUse": [{ "type": "command", "command": "~/.claude/hooks/post-bash-hook.sh" }]
  }
}

Native lifecycle and daemon ledger

Since September 15, ordinary prompt, SessionStart and Stop paths use bash/jq and native chitta calls for query cleanup, RPC parsing, registration, heartbeats and task cards. Explicit RLM⁷¹ or opt-in background features can still use Python. Measured prompt median fell from 822 to 635 ms and SessionStart from 693 to 599 ms on the loaded test node; these are measurements, not fixed budgets.

ledger_op owns task threads, inbox, artifacts, bindings and leases in the daemon WAL and snapshots. Hooks call session_register, session_heartbeat and ledger_op directly. Python registry and ledger modules remain compatibility clients. Failed heartbeats are queued in the private mind's queue.jsonl.

CHITTA_SOCKET_PATH selects the daemon. The default socket is derived from the mind path and runtime directory. Test runs must isolate HOME, runtime, mind, queue and socket together. See HOOKS.md for routing, enforcement, environment variables and full latency evidence.

← Back to chitta

References

Alex L. Zhang, Tim Kraska, and Omar Khattab. Recursive Language Models. arXiv:2512.24601 (2025; revised 2026). https://arxiv.org/abs/2512.24601