Skip to main content
command CX Codex

save-session-learnings — Claude Code command: what it does

The save-session-learnings command for Claude Code saves useful findings from a coding session to CLAUDE.md and AGENTS.md after debugging or a substantial task.

MIT ★ 1,424 updated 2026-10-06

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/save-session-learnings.md
Open on GitHub

What save-session-learnings does

The command reviews Git changes and history, then draws on the session conversation for bug fixes, design choices, project patterns, and commands that worked. It checks CLAUDE.md and AGENTS.md before writing, so existing notes can be skipped or refreshed instead of copied.

It writes matching updates to both files in the project root. New notes can go into Session Log or sections such as Gotchas, Patterns, and Commands; entries are meant to stay brief and actionable. The Git review uses HEAD~5, so that history reference must be available for this part of the context check to work.

What it helps with

  • record a bug’s root cause and fix for later sessions
  • carry architecture decisions into project documentation
  • save build and test commands that worked
  • refresh outdated notes without duplicating existing guidance

Example prompts for the agent

  • /save-session-learnings — record the findings from this debugging session in CLAUDE.md and AGENTS.md.
  • /save-session-learnings — document the architecture choices and working commands from this session.
  • /save-session-learnings — check the project docs and add any new patterns or gotchas.

How to install save-session-learnings

Manually: put the files in place

.claude/commands/save-session-learnings.md

Call it with /save-session-learnings. For all projects use ~/.claude/commands/

Questions about save-session-learnings

How do I install save-session-learnings in Claude Code?

Place the command file at .claude/commands/save-session-learnings.md.

What does save-session-learnings do?

It gathers useful findings from the current session, checks the project docs, and writes new or updated notes to CLAUDE.md and AGENTS.md.

Which files does the command update?

It updates CLAUDE.md and AGENTS.md in the project root, keeping the findings in both files aligned.

Source text

save-session-learnings.md · MIT
---
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(git:*)
description: Document session learnings to CLAUDE.md and AGENTS.md. Use after completing significant tasks, debugging sessions, or discovering project patterns.
---

# Save Session Learnings

Capture and persist significant discoveries from this session into project documentation so knowledge survives across sessions and agents.

## Phase 1: Gather Session Context

Collect evidence of what was learned during this session:

```bash
git diff HEAD~5 --stat
git log --oneline -10
git diff --name-only HEAD~5
```

Also review the conversation history for:

- Bugs that were debugged (root cause + fix)
- Architecture decisions made
- Configuration or environment discoveries
- Patterns established or followed
- Commands that worked (or failed)
- Gotchas and edge cases encountered

## Phase 2: Categorize Learnings

Sort each finding into one of these categories:

### Architecture

- Key files, folders, data flow, component relationships
- Service boundaries, module dependencies

### Patterns

- Naming conventions, code style, recurring design patterns
- File structure conventions, import ordering

### Gotchas

- Things that break, common errors, non-obvious behavior
- Workarounds for known issues

### Commands

- Build, test, deploy, dev server commands that work
- Tool-specific invocations with correct flags

### Decisions

- Why something was done a certain way
- Trade-offs considered, alternatives rejected

## Phase 3: Check Existing Documentation

Before writing, read both files to avoid duplicating entries:

1. Use Glob to check if `CLAUDE.md` and `AGENTS.md` exist in the project root
2. If they exist, Read them fully
3. Compare gathered learnings against existing entries
4. Skip anything already documented
5. If existing entries are outdated, update them instead of adding duplicates

## Phase 4: Write Learnings

Update both `CLAUDE.md` and `AGENTS.md` in the project root (create if missing).

### Format for New Entries

Append to the `## Session Log` section (create it if absent). Use this format:

```markdown
## Session Log

- YYYY-MM-DD: [Category] Brief, actionable description of what was learned
```

For structured learnings, append to the relevant section (`### Gotchas`, `### Patterns`, etc.) or create the section if it does not exist:

```markdown
### Gotchas

- `short description` -- explanation of the issue and the workaround

### Patterns

- Pattern name -- where it applies and why

### Commands

- `command here` -- what it does, when to use it
```

### Rules

- **Concise**: Each entry should be 1-2 lines max. Favor telegraphic style.
- **Actionable**: Write entries that help a future developer take action, not just understand history.
- **No duplicates**: If the learning is already documented, skip it or update the existing entry.
- **Date stamp**: Always include today's date in Session Log entries.
- **Both files**: CLAUDE.md and AGENTS.md must contain the same learnings. Keep them in sync.
- **Preserve existing content**: Never overwrite or remove existing entries. Only append or update.

## Phase 5: Confirm

After writing, summarize what was added:

```
## Learnings Saved

- **New entries added**: X
- **Existing entries updated**: Y
- **Skipped (already documented)**: Z

### Added
1. [Category] Description
2. [Category] Description

### Updated
1. [What changed and why]
```

## When to Use

- After completing a significant feature or bug fix
- After a long debugging session
- After discovering non-obvious project behavior
- After setting up a new tool or integration
- Before ending a session where important context was built up
- When you realize "a future me would want to know this"

© CloudAI-X · MIT · CloudAI-X/claude-workflow-v2

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set46

The whole set →
parallel-review parallel-review runs code review across multiple directories or files simultaneously, one subagent per target. CX Codex +1 ★ 1,424repo stars code-simplifier The code-simplifier command reviews recent changes and proposes cleaner code without changing behavior. Use it after implementing a feature or refactoring. CX Codex +1 ★ 1,424repo stars security-scan security-scan is a command for Claude Code that checks a repository for hardcoded secrets, vulnerable dependencies, injection, XSS and weak config before a commit or PR. CX Codex +1 ★ 1,424repo stars verify-changes verify-changes executes adversarial multi-subagent verification across recent code diffs to weed out bugs and false alarms. CX Codex +1 ★ 1,424repo stars analyzing-projects analyzing-projects walks through an unfamiliar codebase step by step: stack, structure, patterns, dev commands — useful when onboarding onto a project. CX Codex +1 ★ 1,424repo stars plan Creates and maintains a structured PLAN.md file in your project root to track phases, task dependencies, and progress logs. CX Codex +1 ★ 1,424repo stars refactor-guided refactor-guided guides structural refactoring in small steps and runs tests after each change. It keeps feature work separate from code restructuring. CX Codex +1 ★ 1,424repo stars convex-backend convex-backend is a Claude Code skill that loads Convex guidelines for TypeScript functions, schemas, validators, queries, mutations, actions, subscriptions, and file storage. It supports type-safe backend development. CX Codex +1 ★ 1,424repo stars

Project sponsors

Companies that keep this analytics open