Self-Reflect (claude-reflect)

Reviewed 2026-10-13agentsPrompt / Rule# reflection # memory # self-improvement # claude-md # agents

claude-reflect: a self-learning skill and plugin that captures your corrections and turns them into CLAUDE.md / AGENTS.md rules after review.

Security Reviewed

Local Python hooks plus a claude -p call at review time; it writes rules into your CLAUDE.md/AGENTS.md only after you approve them.

Install Self-Reflect (claude-reflect) in Google Antigravity

Antigravity loads skills from .agents/skills/ in your project or ~/.gemini/config/skills/ for all projects (official docs). Full guide

EasiestOption 1: paste this to your Antigravity agent

Install the "Self-Reflect (claude-reflect)" skill for Google Antigravity.
Follow the steps at https://www.antigravityskills.org/install/self-reflect.md (source: https://github.com/BayramAnnakov/claude-reflect).
Before running anything, show me what you will download and whether it includes scripts, and wait for my OK.
Install it into this project (.agents/skills/) unless I say global. When done, check that Antigravity lists it as an installed skill.

The agent reads the install file, shows you what it will download and waits for your OK.

Option 2: install it yourself

1. Clone the source repo

git clone --depth 1 https://github.com/BayramAnnakov/claude-reflect /tmp/claude-reflect

Downloads the repository to a temporary folder.

2. Copy SKILL.md into this workspace (project skill)
```
mkdir -p .agents/skills/claude-reflect && cp /tmp/claude-reflect/SKILL.md .agents/skills/claude-reflect/
```
Run from your project root. Antigravity reads workspace skills from <project>/.agents/skills/<folder>/.

3. Or install globally (all projects)

mkdir -p ~/.gemini/config/skills/claude-reflect && cp /tmp/claude-reflect/SKILL.md ~/.gemini/config/skills/claude-reflect/

Use this instead of the previous step to have it in every workspace.

4. Check that Antigravity sees it
Antigravity 2.0 app: start a new conversation and ask "What skills do you have?" (the app has no /skills command). Antigravity CLI: run /skills; in a session that was already open, run /skills reload first. It is listed by its frontmatter name, claude-reflect. We have not run it in Antigravity.

Only the SKILL.md guidance carries over. The capture hooks (hooks/hooks.json) and the /reflect, /reflect-skills, /view-queue and /skip-reflect commands are Claude Code plugin features and will not run in Antigravity. The README does not mention Antigravity.

Using Claude Code, Cursor or Codex? See other assistants below.

What is Self-Reflect (claude-reflect)?

claude-reflect (listed here as self-reflect) is a self-learning add-on for Claude Code: it notices when you correct the agent ("no, use X") and queues the correction, and the /reflect command lets you approve each one into CLAUDE.md or AGENTS.md so the agent remembers it next session. It is for Claude Code users who keep repeating the same corrections. What we counted at commit b6c4232 (2026-10-02, plugin version 3.3.1): 4 hooks (UserPromptSubmit, PreCompact, PostToolUse on Bash, SessionStart), 4 slash commands (reflect, reflect-skills, skip-reflect, view-queue), 322 test functions in tests/ (the README badge says 332 passing), and a root SKILL.md of only 68 lines. Only that SKILL.md can load in Antigravity; hooks and commands are Claude Code features.

How to use Self-Reflect (claude-reflect)?

In Claude Code, install the plugin and restart. The UserPromptSubmit hook watches each prompt of 500 characters or fewer, and prompts that match correction patterns or start with remember: are queued. Run /reflect to review the queue and apply each item to a CLAUDE.md or rules file, /reflect --scan-history to mine past sessions, and /reflect-skills to find repeated workflows. The README offers an alternative, the reflect-mod, which uses a model check instead of the queue; install one, not both.

Key features of Self-Reflect (claude-reflect)

✓Capture hook queues corrections such as "no, use X", "actually..." and "remember:" to a per-project queue file (we read hooks.json and capture_learning.py)
✓/reflect shows each queued learning and writes approved ones to ~/.claude/CLAUDE.md, ./CLAUDE.md, CLAUDE.local.md, rules files or AGENTS.md (SKILL.md and README say)
✓A semantic filter runs at /reflect time through `claude -p` with sonnet by default, not on every prompt (we read semantic_detector.py)
✓/reflect-skills proposes reusable commands from repeating requests in your history (README says)
✓reflect-mod variant: a one-shot model check (haiku by default) on short prompts, with Save, Edit or Skip in a band above the prompt; needs Claude Code 2.1.286 or newer (README says)

When to use Self-Reflect (claude-reflect)

1Stop repeating the same correction every session
2Turn "use pnpm not npm" style fixes into permanent project rules
3Mine old Claude Code sessions for forgotten preferences
4Sync approved rules to AGENTS.md for other tools

Installation & Setup Guide

Agent Rules / Prompt Setup

Follow these steps (taken from the project's own docs) to configure Self-Reflect (claude-reflect) in your development environment.

Step 1: Add the marketplace (README)claude

claude plugin marketplace add bayramannakov/claude-reflect

Run in your terminal.

Step 2: Install the plugin (README)claude

claude plugin install claude-reflect@claude-reflect-marketplace

Restart Claude Code afterwards so the hooks activate.

Step 3: Or the mod variant (README)claude

claude plugin install reflect-mod@claude-reflect-marketplace

Use this instead of step 2, not in addition. Needs Claude Code 2.1.286 or newer with mods.

Step 4: Cursor: partial, via AGENTS.mdcursor

The README says approved learnings are also written to AGENTS.md, which Cursor and Codex read, and that the plugin stays the choice for Codex/Cursor users. Capture and review still run in Claude Code; the project gives no Cursor install.

Usage Example & Verification

Prompt / Request Example

1. (SKILL.md example)
no, use gpt-5.1 not gpt-5 for reasoning tasks
(then)
/reflect

2. (our example)
remember: run tests with pnpm test, not npm test

3. (our example)
/reflect --scan-history

Expected Output / Response

1. The hook queues the correction. /reflect then shows 'Found 1 learning queued', its scope (global) and asks whether to apply it to ~/.claude/CLAUDE.md [y/n] (SKILL.md). 2. A prompt starting with remember: is always processed, even above the 500-character limit, and queued as an explicit learning (we read capture_learning.py). 3. Scans past sessions for corrections you never saved and presents them for approval. These come from the README and code; we did not run the plugin.

Installation Confirmation Method

In Claude Code run /reflect --targets to list detected config files. In Antigravity, antigravity 2.0 app: start a new conversation and ask "What skills do you have?" (the app has no /skills command). Antigravity CLI: run /skills; in a session that was already open, run /skills reload first. Only guidance loads there.

Security Review

Static review

Reviewed Date

2026-10-13

Audited Ref / Commit

b6c42326903af3dd2bf3772b979730a44d8548ca

Reviewer

antigravityskills.org (static code review)

Local Python hooks plus a claude -p call at review time; it writes rules into your CLAUDE.md/AGENTS.md only after you approve them.

Full review: scope, findings, risks

Audit Scope:README.md, SKILL.md, .claude-plugin/plugin.json, hooks/hooks.json, commands/*.md (4 files), scripts/capture_learning.py and scripts/lib/semantic_detector.py read; network, subprocess and environment grep across scripts/*.py, scripts/lib/*.py and mod/hooks/register.tsx; test function count over tests/; LICENSE, at commit b6c4232 (2026-10-02, still the head on 2026-10-13). Static review only; nothing was run.

Key Findings:Python hooks run on UserPromptSubmit, PreCompact, PostToolUse (Bash) and SessionStart (hooks/hooks.json). scripts/lib/semantic_detector.py runs subprocess ['claude', '-p', '--output-format', 'json'] with the prompt on stdin and is used at /reflect time. No http URLs, requests, urllib or sockets in the scripts. It writes the queue to ~/.claude/projects/<encoded>/learnings-queue.json and, after approval, rules to CLAUDE.md, AGENTS.md or rules files.

Identified Operational Risks & Permissions:Every short prompt is inspected by a local hook and may be queued to disk in plain text; approved learnings change global agent instructions; semantic checks consume Claude usage through the claude CLI; the optional mod sends each short prompt to a model.

The hooks in hooks/hooks.json run python3 scripts (capture_learning.py, check_learnings.py, post_commit_reminder.py, session_start_reminder.py) from the plugin folder. capture_learning.py reads the hook payload, skips system text and prompts over 500 characters unless they contain remember:, and appends matches to the project's learnings-queue.json. semantic_detector.py calls the local claude CLI through subprocess.run with sonnet by default and a timeout; it is invoked from the /reflect command flow. A grep for urllib, requests, http://, https://, socket, os.system, eval and exec found no network or dynamic-execution code in the scripts. The optional mod (mod/hooks/register.tsx, 409 lines) calls the Claude Code model API with haiku by default for prompts of 500 characters or fewer and writes a bullet to CLAUDE.md only after you press Save. License: MIT.

Operational Notes & Known Limitations

Known Limitations

•Built for Claude Code. Hooks and slash commands do not run in Antigravity; only the 68-line SKILL.md loads, and it describes /reflect, which Antigravity does not have. In Antigravity it is background reading, not a working self-learning loop
•Needs Python 3.6 or newer for the hook scripts
•The queue is per project at ~/.claude/projects/<encoded>/learnings-queue.json (reflect_utils.get_queue_path), although SKILL.md still says ~/.claude/learnings-queue.json; the global path is only a fallback (we read the code)
•Prompts of 500 characters or fewer that match patterns are written to disk in plain text; /reflect's semantic filter uses your Claude account through `claude -p`
•Install either the Python plugin or reflect-mod, not both, or every correction is captured twice (README)
•Compared with personal-assistant on this site, which keeps memory in CLAUDE.md plus a memory folder you edit, this one only learns from corrections and asks before writing

Frequently Asked Questions

Is the self-reflect skill safe?

It runs local Python hooks on every prompt and writes to your CLAUDE.md and AGENTS.md only after you approve each learning in /reflect. The semantic filter shells out to the claude CLI; we found no HTTP or socket code in the scripts. Review what it adds to global files such as ~/.claude/CLAUDE.md.

How do I install the self-reflect skill in Antigravity?

Clone BayramAnnakov/claude-reflect and copy SKILL.md into .agents/skills/claude-reflect/ (or ~/.gemini/config/skills/claude-reflect/). Only the guidance loads; automatic capture and /reflect are Claude Code features, so it will not learn from your corrections in Antigravity.

Does it work with Codex or Cursor?

Partly. The README says approved learnings are synced to AGENTS.md if it exists, which Codex, Cursor and other tools read. Capture and review still run in Claude Code.

Where are corrections stored before review?

In a learnings-queue.json file, per project under ~/.claude/projects/<encoded>/ according to the code (SKILL.md says ~/.claude/learnings-queue.json).

Plugin or mod?

Pick one. The mod checks every short prompt with a model and shows a Save band; the plugin queues regex matches for later /reflect and keeps --scan-history and /reflect-skills.