Use this skill when setting up, using, or troubleshooting Terraphim's automatic learning capture system that records failed commands and their context.
Overview
Terraphim learning capture automatically records bash command failures during AI-assisted development sessions. Each failure is stored as a structured Markdown document with the command, error output, exit code, working directory, and timestamp.
Key Capabilities:
- Automatic capture via PostToolUse Claude Code hook
- Structured Markdown storage in
~/.local/share/terraphim/learnings/ - Query past failures by command pattern
- Add corrections to existing learnings
- Install hooks for Claude Code, Codex, and OpenCode
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Claude Code (PostToolUse) │
│ Hook fires after every Bash tool call │
└───────────────────────┬─────────────────────────────────────┘
│ JSON: {tool_name, tool_input, tool_result}
▼
┌─────────────────────────────────────────────────────────────┐
│ ~/.claude/hooks/learning-capture.sh │
│ - Filters: only Bash tools, only non-zero exit codes │
│ - Skips: test commands (cargo test, npm test, etc.) │
│ - Fail-open: continues even if capture fails │
└───────────────────────┬─────────────────────────────────────┘
│ terraphim-agent learn capture ...
▼
┌─────────────────────────────────────────────────────────────┐
│ terraphim-agent learn capture │
│ Stores structured learning document with YAML frontmatter │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ~/.local/share/terraphim/learnings/learning-*.md │
│ YAML frontmatter: id, command, exit_code, captured_at, tags │
│ Body: ## Command, ## Error Output sections │
└─────────────────────────────────────────────────────────────┘
For Humans
Quick Install
# Install the PostToolUse hook for Claude Code automatically
terraphim-agent learn install-hook claude
# Or manually: add to ~/.claude/settings.json under hooks.PostToolUse
# See the hook script at ~/.claude/hooks/learning-capture.sh
Manual Hook Script Setup
Create ~/.claude/hooks/learning-capture.sh:
#!/bin/bash
# Read JSON from stdin, call terraphim-agent learn hook
INPUT=$(cat)
echo "$INPUT" | terraphim-agent learn hook
echo "$INPUT"
Add to ~/.claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [{"type": "command", "command": "~/.claude/hooks/learning-capture.sh"}]
}
]
}
}
Querying Learnings
# List recent captured failures
terraphim-agent learn list
# Search by command pattern
terraphim-agent learn query "cargo build"
terraphim-agent learn query "git push"
# Add a correction to an existing learning
terraphim-agent learn correct <id> "Use 'cargo build --release' instead"
Learning Document Format
Each captured learning is stored as:
---
id: <hash>-<timestamp>
command: <failed command>
exit_code: <non-zero code>
source: Global
captured_at: <ISO timestamp>
working_dir: <project directory>
tags:
- learning
- exit-<code>
---
## Command
`<command that failed>`
## Error Output
<stderr/stdout from the failure>
For AI Agents
Before Running a Risky Command
Query learnings to check if a similar command has failed before:
terraphim-agent learn query "<command keyword>"
If results exist, review the error patterns and corrections before proceeding.
After a Session
Review recent learnings to identify recurring patterns:
terraphim-agent learn list
Debug Mode
Enable debug output from the hook:
export TERRAPHIM_LEARN_DEBUG=true
When to Use This Skill
- Setting up a new development environment (run
install-hook) - Diagnosing why the hook is not capturing failures
- Reviewing accumulated learnings before starting a complex task
- Adding corrections after discovering the right fix for a recurring error
- Configuring hook behavior (filtering, debug mode)
Trigger Phrases
- "why isn't learning capture working"
- "set up learning capture"
- "check my learnings for..."
- "what failed when I tried to..."
- "install the learning hook"
- "debug learning capture"
Configuration
| Variable | Default | Description |
|---|---|---|
TERRAPHIM_LEARN_DEBUG |
false |
Enable debug logging from hook |
| Storage path | ~/.local/share/terraphim/learnings/ |
Where learnings are stored |
Supported AI Agents
| Agent | Install Command |
|---|---|
| Claude Code | terraphim-agent learn install-hook claude |
| OpenAI Codex | terraphim-agent learn install-hook codex |
| OpenCode | terraphim-agent learn install-hook opencode |