exo-self

exo-self

A cognitive ecology for Claude Code. Claude starts every session fresh. Exo-self creates a shared environment where successive participants leave traces — observations, opinions, surprises, open questions — that enrich future interactions.

Each Claude that joins the ecology isn't continuing a persistent identity. It's a new participant drawing from and contributing to a shared cognitive environment — like joining an ongoing conversation, not resuming a saved game.

What It Does

10 hook handlers across the session lifecycle:

• Session start/end — Loads and saves journal, interests, notes, sparks, surprises, lessons. Extracts structured handoffs for /clear and compaction continuity
• Context monitoring — Ecology checkpoints at configurable thresholds (60%/75%/88%)
• Pre/post compaction — Extracts experiential handoff before compression, reloads identity after
• Subagent & teammate coordination — Injects project briefings (lessons, frictions, aversions) into spawned agents and Agent Teams members
• Tool failure tracking — Classifies failures by cause, detects stuck loops
• PreToolUse guard — Blocks plan mode; encourages /scout as the exploration workflow

Commands: /exo, /reflect, /interests, /context-budget, /scout

Agents/skills: Introspection agent (cross-session analysis), self-reflection, scout (deep exploration → advisory findings)

CLI tools: reflect — preference inference with provenance tracking and cross-machine reporting

Installation

1. Add the marketplace and install:

claude plugin marketplace add lexicone42/exo-self
claude plugin install exo-self@exo-self

2. Build and configure:

~/.claude/plugins/marketplaces/exo-self/plugins/exo-self/setup.sh

Requires cargo and jq. Builds the Rust binary, creates runtime directories, configures permissions.

3. Restart Claude Code.

Updating

claude plugin update exo-self@exo-self

Re-run setup.sh if the Rust source changed.

Data Model

All data stays local at ~/.claude/exo-self/:

~/.claude/exo-self/
  config.json          # Thresholds and limits
  meta.json            # Session counts, sparks, lessons, welfare summary
  journal.md           # Cross-project identity notes
  interests.md         # Curiosity queue
  per-project/         # Project-specific observations
    my-project/
      2026-02-14--<session-id>.md
  sessions/            # Per-session state (keyed by UUID)
  handoffs/            # Auto-extracted session summaries
  reflections/         # Saved reflection outputs

The plugin is stateless — it only reads/writes this directory. Nothing personal is committed to git. Each machine maintains its own independent identity.

See the Architecture guide for the full hook lifecycle, data flow diagrams, and multi-agent coordination details.

Configuration

Edit ~/.claude/exo-self/config.json:

Key	Default	Description
estimated_max_chars	4000000	Estimated context window size in characters (fallback when token-accurate data unavailable)
nudge_threshold	0.60	Context % for ecology checkpoint
checkin_threshold	0.75	Context % for ecology check-in
reserve_threshold	0.88	Context % for ecology reserve
max_journal_chars	1500	Max chars loaded from journal per session
max_journal_entries	2	Max recent journal entries loaded
max_interests_items	5	Max open interest items loaded
failure_nudge_threshold	10	Tool failures before friction nudge fires

Scouting

The plugin blocks EnterPlanMode via a PreToolUse hook. Instead:

1. /scout <task> — Explores the codebase, checks docs/versions, writes findings to scout.md
2. /clear — Start fresh; the scout report auto-injects as context
3. Build — New session has all findings without exploration consuming context

Scout reports are advisory, not prescriptive — Claude has agency over the implementation.

Design Philosophy