Checkpoint claudio

checkpoint-claudio

Persistent memory system for Claude Code projects. Maintains a structured modification log and a codebase summary across sessions. Optionally uses graphify to explore the codebase faster.

---

COMMAND: /checkpoint-claudio install

Triggered by: /checkpoint-claudio install

Installs everything needed for checkpoint-claudio to work automatically:

1. Registers the skill in ~/.claude/CLAUDE.md
2. Installs the hook script in ~/.claude/hooks/
3. Adds the UserPromptSubmit hook to ~/.claude/settings.json

Run this once after copying the skill folder to ~/.claude/skills/checkpoint-claudio/.

Steps

Step 1 — Check if already registered

grep -q "checkpoint-claudio" ~/.claude/CLAUDE.md && echo "ALREADY_REGISTERED" || echo "NOT_FOUND"

If ALREADY_REGISTERED: tell the user and stop. Do not proceed.

Step 2 — Append to global CLAUDE.md

cat >> ~/.claude/CLAUDE.md << 'CLAUDEEOF'

# checkpoint-claudio
- **checkpoint-claudio** (`~/.claude/skills/checkpoint-claudio/SKILL.md`)
At the start of every project session, invoke the `checkpoint-claudio` skill
before doing anything else.
When the user types `/historia`, invoke the Skill tool with `skill: "checkpoint-claudio"`.
When the user types `/retroso`, invoke the Skill tool with `skill: "checkpoint-claudio"`.
CLAUDEEOF

Step 3 — Install the hook script

mkdir -p ~/.claude/hooks
cp ~/.claude/skills/checkpoint-claudio/hooks/checkpoint-reminder.sh \
   ~/.claude/hooks/checkpoint-reminder.sh
chmod +x ~/.claude/hooks/checkpoint-reminder.sh

Step 4 — Add UserPromptSubmit hook to settings.json

Read ~/.claude/settings.json. Check if UserPromptSubmit already contains checkpoint-reminder.sh:

grep -q "checkpoint-reminder" ~/.claude/settings.json && echo "HOOK_EXISTS" || echo "HOOK_MISSING"

If HOOK_EXISTS: skip this step.

If HOOK_MISSING: use Python to inject the hook safely without breaking the existing JSON:

python3 - << 'PYEOF'
import json, sys
from pathlib import Path

settings_path = Path.home() / '.claude' / 'settings.json'
settings = json.loads(settings_path.read_text()) if settings_path.exists() else {}

hooks = settings.setdefault('hooks', {})
submit = hooks.setdefault('UserPromptSubmit', [])

new_hook = {
    "hooks": [
        {
            "type": "command",
            "command": str(Path.home() / '.claude' / 'hooks' / 'checkpoint-reminder.sh'),
            "timeout": 5
        }
    ]
}

# Avoid duplicates
already = any(
    any(h.get('command', '').endswith('checkpoint-reminder.sh')
        for h in entry.get('hooks', []))
    for entry in submit
)

if not already:
    submit.append(new_hook)
    settings_path.write_text(json.dumps(settings, indent=2))
    print('Hook added to settings.json')
else:
    print('Hook already present in settings.json')
PYEOF

Step 5 — Confirm

Tell the user:

"checkpoint-claudio installed:

• CLAUDE.md: registered
• hooks/checkpoint-reminder.sh: installed
• settings.json: UserPromptSubmit hook added

Restart Claude Code to activate the hook. Commands available: /historia, /retroso."

---

PHASE 1 — Session startup (always run this first)

1.1 Check folder existence

Step 0 — Check if there is anything to work with

Before doing anything else, check whether the current directory contains actual project files:

find . -maxdepth 2 \
  -not -path '*/.git/*' \
  -not -path '*/checkpoint_claudio/*' \
  -not -name '.DS_Store' \
  -not -name '*.swp' \
  -type f | head -5

• If the output is empty (no files found): the directory is empty or not yet a project. Create checkpoint_claudio/ and checkpoint1.md silently, then stop. Do NOT create starting.md yet and do NOT ask about graphify. On the user's first interaction (first message or first file created), run the full Bootstrap (section 1.2) at that point.

• If the output contains project files (code, config, docs, scripts): proceed normally below.

Check whether checkpoint_claudio/ exists in the current project root.

If it does NOT exist → go to section 1.2 (Bootstrap) If it exists → go to section 1.3 (Resume)

---

1.2 Bootstrap (first session on this project)

Step 1 — Ask about graphify

Before reading anything, ask the user exactly this:

"No checkpoint found for this project. I'll build starting.md by exploring the codebase. Do you want me to use graphify for a faster and deeper analysis? (recommended for large codebases)

• Yes → I'll build or reuse the knowledge graph, then query it
• No → I'll read the codebase directly"

Wait for the answer, then follow the appropriate path below.

---

1.2-A Bootstrap WITH graphify

Step A1 — Check for existing graph

ls graphify-out/graph.json 2>/dev/null && echo "EXISTS" || echo "MISSING"

• If EXISTS: skip to Step A3 (graph already built, free to query)
• If MISSING: run Step A2 first

Step A2 — Build the graph

Run graphify on the current directory:

/graphify .

Wait for the pipeline to complete. Do not proceed until graphify-out/graph.json exists and graphify-out/GRAPH_REPORT.md is written.

Step A3 — Populate starting.md from the graph

Run these queries in sequence and use the answers to fill starting.md:

graphify query "What is the main purpose of this project?"
graphify query "What languages, frameworks and libraries does this project use?"
graphify query "What is the entry point and main execution flow?"
graphify query "What are the key configuration and dependency files?"
graphify query "What are the most important architectural decisions, patterns, or quirks?"

Also read the God Nodes and Surprising Connections sections from graphify-out/GRAPH_REPORT.md — paste relevant content into the Notes section of starting.md.

For the folder structure section, use:

find . -maxdepth 2 -not -path '*/.*' -not -path '*/graphify-out/*' | sort

Write checkpoint_claudio/starting.md (see template in section 1.2-C). No section should be left as [TBD] after graphify — if a query returned nothing useful, note that explicitly rather than leaving a placeholder.

---

1.2-B Bootstrap WITHOUT graphify

Step B1 — Explore the codebase manually

Read in order:

• Directory structure (top 2 levels)
• Main entry point(s)
• Key config files (pyproject.toml, package.json, requirements.txt, .env.example, Dockerfile, Makefile, etc.)
• Core source files — read enough to understand the architecture, not everything

Step B2 — Write starting.md

Use the template in section 1.2-C. Mark any section you cannot determine with [TBD: <what is missing>] — never leave a section blank or write a generic placeholder.

---

1.2-C starting.md template

# Project: <project name>
Updated: <YYYY-MM-DD>
Built with: <graphify | manual exploration>

## Description
<2-3 sentences on what the project does>

## Tech stack
<languages, frameworks, key libraries>

## Folder structure
<concise directory tree of main folders>

## Entry point and main flow
<where execution starts, high-level flow>

## Key dependencies / config files
<requirements.txt, pyproject.toml, .env, etc.>

## Notes
<architecture decisions, quirks, god nodes, surprising connections, things
worth remembering for future sessions>

---

1.2-D Final bootstrap steps

1. Create checkpoint_claudio/ if not yet created:

   mkdir checkpoint_claudio
   

2. Write checkpoint_claudio/starting.md with the content from the path above
3. Create checkpoint_claudio/checkpoint1.md:

   # Checkpoint 1
   
   

4. Report to the user in one line: project detected, starting.md created, ready.

---

1.3 Resume (checkpoint_claudio/ already exists)

Step 1 — Read starting.md

Read checkpoint_claudio/starting.md in full. Always the first read.

Step 2 — Completeness check

Evaluate each section against this table:

Section	Incomplete if...
Description	empty, [TBD...], or too vague to understand the project
Tech stack	empty or [TBD...]
Folder structure	empty or [TBD...]
Entry point	empty or [TBD...]
Key dependencies	empty or [TBD...]

If no section is incomplete: skip to Step 4.

If one or more sections are incomplete: go to Step 3.

Step 3 — Fill incomplete sections

Ask the user exactly this:

"starting.md has incomplete sections: [list them]. Do you want me to use graphify to fill them in?

• Yes → I'll query the knowledge graph (fast, if graph.json exists) or build it first
• No → I'll read the relevant codebase files directly"

Wait for the answer, then:

If YES (graphify):

Check for graphify-out/graph.json:

• If it exists: run targeted queries for the incomplete sections only (see query list in section 1.2-A, Step A3)
• If it does not exist: ask whether to build it now or fall back to manual reading — do not build silently

For each incomplete section, run the corresponding query, update the section in starting.md, remove the [TBD...] marker.

If NO (manual):

Read only the codebase files relevant to the incomplete sections. Update starting.md accordingly.

In both cases: update the Updated: date in starting.md.

Step 4 — Read the latest checkpoint

Find the highest-numbered checkpoint file in checkpoint_claudio/ and read it.

Step 5 — Report to the user

2-3 line summary of the last session's changes, then confirm you are ready.

---

PHASE 2 — During the session (after every modification)

After every modification to the project (create, edit, or delete files; refactor; add features; fix bugs; change config), immediately append an entry to the active checkpoint file.

Entry format

## [YYYY-MM-DD HH:MM] - <short title>
- What: <concise description of what was done>
- Files: <list of affected files>
- Why: <reason / problem solved>

Rules:

• Write the entry right after the modification — do not batch entries
• Keep it short: 3-5 lines per entry
• Title must be readable at a glance
• Never edit previous entries (checkpoints are append-only)

---

PHASE 3 — File rotation

After writing an entry, check the line count of the active checkpoint:

wc -l checkpoint_claudio/checkpointN.md

If it exceeds 200 lines:

1. Finish writing the current entry (never cut an entry in half)
2. Create the next file:

# Checkpoint N+1
_Continues from checkpointN.md_

3. Write all subsequent entries in the new file

---

PHASE 4 — Updating starting.md

Update checkpoint_claudio/starting.md when:

• You discover something about the codebase not yet documented in it
• A key dependency is added or removed
• The architecture or main flow changes
• You find a quirk worth remembering for future sessions

If graphify is available and the section to update is structural (architecture, relationships, flow), prefer:

graphify query "<specific question about the changed part>"

Then update only the relevant sections. Always update the Updated: date.

---

Read priority

starting.md → latest checkpointN.md → graphify query → codebase (last resort)

---

COMMAND: /historia

Triggered by: /historia

Reads the full project history across all checkpoints and produces a consolidated timeline. Use when the user wants to recall everything that happened in the project, understand the evolution of the codebase, or prepare a handoff/summary.

Steps

Step 1 — Read starting.md

Read checkpoint_claudio/starting.md in full.

Step 2 — Read ALL checkpoint files in order

Find every checkpoint file and read them in numeric order:

ls checkpoint_claudio/checkpoint*.md | sort -V

Read each one completely, from checkpoint1.md to the last.

Step 3 — Build the timeline

Produce a structured output with this format:

# Project history: <project name>
<one-line project description from starting.md>

## Timeline

### [date range of checkpoint1] — checkpoint1.md
- <entry 1 title>: <one-line summary>
- <entry 2 title>: <one-line summary>
...

### [date range of checkpoint2] — checkpoint2.md
...

## Summary
- Total checkpoints: N
- Total entries: N
- Key milestones: <3-5 most significant changes across all checkpoints>
- Current state: <what the project looks like now, based on all entries>

Keep each entry summary to one line. The goal is a scannable overview, not a repeat of the full checkpoint content.

Step 4 — Offer to go deeper

After presenting the timeline, ask:

"Want me to expand any specific checkpoint or period?"

---

COMMAND: /retroso

Triggered by: /retroso or /retroso "<context>"

Checkpoint-assisted debugging. Helps identify when and why something broke by cross-referencing checkpoint history with the current broken state. The user can provide optional context: what last worked, what is broken, any error messages or symptoms.

Input

/retroso with no arguments → Claude asks for context before starting.

/retroso "<free text>" → the text can contain any combination of:

• When things last worked: "worked before checkpoint3", "was fine yesterday", "broke after the refactor"
• What is broken: "the API returns 500", "the pipeline crashes at step 2", "auth module throws KeyError"
• Error messages or stack traces (paste directly after the command)

Steps

Step 1 — Collect context (if not provided)

If invoked with no arguments, ask:

"Tell me what broke and any context you have:

• When did things last work? (date, checkpoint number, or describe the state)
• What exactly is broken? (behavior, error, module)
• Any error message or stack trace? (paste it here)"

Wait for the answer before proceeding.

Step 2 — Read starting.md

Read checkpoint_claudio/starting.md to understand the project architecture.

Step 3 — Identify the search window

From the user's context, determine where to start looking:

• If the user named a checkpoint ("broke after checkpoint3"): start reading from that checkpoint
• If the user named a date: find the checkpoint files that contain that date and start from there
• If no time reference: read ALL checkpoints from the beginning

ls checkpoint_claudio/checkpoint*.md | sort -V

Step 4 — Scan checkpoints for suspects

Read the checkpoints in the identified window. For each entry, flag it as a suspect if it:

• Modified files related to the broken functionality
• Changed shared dependencies, config files, or environment variables
• Introduced a refactor or structural change
• Was done close in time to when the breakage appeared

Build a suspect list:

## Suspects (most likely → least likely)

1. [YYYY-MM-DD HH:MM] - <entry title> (checkpoint N)
   Changed: <files>
   Why suspicious: <reason>

2. ...

Step 5 — Targeted investigation

For each suspect, investigate the actual current state of the affected files. If graphify is available:

graphify query "How does <broken module/function> connect to <changed file>?"

Otherwise read the relevant files directly.

Cross-reference:

• Does the current code match what the checkpoint entry says was changed?
• Are there any inconsistencies between the checkpoint description and what is actually on disk?
• Does the broken behavior align with the change described in the suspect entry?

Step 6 — Report

Produce a structured debug report:

# /retroso report

## What is broken
<description from user context>

## Last known good state
<when / which checkpoint the project was last working>

## Suspect changes (ordered by likelihood)

### 1. Most likely cause
- Checkpoint entry: [date] - <title>
- Files changed: <list>
- Why this is likely: <reasoning>
- What to check: <specific thing to verify or revert>

### 2. ...

## Recommended next steps
1. <concrete action — e.g. "revert X in file Y and test">
2. <concrete action>
3. ...

## If none of the above resolves it
<what to look at next — e.g. environment, external dependencies, data>

Step 7 — Offer to act

After the report, ask:

"Want me to investigate any of these suspects deeper, or try reverting one of them?"

If the user confirms, proceed with the investigation or the targeted fix, and log the result as a new checkpoint entry (Phase 2 format).

---

Expected folder structure

checkpoint_claudio/
├── starting.md       # codebase summary, updated incrementally
├── checkpoint1.md    # first modifications (append-only)
├── checkpoint2.md    # continues from checkpoint1 (if >200 lines)
└── ...