stack-setup
Install, verify, bundle or remove the self-improving stack (review-learn pattern ledger + skill-index roster + dreamd scheduled memory) on any machine, for any repo, on macOS or Linux. Use for "set up the learning stack", "install dreamd on this machine", "package the stack", "portable zip of my skills", "onboard a new repo to review-learn", "uninstall the stack", "why is the SessionStart block empty".
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 3
01 前言 Front Matter
- name
- stack-setup
- description
- Install, verify, bundle or remove the self-improving stack (review-learn pattern ledger + skill-index roster + dreamd scheduled memory) on any machine, for any repo, on macOS or Linux. Use for "set up the learning stack", "install dreamd on this machine", "package the stack", "portable zip of my skills", "onboard a new repo to review-learn", "uninstall the stack", "why is the SessionStart block empty".
02 资源文件 7
- 参考文档references/INTEGRATION-GUIDE.md18.8 KB
- 参考文档references/SETUP.md18.1 KB
- 脚本scripts/install.py24.1 KB
- 脚本scripts/templates/launchd.plist.tmpl705 B
- 脚本scripts/templates/systemd.service.tmpl214 B
- 脚本scripts/templates/systemd.timer.tmpl174 B
- 脚本tests/test_install.py5.7 KB
03 SKILL.md 正文
stack-setup
Three skills work as one system and none of them is useful alone:
| Skill | What it does | Fires from |
|---|---|---|
review-learn |
PR review threads, claude-mem observations and user corrections → per-repo pattern ledger → guardrails injected at SessionStart | Stop hook, debounced 10 min |
skill-index |
the skill roster injected at SessionStart, plus skill-learn candidates discovered from repeating workflows | Stop hook (after review-learn) |
dreamd |
episodes → a rewritten memory.md, nightly typed lessons, weekly pruning, all injected within a 2.5k-token cap |
its own 15-minute scheduler |
Everything derived lives under $CLAUDE_CONFIG_DIR/projects/<repo-folder>/, git-versioned and private. Nothing is ever written inside a repo.
One command does each step. S=~/.claude/skills/stack-setup/scripts/install.py.
For the full runbook — what each file does, every failure mode, day-two operation — read references/SETUP.md.
For a fresh machine, a shared skills repo, and the quirks that cost days, read references/INTEGRATION-GUIDE.md.
| Step | Command |
|---|---|
| check the machine | python3 $S doctor |
| package for another machine | python3 $S bundle --out ~/claude-learning-stack.zip |
| install from that zip | unzip <zip> -d stack && python3 stack/skills/stack-setup/scripts/install.py apply --from stack |
| wire hooks, claude-mem, scheduler | python3 $S wire |
| register the scheduler | python3 $S schedule --load |
| seed one repo | python3 $S seed --repo /path/to/repo [--since 2026-06-01] [--pr 1874 --pr 1882] |
| check everything | python3 $S verify [--phase wire|seed|tests] [--repo /path/to/repo] |
| remove it | python3 $S uninstall [--remove-skills] |
Every command prints what it changed and is safe to re-run. wire backs up each file it edits to <name>.bak and adds nothing that is already present. apply moves an existing install aside rather than deleting it.
Phase 1 — prerequisites
doctor exits non-zero if a hard requirement is missing.
| Requirement | Hard | Why |
|---|---|---|
claude CLI on PATH |
yes | every model call is claude -p --settings '{"disableAllHooks":true}' |
git |
yes | the ledgers are git repos |
| python ≥ 3.9 | yes | the syntax floor of the skills; the installer uses the same interpreter for the scheduler unit |
| claude-mem database | yes | the only source of observations, sessions and tool use |
| claude-mem worker script | no | needed to apply a settings change without a manual restart |
gh authenticated |
no | PR review threads; review-learn still works from claude-mem alone |
| claude-reflect plugin | no | user-correction events, the largest term in dreamd's priority score |
node or bun |
no | runs the worker restart |
It also prints the resolved CLAUDE_CONFIG_DIR, the interpreter it will bake into the scheduler unit, and which scheduler it found.
The skills root is not configurable. They must sit at ~/.claude/skills/<name>, because they import each other through that exact path (dcommon.py, skill_learn.py, propose.py, stop_hook.py). CLAUDE_CONFIG_DIR may be anywhere; only the skills location is fixed.
Phase 2 — install and wire
bundle writes one zip holding the three skills, this installer, and the claude-mem mode file code--review-learning.json, which defines the review-finding and review-resolution observation types that review-learn keys on. Caches, .pyc and lock files are excluded. apply unpacks it to the skills root and symlinks each skill into ~/.codex/skills so Codex sessions see the same thing.
wire touches exactly four places:
$CLAUDE_CONFIG_DIR/settings.json— three SessionStart entries with matcherstartup|resume|clear|compact, plus the review-learn Stop hook.~/.codex/hooks.json— the same three SessionStart commands, plus the Codex prompt hook and Stop hook. Skipped when~/.codexis absent.~/.claude-mem/settings.json—CLAUDE_MEM_CONTEXT_OBSERVATIONS=25andCLAUDE_MEM_MODE=code--review-learning, then a worker restart. The 50→25 cut is the budget trade that pays for dreamd's injected block, so resident context stays flat.- The scheduler unit: a launchd plist on macOS, a systemd user service and timer on Linux, or a printed crontab line.
Two host facts that cost a day to learn, so do not undo them:
- A scheduler must not open a file inside a repo. On macOS, opening a path under
~/Documentsfrom a launchd job blocks uninterruptibly on the Files-and-Folders prompt, andsubprocesstimeouts do not fire. dreamd resolves repo roots with stat only and never spawns git. The systemd template deliberately omitsProtectHomeand sandboxing for the same reason. CLAUDE_CONFIG_DIRmust reach the scheduler, not just your shell. It is written into the unit's environment. A value exported in a shell profile alone will not be visible to the job, and the ledgers will silently land in~/.claudeinstead.
Verify: python3 $S verify --phase wire asserts each entry appears exactly once, the mode file exists, the observation budget reads 25, and the job is loaded.
Phase 3 — seed a repo
seed runs, from inside the repo: review-learn ingest → maintain → propose, then one forced dreamd tick that builds episodes, writes the first memory, runs one nightly and one weekly. Budget a few minutes and roughly four model calls. Pass --pr a few times on the first run so the first patterns rest on real review threads rather than observations alone.
No per-repo registration step exists or is needed: the SessionStart hook registers the repo on every session, and the tick also discovers repos from claude-mem tool use. A linked git worktree registers from its own sessions.
Read memory.md and lessons.md by hand before trusting the injection. A repo with little claude-mem history produces a thin memory and few lessons; that is correct, not broken. dreamd's first reflect starts from the newest observations that fit its input cap and never replays older history into memory.
Verify: python3 $S verify --phase seed --repo <path> checks both ledgers exist with commits, the run ledger has an episodes row and a reflect row, the watermark is set, and the block a session will receive is within the token cap.
Phase 4 — end to end
python3 $S verify runs the wire checks, all three test suites, and the seed checks when --repo is given. Then confirm by hand, because no script can:
- Start a real session in the repo. The dreamd block, the review-learn guardrails and the skill roster should all appear, and the claude-mem timeline should show 25 entries rather than 50.
- Mute and unmute dreamd, confirming the block disappears and returns.
- Wait one scheduler interval and check
$CLAUDE_CONFIG_DIR/dreamd/tick.loggained a line. On macOS:launchctl print gui/$(id -u)/com.<user>.dreamd | grep -E 'state|last exit'. On Linux:systemctl --user list-timers dreamd-tick.timer.
What to watch
dropped_by_provenanceper reflect indream/runs.jsonlshould stay near zero. A rise means the prompt is inventing evidence ids.- The repeat-rate column in
review-patterns/index.mdis the point of the whole exercise: it should fall over months. - A nightly that reports
10/24 episodesis normal. Only what fits the prompt is consolidated; the rest stay pending for the next run.
Known ceilings
- The evidence gate checks that a cited id exists, not that it supports the sentence. It catches invented ids, not misattributed ones.
- Contrastive failure pairing needs file lists, and claude-mem populates them on a small fraction of observations, so that mechanic is mostly inert today. dreamd supplements from tool use where it can.
- A lesson's
last_seenis set at creation and refreshed only by a merge, so the 90-day decay means 90 days since creation. - The first reflect on a cold ledger skips history older than its input cap, permanently.
Uninstall
uninstall removes the hook entries it owns and leaves foreign entries in the same file alone, unloads and deletes the scheduler unit, and restores the claude-mem observation budget. Ledgers under $CLAUDE_CONFIG_DIR/projects/ are never deleted; they are your data. Add --remove-skills to drop the three skill directories too.
Testing
python3 -m unittest discover ~/.claude/skills/stack-setup/tests # hook merge, unit rendering, path derivation, bundle filters
python3 ~/.claude/skills/stack-setup/scripts/install.py verify # the live machine, including the three skills' own suites
04 同仓库更多 Skills
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.
alpha
Human-started command: it runs only when the human's message begins with `/ak:alpha`. On any other request do not load or follow it; tell the human to type that command. Runs the alpha workflow when a human asks for it.