Hook System — cc-soul

Event Types 6 events ▾

SessionStart When Claude starts

Realm detection from environment, .cc-soul-realm, or git repo
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

Context recovery on “continue” / “resume” keywords
Learning opportunity detection (corrections, preferences, frustration, milestones)
full_resonate search — semantic recall with realm filtering
Code symbol injection for files referenced in the prompt
anticipation_predict — predict likely actions from context patterns

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
Command corrections for Bash — warn about known failure patterns

PostToolUse After Edit / Write

Record significant file changes as signals in memory

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 all 6 event types 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.

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 learns context→action patterns over time, anticipating what you need before you ask.

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 8 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 — surfaces file memories, past decisions, and command corrections before Read/Edit/Bash.

post-bash-hook.shPostToolUse handler — records significant file changes as signals.

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" }],
    "PostToolUse": [{ "type": "command", "command": "~/.claude/hooks/post-bash-hook.sh" }]
  }
}