| name | setup |
| description | One-time setup of YOUR lens memory loop on Claude Code — your foundry where the SessionEnd hook queues lens sessions, /lens:retro mines them, and /lens:new grows your collection. Use when the user runs /lens:setup, or when a foundry-dependent skill (retro, new) finds no config. Claude Code only — the loop is not supported on Cowork. |
Lens Setup (Claude Code)
The memory loop — a SessionEnd hook that queues lens sessions, /lens:retro to mine
them, /lens:new to grow your collection — is a Claude Code feature. Setup
creates your foundry and wires it up. Without setup, all bundled lenses and
/lens:socratic still work; setup only adds the loop.
On Claude Cowork: not supported — stop here
If you detect Cowork, do NOT set up a foundry. The memory loop does not run on Cowork:
its sandbox spawns the CLI with --setting-sources user, so plugin-provided hooks (the
SessionEnd queue) never fire, and the VM home is ephemeral. Tell the user plainly: on
Cowork, just use the lenses and /lens:socratic directly — they work fully. Run
/lens:setup on Claude Code to enable the loop there. Then stop — no foundry, no
config, no folder grant.
On Claude Code: set up the loop
The foundry holds PERSONAL session data (session IDs, project/transcript paths, mined
observations) — never commit it to git. Use a private, persistent, non-tracked
folder.
-
Choose the foundry location — default ~/.claude/lens-foundry/; any non-git
folder is fine, but NEVER inside a git working tree. Create it with empty
pending-retros.jsonl and processed-retros.jsonl, an observations.md with a
one-line header ("Cross-project learnings mined by /lens:retro; append-only"), a
registry.md (your lenses — same columns as ${CLAUDE_PLUGIN_ROOT}/core/registry.md,
starting empty), and an empty lenses/ dir (where /lens:new writes your global
lenses; /lens:socratic reads them inline).
-
Write the config at ~/.claude/lens.json (show the user first):
{ "foundry": "<foundry path>" }
-
Hand the user the cross-cwd permission rule so retro/hook writes never prompt
from other projects' sessions. Do NOT edit ~/.claude/settings.json yourself —
permission-widening by an agent is blocked by the auto-mode classifier by design.
Print a paste-ready node -e one-liner the USER runs, merging into their settings
and preserving everything else:
permissions.additionalDirectories += "<foundry path>"
permissions.allow += [ "Edit(//<foundry path>/**)", "Write(//<foundry path>/**)" ]
Optional — without it the user just gets a one-time prompt on the first cross-project
foundry write.
-
Verify: run ${CLAUDE_PLUGIN_ROOT}/scripts/queue-retro.sh with no stdin — it
must exit 0 silently. Confirm the config parses (cat it back).
-
Tell the user: the SessionEnd hook now queues lens-using sessions; run /lens:retro
to process them, /lens:new to grow your collection (used via /lens:socratic — not
as separate slash commands).
