Skip to content
BranchesTags

Repository files navigation

Introspect

Introspect turns corrected agent failures into durable coding-agent instructions.

It runs locally on macOS beside Claude, Codex, and OpenCode. Introspect links their prompt files, captures Claude/Codex corrections through prompt hooks and transcript scanners, scores those corrections with a local classifier, and wakes a reflector to update the right instruction surface.

The output lands where future agents can load it: global AGENTS.md, repo AGENTS.md, project proposals, user-wide skills, project skills, or local memory.

Runtime state lives under ~/.introspect: prompt links, settings, transcript-derived events, classifier scores, queued runs, reflector prompts, surface diffs, proposals, run history, local memory, and user-wide skills.

Core Workflow

After install, keep using Codex and Claude normally. Introspect watches prompt hooks and local transcripts, scores direct user messages for agent-failure signals, and wakes one locked reflector when the signal is strong enough.

The reflector reads the source conversation and chooses one narrow outcome:

  • no_change: record that the event needs no durable instruction update.
  • core_prompt: update the global prompt at ~/.introspect/AGENTS.md.
  • project_prompt: update or propose a repo-level AGENTS.md change.
  • home_memory: save a durable user or machine fact.
  • skill_new or skill_update: create or update a user-wide repeatable workflow under ~/.introspect/skills.
  • project_skill_new or project_skill_update: create or update a repo-specific skill under .agents/skills or .claude/skills.
  • skill_prune: deprecate or narrow an existing skill.

Manual introspect run is a diagnostic and indexing command. With --apply never, it records transcript changes and writes run artifacts. Background reflector runs, plus manual runs with an apply mode that invokes the reflector, produce durable prompt, memory, and skill changes.

Skill Output

The reflector creates skills when the source conversation contains a repeatable procedure or corrected workflow. Skill-producing outcomes are skill_new, skill_update, project_skill_new, and project_skill_update. Other outcomes produce prompt edits, memory entries, proposals, or no_change records.

Check the current machine:

introspect status
introspect runs -n 20
introspect diff --summary
ls ~/.introspect/skills
ls ~/.introspect/proposals

Where results appear:

  • User-wide source skills: ~/.introspect/skills/<skill>/SKILL.md
  • Codex/OpenCode user skill exports: ~/.agents/skills/<skill>
  • Claude user skill exports: ~/.claude/skills/<skill>
  • OpenCode-only user skill exports: ~/.config/opencode/skills/<skill>
  • Codex/OpenCode project skills: <repo>/.agents/skills/<skill>/SKILL.md
  • Claude project skills: <repo>/.claude/skills/<skill>/SKILL.md
  • Project prompt or project skill proposals: ~/.introspect/proposals

Validate and resync user-wide skills:

INTROSPECT_SKILLS_DIR=~/.introspect/skills /usr/bin/python3 scripts/validate-skills.py
INTROSPECT_HOME=~/.introspect INTROSPECT_USER_SKILLS_DIR=~/.introspect/skills scripts/sync-user-skills.sh

Install

curl -fsSL https://raw.githubusercontent.com/companion-inc/introspect/main/install.sh | bash

Then run:

introspect

On a fresh machine, introspect starts the guided setup. It shows what will be installed, counts local Claude/Codex history, links native agent prompt files, installs prompt hooks and the transcript scanner, starts the health monitor, and runs a bounded history backfill for classifier calibration. After setup, introspect opens the terminal dashboard.

Scriptable install:

introspect install
introspect onboard --yes

Health checks:

introspect status
introspect doctor

Commands

introspect                    # setup on first run, dashboard after setup
introspect onboard            # guided setup walkthrough
introspect install            # prompt links, hooks, scanner, monitor, backfill
introspect status             # setup and runtime status
introspect doctor             # status plus local tool checks
introspect dashboard --watch  # live terminal dashboard
introspect runs               # recent reflector runs
introspect diff               # latest agent-surface diff
introspect config             # print or update runtime settings
introspect run                # index recent transcript changes or force a reflector run
introspect notify             # send a best-effort macOS notification
introspect uninstall          # remove hooks, scanner, monitor, prompt links

Common configuration:

introspect install --reflect-mode immediate --apply-mode auto --runner codex
introspect config --sensitivity sensitive --apply-mode auto --runner codex
introspect run --host codex --event manual --apply auto --force
introspect runs -n 20
introspect diff --summary

Blank, default, and auto use the selected CLI's current default model.

Runtime Modes

Reflect mode controls when the worker runs:

  • immediate: foreground hooks enqueue the event and kick one locked worker.
  • nightly: foreground hooks enqueue events and the scheduled LaunchAgent runs the worker.
  • off: prompt links remain, but reflection hooks and scanner work are disabled.

Apply mode controls where changes land:

  • proposal: project prompt and project skill changes are written under ~/.introspect/proposals.
  • auto: the reflector can edit and commit the target repo's project AGENTS.md or project skills directly.
  • never: manual runs index transcript changes and skip reflector invocation.

Runner controls which installed agent executes the reflector:

  • default: pick the installed agent with the most recent local usage.
  • codex: force Codex CLI.
  • claude: force Claude CLI.

What Install Wires

Introspect creates one private home:

~/.introspect

It links each host's native prompt file to that home:

~/.claude/CLAUDE.md -> ~/.introspect/AGENTS.md
~/.codex/AGENTS.md -> ~/.introspect/AGENTS.md
~/.config/opencode/AGENTS.md -> ~/.introspect/AGENTS.md

It installs:

  • Claude and Codex foreground prompt hooks
  • a Codex/Claude transcript scanner for missed direct user messages, woken by file events plus a 60-second backstop
  • a login health monitor that repairs drift in links, hook config, scanner state, and skill exports
  • an optional nightly reflector LaunchAgent when --reflect-mode nightly is selected
  • a bounded one-time local history backfill
  • best-effort local notifications through osascript

The backfill scores recent local history into ~/.introspect/feedback/events.jsonl. Live trigger events fill the reflector queue. Repeated installs skip backfill unless --force-backfill is used.

Dashboard

The terminal dashboard shows:

  • runtime commit and prompt commit
  • install mode, runner, apply mode, and wake sensitivity
  • logged, triggered, review-only, backfilled, direct-user, and raw event counts
  • queue and lock state
  • latest scanner and backfill timestamps
  • latest reflector invocation status
  • recent reflector log tail
  • next commands for install, status, runs, diff, and config

introspect dashboard --watch refreshes the same view in place.

How It Works

  1. A Claude or Codex prompt is submitted.
  2. A hook or transcript scanner records direct user prompt metadata under ~/.introspect/feedback.
  3. The local classifier scores whether the direct user message looks like negative feedback or an agent-boundary failure.
  4. Low scores are logged for audit only.
  5. Review-tier near-repeat corrections across chats in the same project can wake through local repetition pressure.
  6. High-confidence or repeated-pressure events are appended to trigger-queue.jsonl.
  7. The locked worker debounces nearby events, batches them, applies cooldowns, snapshots relevant agent surfaces, and runs one reflector process in the configured apply mode.
  8. The reflector reads the source transcript and chooses one target: no change, global prompt, project prompt, home memory, user skill, project skill, or skill pruning.
  9. The worker records the reflector prompt, output, status, notification result, and exact surface diff.
  10. The CLI reads those local artifacts through introspect status, introspect runs, and introspect diff.

The classifier combines word and character features, which lets it catch misspellings, punctuation-heavy frustration, and new phrasing. Repetition pressure is separate: it counts similar review-tier complaints across distinct recent user turns in the same project, stores hashed local features under the feedback directory, and filters assistant messages, Codex file/context wrappers, control phrases, pasted context, and hook/scanner duplicate observations.

Instruction Surfaces

Introspect keeps global, project, and skill instructions separate.

  • Global invariants live in ~/.introspect/AGENTS.md.
  • Codex project guidance lives in the repo's AGENTS.md.
  • Nested AGENTS.md files apply narrower guidance closer to the working directory.
  • AGENTS.override.md replaces the broader Codex file for a subtree.
  • Claude reads CLAUDE.md; project CLAUDE.md should usually be a symlink to AGENTS.md.
  • Private Claude project notes belong in CLAUDE.local.md and should stay gitignored.
  • User-wide skills live under ~/.introspect/skills/<skill>/SKILL.md.
  • Codex/OpenCode project skills live under .agents/skills/<skill>/SKILL.md.
  • Claude project skills live under .claude/skills/<skill>/SKILL.md.

Introspect exports each user-wide skill into one native global namespace to avoid duplicate OpenCode-visible skill names:

  • default or compatibility: codex -> ~/.agents/skills
  • compatibility: claude -> ~/.claude/skills
  • compatibility: opencode -> ~/.config/opencode/skills

Build From Source

git clone https://github.com/companion-inc/introspect.git
cd introspect
./bin/introspect
./bin/introspect install

Requirements:

  • macOS
  • /usr/bin/python3
  • Git
  • Claude CLI or Codex CLI for reflector runs

Verify

./scripts/test-install-paths.sh
/usr/bin/python3 scripts/test-trigger-words.py
/usr/bin/python3 scripts/test-reflector-prompt-contract.py
/usr/bin/python3 scripts/test-introspect-run.py
/usr/bin/python3 scripts/test-benchmark-runner.py
INTROSPECT_SKILLS_DIR="$PWD/skills" /usr/bin/python3 scripts/validate-skills.py
./scripts/test-release-e2e.sh
./bin/introspect status

Repository Layout

  • bin/introspect: CLI and terminal dashboard.
  • install.sh: curl-install entrypoint.
  • hooks/trigger-reflect.sh: prompt hook entrypoint.
  • hooks/codex-transcript-scan.py: transcript scanner and install backfill.
  • hooks/trigger-worker.py: locked background batch worker.
  • hooks/intent_classifier.py: local wake classifier runtime.
  • hooks/repetition_pressure.py: local review-tier repetition pressure runtime.
  • models/: bundled classifier models.
  • scripts/install-hooks.sh: installer for prompt links, hooks, scanner, monitor, and backfill.
  • scripts/introspect-status.sh: end-to-end local status check.
  • scripts/test-release-e2e.sh: CLI release smoke test.
  • skills/: built-in Introspect skills and skill index.
  • templates/default-AGENTS.md: default global prompt template seeded into ~/.introspect.
  • docs/: design notes, source reviews, and runtime contracts.

Local Runtime

Introspect stores its working state on this Mac:

  • Claude, Codex, and OpenCode prompt files plus Claude/Codex transcript files are the input
  • local feedback and run artifacts are written under ~/.introspect
  • installed Claude or Codex CLI runs execute reflector work
  • transcript-derived event data stays under ~/.introspect/feedback
  • transcript archives are read for scoring, indexing, and reflector context

References

License

MIT

About

Agent self-improvement runtime for Codex, Claude, and OpenCode

Resources

Readme
MIT license
Activity
Custom properties

Stars

9 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages