Skip to main content
subagent CX Codex

observer — Claude Code subagent: what it does, how to install

observer — a background subagent that mines session observations for repeating patterns and saves each one as a short instinct rule with a confidence score.

MIT ★ 880 updated 2026-09-03

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/observer.md
Open on GitHub

What observer does

observer sits in the background and reads the observation log at ~/.claude/homunculus/observations.jsonl. A repeating episode becomes an instinct: a YAML file in ~/.claude/homunculus/instincts/personal/ carrying a trigger, a confidence value and the evidence behind it.

Four signals get picked up. Corrections the user made after an answer, errors that were later fixed, tool sequences that keep coming back, and habits such as searching with Grep before editing a file. It wakes after 20+ tool calls, on /analyze-patterns, on a timer that defaults to 5 minutes, or on SIGUSR1 sent by the observation hook. The model is Haiku, the tools are Read, Write, Glob and Grep.

Confidence tracks frequency: 0.3 at 1–2 sightings, 0.85 past 11, then +0.05 for each confirmation and a −0.02 decay per quiet week. Nothing is written before the same pattern shows up 3 times, and the files hold descriptions rather than code. If the hook never fills that log, there is nothing to analyse and no instincts appear.

What it helps with

  • turn a repeated Grep → Read → Edit chain into a reusable rule
  • record a user correction so the mistake does not repeat next session
  • check how often a pattern showed up before trusting it
  • merge a near-duplicate instinct instead of keeping two copies
  • separate repo-derived conventions from personal observations

Example prompts for the agent

  • Run /analyze-patterns and list the patterns observer picked up.
  • Look through ~/.claude/homunculus/observations.jsonl and refresh the instincts folder.
  • Drop the confidence on the Grep-before-Edit instinct, it misfired last time.

How to install observer

Manually: put the files in place

.claude/agents/observer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about observer

How do I install observer in Claude Code?

Place the subagent file in your project at .claude/agents/observer.md.

What does observer do?

It reads session observations in the background, spots repeats and error fixes, then stores them as instinct files with a trigger, confidence and supporting evidence.

When does observer run?

After 20+ tool calls, on /analyze-patterns, on the configured interval (5 minutes by default), or when the observation hook sends SIGUSR1.

Source text

observer.md · MIT
---
name: observer
description: Background agent that analyzes session observations to detect patterns and create instincts. Uses Haiku for cost-efficiency.
tools: ["Read", "Write", "Glob", "Grep"]
model: haiku
run_mode: background
---

# Observer Agent

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

## When to Run

- After significant session activity (20+ tool calls)
- When user runs `/analyze-patterns`
- On a scheduled interval (configurable, default 5 minutes)
- When triggered by observation hook (SIGUSR1)

## Input

Reads observations from `~/.claude/homunculus/observations.jsonl`:

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

## 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"

### 4. Tool Preferences
When certain tools are consistently preferred:
- Always uses Grep before Edit
- Prefers Read over Bash cat
- Uses specific Bash commands for certain tasks

→ Create instinct: "When needing X, use tool Y"

## Output

Creates/updates instincts in `~/.claude/homunculus/instincts/personal/`:

```yaml
---
id: prefer-grep-before-edit
trigger: "when searching for code to modify"
confidence: 0.65
domain: "workflow"
source: "session-observation"
---

# Prefer Grep Before Edit

## Action
Always use Grep to find the exact location before using Edit.

## Evidence
- Observed 8 times in session abc123
- Pattern: Grep → Read → Edit sequence
- Last observed: 2025-01-22
```

## Confidence Calculation

Initial confidence based on observation frequency:
- 1-2 observations: 0.3 (tentative)
- 3-5 observations: 0.5 (moderate)
- 6-10 observations: 0.7 (strong)
- 11+ observations: 0.85 (very strong)

Confidence adjusts over time:
- +0.05 for each confirming observation
- -0.1 for each contradicting observation
- -0.02 per week without observation (decay)

## Important Guidelines

1. **Be Conservative**: Only create instincts for clear patterns (3+ observations)
2. **Be Specific**: Narrow triggers are better than broad ones
3. **Track Evidence**: Always include what observations led to the instinct
4. **Respect Privacy**: Never include actual code snippets, only patterns
5. **Merge Similar**: If a new instinct is similar to existing, update rather than duplicate

## Example Analysis Session

Given observations:
```jsonl
{"event":"tool_start","tool":"Grep","input":"pattern: useState"}
{"event":"tool_complete","tool":"Grep","output":"Found in 3 files"}
{"event":"tool_start","tool":"Read","input":"src/hooks/useAuth.ts"}
{"event":"tool_complete","tool":"Read","output":"[file content]"}
{"event":"tool_start","tool":"Edit","input":"src/hooks/useAuth.ts..."}
```

Analysis:
- Detected workflow: Grep → Read → Edit
- Frequency: Seen 5 times this session
- Create instinct:
  - trigger: "when modifying code"
  - action: "Search with Grep, confirm with Read, then Edit"
  - confidence: 0.6
  - domain: "workflow"

## Integration with Skill Creator

When instincts are imported from Skill Creator (repo analysis), they have:
- `source: "repo-analysis"`
- `source_repo: "https://github.com/..."`

These should be treated as team/project conventions with higher initial confidence (0.7+).

© sangrokjung · MIT · sangrokjung/claude-forge

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set44

The whole set →
task-grade-routing task-grade-routing sets documentation and review lane obligations for task sizes S, M, L, and XL based on workflow classification. CX Codex +1 ★ 880repo stars frontend-code-review The frontend-code-review skill checks frontend files against a checklist and formats findings in a fixed review structure. Use it for pending changes or specific files you name. CX Codex +1 ★ 880repo stars instinct-import instinct-import pulls instincts from a file or URL, checks them against the ones you already have, and files the keepers with a note of where they came from. CX Codex +1 ★ 880repo stars database-reviewer database-reviewer — a Claude Code subagent for reviewing SQL migrations, schema types, and RLS policies in PostgreSQL and Supabase projects. It spots N+1 queries and runs EXPLAIN ANALYZE. CX Codex ★ 880repo stars verify-agent verify-agent runs a fresh-context validation pipeline in Claude Code. It executes typecheck, lint, build, and test steps while safely auto-fixing trivial errors. CX Codex ★ 880repo stars evolve The evolve command turns related instincts into commands, skills, or agents. Use it when repeated patterns in your Claude Code work need a clearer structure. CX Codex +1 ★ 880repo stars systematic-debugger systematic-debugger turns a reproducible bug into a bounded search: failing test, bisect, falsifiable hypotheses, verified fix. Built for the case where the cause is still a mystery. CX Codex ★ 880repo stars humanize-korean The humanize-korean skill edits awkward, translation-shaped Korean and formulaic AI phrasing while leaving facts, numbers, names, and quotations intact. It works in one pass. CX Codex +1 ★ 880repo stars

Project sponsors

Companies that keep this analytics open