Set up and maintain multiple Claude Code projects with persistent STATE, prioritized BACKLOG, architectural DECISIONS, and MEMORY that survives sessions. 10 skills, one portfolio-wide audit, and a dream skill that consolidates project docs the way sleep consolidates memory — with every run snapshotted for rollback. A companion status bar ships as a separate repo.
Craft is not another CLAUDE.md helper. It is a working system for builders who juggle 3+ projects and want each session to start where the last one ended, not from scratch.
Craft is built for builders: solo developers, freelancers, indie hackers, and small agencies who run multiple projects in parallel and want Claude Code to pick up each one without re-learning it every session.
You'll get the most out of craft if you:
- Work across 3+ active projects (client work, side projects, personal tools) and keep losing context when you switch
- Use Claude Code as your primary environment, not as a bolt-on to another editor
- Care about your project memory across sessions, not just within one
- Want to experiment with Claude Code's capabilities and the wider ecosystem rather than lock into a fixed setup
Craft is probably not for you if you work in a single large codebase with an established team workflow where CLAUDE.md, Jira, and code review already cover the same ground. Craft adds structure where none exists; it does not replace team tooling.
The six ideas that shape every decision in this repo:
- Context is expensive. Project knowledge belongs in structured files, not in CLAUDE.md or session history. Load what you need, skip what you don't.
- State ≠ Tasks ≠ Decisions. Three time horizons, three files. Mixing them means Claude re-learns the same things every session.
- Archive, don't delete. Mistakes are cheap to reverse when nothing is gone. Everything moves to
archive/or.craft/dreams/, nothing is thrown away. - Sessions have a beginning, middle, and end. Each phase needs a different action — setup, solidify, handover. Craft skills map to these phases.
- Portfolio over project. Solo builders rarely have one project. The tooling has to scale from one codebase to a dozen without friction.
- Silent defaults beat configuration. Quality rules run in the background. You configure once, then forget about it.
/craft-project-setup generates a complete project structure:
your-project/
CLAUDE.md project instructions for Claude Code
.claude/
settings.json project-specific permissions and hooks
.craft/ all craft-owned files live here
PROJECT_STATE.md current state, in-progress work, known issues
BACKLOG.md prioritized task list (P0/P1/P2)
HANDOVER.md handoff notes between sessions
DECISIONS.md architectural decisions with rationale
DREAM_LOG.md dream history (created by /craft-project-dream)
QUALITY.md silent quality questions (always active)
memory/ committed memory for insights that should travel with the repo
MEMORY_INDEX.md index of memory entries
learned-rules.md numbered lessons read by the SessionStart hook
dreams/ auditable snapshots from /craft-project-dream
archive/ stale docs moved here by dream, never deleted
rules/
coding.md project-specific coding conventions
One directory, one owner. .claude/ holds what Claude Code natively expects. .craft/ holds everything craft creates. CLAUDE.md at the root stays because Claude Code reads it from there.
Claude Code ships its own auto-memory system at ~/.claude/projects/<project-key>/memory/ — persistent, typed, machine-local. That stays your personal, per-machine notebook.
.craft/memory/ is different by design:
- Committed — tracked by git, travels with the repo
- Team-shareable — when a colleague clones the project, the lessons come with it
- Project-bound, not machine-bound — your learned rules move with your laptop, or your co-founder's
- Consolidated by
/craft-project-dream— craft-memory is the input dream reshapes; the auto-memory is not
Use craft-memory for insights that belong to the project, not to you personally. For everything else, Claude Code's auto-memory is the better home.
Every Claude Code session gets the context it needs without burning tokens on exploration.
See examples/craft-demo-structure/ for a fully-filled-in reference project (a fictional Astro blog) — every file populated with realistic content, so you can see what the structure actually looks like after a few weeks of use.
Craft needs a few things to run. The installer handles dependencies automatically where possible — you rarely install anything manually.
| What | Why | Installer behavior |
|---|---|---|
| Claude Code | Runtime. Skills load here | Install Claude Code yourself first |
| bash 3.2+ | Everything in craft is shell. macOS ships 3.2, Linux has 4+ | Comes with your OS |
| jq | Session hooks and /craft-project-audit read settings.json with it |
Installed automatically: tries Homebrew first, then downloads a static binary to ~/.claude/bin/jq (no sudo, no PATH edits — craft scripts find it) |
| git | Most skills read git state (commits, branch, status) | Comes with macOS/Linux; craft works without it but audits show less |
Nothing else. No Node, no Python, no Docker, no Nerd Fonts. Windows: use WSL.
curl -fsSL https://raw.githubusercontent.com/derjochenmeyer/claude-code-craft/main/install.sh | bashAll 10 skills land in ~/.claude/skills/. Templates go to ~/.claude/craft-templates/. jq (if missing) goes to ~/.claude/bin/. No sudo, no root, idempotent. Works on macOS, Linux, and Windows (WSL). To update, re-run the same command.
Security note: This installer fetches files from GitHub over HTTPS. No checksum verification is performed. If you prefer to audit before running, clone the repo and use
bash install.sh --localinstead.
Dream is the feature that makes craft more than a scaffolding tool. Every session leaves residue: decisions half-logged, backlog items done but never marked, rules in CLAUDE.md that reference code you deleted three weeks ago, STATE that was appended to so many times it no longer reflects reality.
/craft-project-dream processes what accumulated, the way sleep consolidates memory.
Phase 1 -- Forget. Finds noise across your project docs. Stale backlog items that git log shows were resolved. Memory entries referencing deleted files. CLAUDE.md rules pointing to code that no longer exists. HANDOVER content already covered by STATE.
Phase 2 -- Consolidate. Strengthens what matters. Decisions buried in state notes get recorded in .craft/DECISIONS.md. Scattered memory entries about the same topic get merged into one. Recurring lessons get promoted to explicit CLAUDE.md rules.
Phase 3 -- Reset. Restores capacity. .craft/PROJECT_STATE.md gets rewritten to reflect current reality. .craft/BACKLOG.md gets cleaned. CLAUDE.md gets checked against the 200-line hard limit where instruction adherence degrades.
Every dream is auditable. Before any change is applied, the state of all touched files is snapshotted to .craft/dreams/<timestamp>/before/. After the run, the new state lands in after/, alongside a human-readable diff.md and a quantified report.md. If a dream makes things worse, rollback is one cp away.
Dream complete — .craft/dreams/2026-04-18-14-23/
Forgotten: 8 items removed (34 lines of noise)
Consolidated: 2 decisions · 1 merge · 1 promotion
Reset: STATE 67→28 lines · BACKLOG 5 archived · CLAUDE.md 148 lines
Next session starts with ~39% less noise in project docs.
Rollback: cp .craft/dreams/2026-04-18-14-23/before/* .
Automatic suggestions, never silent changes. When Claude Code starts a session and detects that a dream would likely help (10+ commits since last dream, STATE.md grown past 100 lines, memory index bloated), it surfaces a one-line banner: "12 commits since last dream. Run /craft-project-dream? (y/N/skip-for-now)". You choose. Nothing runs in the background.
Read .craft/dreams/*/report.md after a few runs to see whether dream is earning its keep on your project. If it is not, kill it.
/craft-project-setupSet up a new project or enhance an existing one with full Claude Code infrastructure (CLAUDE.md, settings.json, memory, .craft/ docs). Never overwrites existing files./craft-project-statusDaily status report: reads.craft/PROJECT_STATE.md,.craft/BACKLOG.md, and recent git history. No agents, no network, instant./craft-project-auditFast local health check: git pulse, file freshness, setup quality. No agents, no external fetches, done in ~15 seconds./craft-project-audit-fullDeep audit via 4 parallel agents: feature adoption, session usage patterns, config quality, craft-pattern compliance. Takes 2-20 minutes. Note: reads recent session files to analyze usage patterns. Session content stays in the local context window and is never sent externally, but may contain sensitive conversation data./craft-project-dreamForget the noise, reinforce memories, wake up sharper. Every run is snapshotted to.craft/dreams/<timestamp>/so you can audit and roll back. See the Dream section above./craft-project-rememberSave facts, decisions, lessons, and context to project memory. Structured files that dream can consolidate./craft-project-exploreDetect your stack, query the MCP registry, and get a relevance-sorted table of integrations you are not using yet./craft-session-solidifySave a mid-session checkpoint: updates.craft/PROJECT_STATE.md,.craft/BACKLOG.md,.craft/DECISIONS.md, optionally.craft/HANDOVER.md, and commits. Run when context hits ~75% or at a clean break — keep working after.
/craft-global-auditTwo sections: Claude Code installation health (version, global config, installed skills) and a scored portfolio table across all projects./craft-update-selfCheck for updates to all installed craft skills. Shows what is new, applies updates on request.
A matching status bar lives in its own repo: claude-code-craft-statusline. No Nerd Fonts, just bash and jq. Shows model, effort, context, rate limits, session cost, and git branch.
curl -fsSL https://raw.githubusercontent.com/derjochenmeyer/claude-code-craft-statusline/main/install.sh | bashIt is an independent repo so you can install it with or without craft. Home-dir filename and slash command (/craft-statusline) did not change — upgrading from craft v1 just points the install at the new source.
Claude Code works best when it is not alone. Here is the stack we run daily, each tool solving a different slice of the same underlying problem: context is expensive, attention is finite.
- Wispr Flow (macOS) — voice-to-text for prompts. Dictating a handover or a long instruction is almost always faster than typing it, and the tone of voice makes briefs more natural.
- cmux — terminal multiplexer for parallel Claude sessions. Dev server, agent, main coding session, and a monitor in one window. We learned about it from zerotopete.com.
- rtk — CLI proxy that compresses shell output before Claude sees it. 60-90% fewer tokens on
git diff,pytest,cargo test,ls. Pairs perfectly with craft: rtk handles in-session shell noise, craft handles cross-session project memory. - craft — this repo. Structured project memory, portfolio audit, dream consolidation.
One directory for everything: ~/code. The global audit scans it automatically, and you never have to explain to Claude where projects live. Split work by concern, not by client:
~/code/
acme/
project-management/ email, calendar, Notion, file ops
marketing-strategy/ brand docs, planning, content
next-app/ the actual web app
shopify-theme/ storefront theme
Each directory is its own Claude Code session with its own context, memory, and permissions.
/craft-project-audit-full is inspired by Pete Steinberger's catch-up skill published at zerotopete.com. The parallel-agent architecture and anti-hallucination rules are adapted from his approach. Two of the tools in "What we use" above — Wispr Flow and cmux — we picked up from his writing as well. If you are building on Claude Code, his newsletter is worth subscribing to.
Contributions are welcome and encouraged.
This repo is meant to be a community resource. If you have useful skills, clever hooks, better MCP configurations, improved CLAUDE.md patterns, or real-world use cases, please contribute. See CONTRIBUTING.md for guidelines.
Short version: open an issue before writing code. Issues define intent; pull requests deliver it.
MIT. See LICENSE.
Built by okay.cool