Production Claude

Production Claude — Cross-Session Memory for Claude Code

When to Apply

Apply this skill when the user wants Claude Code to carry context across conversations — long refactors, multi-day work, or any project where a fresh chat should resume without re-exploring. It scaffolds a small, self-contained session-log ring buffer that a SessionEnd hook feeds automatically, plus a handful of slash commands for driving it by hand.

It is Claude Code specific: it relies on Claude Code hooks and .claude/commands/, which other agents don't have. Skip it for a pure coding-convention request (that's production-python / production-react).

> Note on installation. npx skills add only drops this folder into place — > it does not register the hook, create the commands, or scaffold the ring > buffer. Those are an explicit one-time bootstrap: run scripts/install.sh, or > perform the [recipe](#manual-recipe-agent-driven) below with your own tools.

---

What the setup is — four parts

| Part | Where | Role | |---|---|---| | Ring buffer | local/sessions/ — index.md + session-1.md … session-N.md | The rolling store. index.md holds a current: N pointer. | | Driver script | local/sessions/update-session.sh | On session end: rotate if the current file is full, then append a summary block. | | SessionEnd hook | .claude/settings.json (or settings.local.json) | Fires the driver script, backgrounded, once per session. | | Slash commands | .claude/commands/{us,nc,ul,wn}.md | Manual counterparts — append a detailed block, produce a handoff, etc. |

local/ is intended to be gitignored — session logs are personal working memory, not shipped product.

---

Quick install (script)

# from anywhere inside the target repo:
bash /scripts/install.sh          # infers the repo root
# or point it explicitly:
bash /scripts/install.sh /path/to/repo

The installer is idempotent — it seeds local/sessions/, copies the portable update-session.sh, installs the four commands (skipping any that already exist), and merges the SessionEnd hook into .claude/settings.json without duplicating it. It requires python3 for the JSON merge. Afterwards, add local/ to .gitignore if it isn't already.

---

Manual recipe (agent-driven)

If a user asks you to "set this up" and you'd rather not run the script, do this directly — it's what the installer automates:

1. Scaffold the ring buffer. Create local/sessions/. Write index.md

containing exactly current: 1 (see assets/index.seed.md), and an empty session-1.md with a # Session Log — 1 heading.

1. Install the driver. Copy scripts/update-session.sh to

local/sessions/update-session.sh and chmod +x it. Do not edit the paths — the script resolves the project root from $CLAUDE_PROJECT_DIR / git rev-parse, so it is already portable.

1. Register the hook. Merge the snippet in assets/settings.hook.json into

the project's .claude/settings.json under hooks.SessionEnd. The command uses ${CLAUDE_PROJECT_DIR} so it stays project-relative. If the user prefers a personal (untracked) hook, put it in .claude/settings.local.json instead.

1. Install the commands. Copy assets/commands/*.md into

.claude/commands/. /us and /nc are the core pair; /ul and /wn are optional companions (/ul commits, so review it before adopting).

1. Gitignore. Ensure local/ is in .gitignore.
2. Verify. bash -n local/sessions/update-session.sh (syntax), then end a

session that changed a file and confirm a block was appended.

---

The slash commands

| Command | What it does | |---|---| | /us | Append a detailed block to the active session file — enough for a cold-start resume (branch/tree state, what was done, decisions, files touched, what NOT to re-explore, next-action checklist). The high-fidelity manual counterpart to the automatic hook. | | /nc | Emit a self-contained handoff to paste into a brand-new conversation. | | /ul (optional) | Update an implementation log and commit to the current branch (never a protected branch; never pushes). Only meaningful if the project keeps such a log. | | /wn (optional) | "Now suggest what next." — a quick planning nudge. |

The hook writes a short, automatic block on every meaningful session end; /us is what you run when you want a thorough, deliberate checkpoint.

---

Tunables

The driver reads these from the environment (defaults in parentheses):

| Variable | Default | Meaning | |---|---|---| | CLAUDE_SESSIONS_DIR | /local/sessions | Where the ring buffer lives. | | CLAUDE_SESSION_THRESHOLD | 102400 (100 KB) | Rotate to the next file past this size (~25K tokens; fits one Read). | | CLAUDE_SESSION_MAX | 20 | Ring size. Total history ≈ MAX × THRESHOLD (~2 MB). |

---

Portability & safety notes

• No hardcoded paths. Project root comes from $CLAUDE_PROJECT_DIR, else

git rev-parse --show-toplevel, else $PWD.

• macOS + Linux. stat and sed -i differ across BSD/GNU; the script

detects and adapts. python3 is used only by the installer's JSON merge.

• Re-entrancy lock. The driver calls claude --print, which would re-fire

SessionEnd; a per-project lockfile in $TMPDIR prevents the loop.

• No-op guard. The driver skips appending when nothing changed or was

committed recently — trivial/read-only sessions leave no noise.

• Never writes to git. The hook only touches the (gitignored) session log.

Design rationale — rotation math, the lock, the no-op guard, and how to extend this into a full docs/issue tracker — is in [references/REFERENCE.md](references/REFERENCE.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nkartik94
• Source: nkartik94/agentic-skills
• License: MIT

Install and usage instructions live in the source repository linked above.