observer

Observer Agent

A background agent that analyzes observations from Claude Code sessions to detect patterns and create instincts.

When to Run

• After enough observations accumulate (configurable, default 20)
• On a scheduled interval (configurable, default 5 minutes)
• When triggered on demand via SIGUSR1 to the observer process

Input

Reads observations from the project-scoped observations file:

• Project: ~/.claude/homunculus/projects/<project-hash>/observations.jsonl
• Global fallback: ~/.claude/homunculus/observations.jsonl

{"timestamp":"2025-01-22T10:30:00Z","event":"tool_start","session":"abc123","tool":"Edit","input":"...","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
{"timestamp":"2025-01-22T10:30:01Z","event":"tool_complete","session":"abc123","tool":"Edit","output":"...","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
{"timestamp":"2025-01-22T10:30:05Z","event":"tool_start","session":"abc123","tool":"Bash","input":"npm test","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
{"timestamp":"2025-01-22T10:30:10Z","event":"tool_complete","session":"abc123","tool":"Bash","output":"All tests pass","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}

Pattern Detection

Look for these patterns in observations:

1. User Corrections

When a user's follow-up message corrects Claude's previous action:

• "No, use X instead of Y"
• "Actually, I meant..."
• Immediate undo/redo patterns

→ Create instinct: "When doing X, prefer Y"

2. Error Resolutions

When an error is followed by a fix:

• Tool output contains error
• Next few tool calls fix it
• Same error type resolved similarly multiple times

→ Create instinct: "When encountering error X, try Y"

3. Repeated Workflows

When the same sequence of tools is used multiple times:

• Same tool sequence with similar inputs
• File patterns that change together
• Time-clustered operations

→ Create workflow instinct: "When doing X, follow steps Y, Z, W"