reflect plugin · multi-tool platform
reflect · Platform Architecture
session timeline · storage layers · adapter interfaces · install paths
Section 01
Session timeline · one coding session, end to end
HOOK FIRES
DATA READ / WRITTEN
Install
adapter / plugin
writes hooks
to config file
Session starts
harness boots
SessionStart fires
recall + drain (bg)
reads graphrag/
injects top-3
additionalContext
User prompts
conversation
—
model context
+ learnings
Tool uses
edits / runs
—
transcript grows;
~/.claude/ JSONL
Context fills
approaching limit
—
harness detects
token threshold
PreCompact
hook fires
PreCompact fires
precompact_reflect.py
appends to
pending_reflections
.jsonl (queue)
Compaction
harness compresses
—
transcript archived;
context window reset
Session ends
process exits
—
queue entry waits;
drained next start
time
SessionStart hook fires
PreCompact hook fires
Context / queue state change
Harness internal event (no hook)
Normal conversation step
Section 02
Storage layers · three tiers, one knowledge base
QUEUE
DOCS
INDEX
Pending queue
~/.reflect/pending_reflections.jsonl
one line per queued transcript · {transcript_path, session_id, trigger, harness, queued_at}
IN: precompact_reflect.py (appends on PreCompact)
OUT: reflect-drain-bg.sh reads + dequeues
append-only
~1 line / compaction
harness-agnostic
any harness writes or drains
Learnings store
~/.learnings/documents/ <slug>.md + <slug>.entities.yaml
markdown document + YAML entity sidecar per learning · grep-able on disk
IN: claude -p /reflect (headless · spawned by drain)
reflect reindex
markdown + YAML
one .md per learning
entity sidecar for graph
human-readable · git-able
GraphRAG + vector index
~/.learnings/graphrag/ communities · entities · relations · hnswlib vectors
nano-graphrag · vector + entity graph · hybrid search · queried on SessionStart
IN: reflect reindex (after each successful drain)
OUT: session_start_recall.py queries top-3
vector + entity graph
queried at SessionStart
rebuilt by reflect reindex
dense + graph hybrid
Append-only queue
Persistent knowledge storage
Write flow (capture)
Read flow (recall)
reindex pipeline
Section 03
The platform · adapter interface and shared knowledge base
HARNESS ADAPTERS
Claude Code
.claude-plugin/plugin.json → ~/.claude/settings.json
/plugin install reflect@agents-in-a-box
plugin runtime
Codex CLI
adapters/codex/codex_adapter.py → ~/.codex/hooks.json
python codex_adapter.py install
adapter direct
Copilot CLI
adapters/copilot/copilot_adapter.py → TBD
python copilot_adapter.py install (planned)
planned
REFLECT CORE
reflect
Hook Scripts
session_start_recall.py · precompact_reflect.py
reflect-drain-bg.sh
CLI
reflect · recall · reindex · search
python -m reflect_kb
Headless Worker
claude -p /reflect <transcript>
--output-format json · --max-turns 25
SHARED KNOWLEDGE BASE
~/.reflect/ + ~/.learnings/
shared by ALL harnesses — same directory
pending queue
~/.reflect/pending_reflections.jsonl
learnings store
~/.learnings/documents/
GraphRAG + vector index
~/.learnings/graphrag/
wires hooks
into harness
config file
enqueue
write .md
reindex
recall · top-3 learnings injected into session context
ALL adapters point here — harness-agnostic
Harness adapter (live)
Harness adapter (planned)
Hook scripts
CLI / storage
Wires / trigger
Write (capture)
Read (recall)
Planned path
Section 04
Install paths · Claude Code vs Codex CLI
INSTALL PATH
LEGEND
Claude Code
1. Marketplace add
/plugin marketplace add
stevengonsalvez/agents-in-a-box
2. Plugin install
/plugin install
reflect@agents-in-a-box
3. Plugin runtime (automated)
extracts plugin.json · expands
CLAUDE_PLUGIN_ROOT → ~/.claude/settings.json
user effort: 2 commands · runtime handles the rest
writes:
~/.claude/settings.json (hooks block merged)
+ skills/ extracted to ~/.claude/plugins/reflect/
Codex CLI
1. Clone repo
or use existing
agents-in-a-box checkout
2. Run adapter directly
python plugins/reflect/
adapters/codex/codex_adapter.py install
3. Adapter copies skills
plugins/ → ~/.codex/skills/
merges ~/.codex/hooks.json
4. Done
hooks.json
active
user effort: 1 python command · no plugin runtime required
writes:
~/.codex/hooks.json (SessionStart + PreCompact entries merged)
+ skills/ copied to ~/.codex/skills/reflect/
Step type
User command (Claude Code)
User action (Codex)
Automated (no user input)
Config written / result
Config files produced
Claude: ~/.claude/settings.json
(hooks block · plugin runtime writes)
Codex: ~/.codex/hooks.json
(hooks block · adapter writes directly)
Both point at the SAME hook scripts
and the SAME shared knowledge base.
Relative user-facing complexity
Claude Code
2 slash commands
Codex CLI
1 python command (more explicit path)
Claude Code user step
Codex CLI user step
Automated / runtime-handled
Config file written / result state
Section 05 · update
Updated recall · UserPromptSubmit primary, SessionStart baseline, per-session dedupe
SESSION TIMELINE
t →
SessionStart
baseline recall
cwd · branch
UserPromptSubmit ①
"fix OAuth bug"
UserPromptSubmit ②
"add refresh token"
UserPromptSubmit ③
"now the rate-limiter"
session_start_recall
query: cwd + branch
inject top-3 baseline
→ L₁ L₂ L₃
user_prompt_recall
query: prompt text
dedupe vs {L₁,L₂,L₃}
→ L₄ (L₁ skipped)
user_prompt_recall
query: prompt text
dedupe vs {L₁..L₄}
→ L₅ (L₂,L₄ skipped)
user_prompt_recall
query: prompt text
topic pivot → new hits
→ L₆ L₇ L₈
DEDUPE STATE
~/.reflect/session-injected/<session_id>.json
{L₁, L₂, L₃}
{L₁, L₂, L₃, L₄}
{L₁..L₄, L₅}
{L₁..L₅, L₆, L₇, L₈}
Why two layers?
SessionStart fires
BEFORE user types
→ query is coarse
UserPromptSubmit has
actual intent
→ sharp query
Dedupe stops the
same learning being
re-injected per prompt
SessionStart recall (baseline · cwd+branch query)
UserPromptSubmit recall (intent-sharp · prompt query)
Per-session dedupe state (filesystem JSON)
Hook writes to dedupe state
Section 06 · new
Extra capture hooks · PostToolUse mini-learning + Stop reflection enqueue
POSTTOOLUSE · MINI-LEARNING
Tool call fails
Bash exit≠0 · Edit error
PostToolUse hook fires
posttooluse_minilearning.py
arms next-prompt watcher
writes ~/.reflect/armed.json
User: "try X instead"
UserPromptSubmit fires
arming detected
~/.learnings/documents/
<slug>.md · conf=low
low-cost · no /reflect run
STOP · REFLECTION ENQUEUE (short sessions)
Agent finishes
Stop hook fires
(context never filled)
stop_reflect.py
enqueue if not already
dedupe by session_id
~/.reflect/pending_reflections
.jsonl (shared queue)
drained next SessionStart
claude -p /reflect (headless)
writes learnings + reindex
same drain path
★ Mini-learning is cheap (no LLM run); Stop-enqueue is full /reflect (same as PreCompact). Both write to the SAME learnings store.
Lifecycle event (harness fires)
Hook script
Shared queue
Storage write
Capture (write to disk)
Section 07 · new
Status line · making recall + capture activity visible
CLAUDE CODE · CUSTOM SHELL STATUS LINE
Any reflect hook fires
recall · enqueue · drain
writes ~/.reflect/last-event.json
~/.reflect/last-event.json
{event, ts, detail}
small atomic file
~/.claude/statusline.sh
reads last-event.json
renders reflect fragment
claude · main
🧠 recalled 3 · queued 1
8% ctx · 2h limit
CODEX CLI · HOOK statusMessage FIELD (PER-CALL ONLY)
Any reflect hook fires
recall · enqueue · drain
hook entry has statusMessage
codex reads
hooks.json entry
"statusMessage":"🧠 recalling…"
codex TUI · ephemeral
shows DURING hook only
no persistent fragment yet
codex · gpt-5.5
🧠 recalling…
main · ./repo · 4%
★ Claude has a custom shell statusline — we get persistent counters (recalled N · queued M). Codex's status line is a fixed token list;
we use the per-hook statusMessage field — shows ephemerally during hook execution only. Full parity blocked on a codex custom-token API.
Hook (writes event)
Intermediate state file / config
Harness UI consumer
Status line output
Section 08 · worked example
End to end · "fix the OAuth bug" through both flows
SCENARIO · CLAUDE CODE SESSION, MORNING
09:14 · SESSIONSTART
Session starts in ./auth-service
recall(cwd=auth) → L₁ "OAuth state"
09:14 · USERPROMPTSUBMIT
"fix the OAuth redirect bug"
recall(prompt) → L₂ L₃ (L₁ skipped)
09:18 · POSTTOOLUSE
Bash exit=1 (curl 500)
posttooluse arms watcher
09:18 · USERPROMPTSUBMIT
"use --insecure for local dev"
mini-learning written ✓
10:42 · PRECOMPACT
Context 90% full
enqueued transcript ✓
11:05 · STOP
Agent finishes · session ends
stop_reflect skips (dedupe)
14:30 · CODEX · SESSIONSTART
Open codex on same repo
drain-bg picks up morning queue
14:30 · BG DRAIN
claude -p /reflect (headless)
writes L₄ "OAuth state mismatch"
14:31 · CODEX USERPROMPTSUBMIT
"add OAuth refresh tokens"
recall returns L₂, L₃, L₄ ✓
OUTCOME
Codex session benefits from this morning's Claude work
L₄ "OAuth state mismatch (Claude AM)" is now in the index. Cross-tool.
STATUS LINE · CODEX TUI
codex · gpt-5.5
🧠 3 recalled · ↗ queue empty
SessionStart · Stop · drain hooks
UserPromptSubmit recall
PostToolUse / harness event
PreCompact · queue
Cross-tool outcome