Keep

Lightweight, intelligent project memory for Claude Code

Keep helps you track work, capture learnings as you code, and grow project context naturally through CLAUDE.md files. Claude detects resumable work at session start and provides workflow hints to help you build a natural cadence.

What is Keep?

Keep is a skill + commands system for Claude Code that provides:

• Persistent memory across sessions via .claude/work/ tracking files
• Intelligent learning capture - decisions, patterns, and gotchas documented automatically
• Context evolution - proactive suggestions to create/update CLAUDE.md files as patterns emerge
• GitHub integration - sync progress to issues, recommend next work based on continuity
• Zero ceremony - natural workflows that enhance rather than constrain

Why Keep?

• No complex setup - leverages native Claude Code CLAUDE.md loading
• Solo-optimized - built for individual developers, not enterprise ceremony
• Graceful degradation - works offline, without GitHub, with minimal files
• Intelligence over automation - suggests and learns, doesn't enforce rigid processes

How Keep Works

Keep provides session continuity and workflow hints - Claude detects when you have resumable work at the start of a new conversation, and agents provide helpful next-step hints to teach you the natural rhythm.

You invoke Keep commands manually as you work:

• Starting work: Run /keep:start [issue] to load context and begin tracking
• Saving progress: Run /keep:save at natural breakpoints (after features, decisions, or every 30-45 min)
• Completing tasks: Run /keep:done when tests pass and you're ready to move on
• Growing context: Run /keep:grow [directory] to document patterns in CLAUDE.md files

Keep integrates into your workflow through helpful hints:

You: /keep:start 42
Claude: *loads issue, context, creates tracking file*
        💡 Next steps: As you work, use /keep:save to checkpoint progress
        and capture decisions.

You: *work for 45 minutes, implement feature*

You: /keep:save
Claude: *captures progress and decisions*
        💡 Next steps: Continue working, or use /keep:done when you've
        completed the issue and tests pass.

Session resume detection: When you start a new conversation with active work from a recent session (< 48h), Claude will suggest resuming where you left off.

Quick Start

Installation

Option 1: Install from GitHub (Recommended)

# Add the Keep marketplace
/plugin marketplace add https://github.com/lackeyjb/claude-keep

# Install the plugin
/plugin install keep@keep-marketplace

Option 2: Install Locally

# Clone the repository
git clone https://github.com/lackeyjb/claude-keep.git

# Add as local marketplace
/plugin marketplace add ./claude-keep

# Install the plugin
/plugin install keep@keep-marketplace

Getting Started

1. Ensure you have gh CLI installed (optional, for GitHub integration)
2. Keep will automatically create .claude/ directory structure in your projects when you first use a command
3. Create initial project context:

   /keep:grow .

   Keep will analyze your project and suggest creating a root CLAUDE.md with tech stack, architecture, and conventions.
4. Start using commands!

Directory Structure

In your project (auto-created by Keep):

your-project/
├── CLAUDE.md                    # Root context (create manually or let Keep suggest)
├── src/
│   └── auth/
│       └── CLAUDE.md            # Module context (Keep suggests when patterns emerge)
└── .claude/
    ├── work/                    # Active issue tracking (auto-created)
    ├── archive/                 # Completed issues (auto-created)
    └── state.md                 # Current session state (auto-created)

Plugin structure (installed via /plugin install):

keep/
├── .claude-plugin/
│   ├── plugin.json              # Plugin metadata
│   └── marketplace.json         # Marketplace configuration
├── commands/
│   ├── start.md                 # Start work command
│   ├── save.md                  # Save progress command
│   ├── done.md                  # Complete work command
│   └── grow.md                  # Grow context command
├── agents/
│   ├── start.md                 # Start workflow agent
│   ├── save.md                  # Save workflow agent
│   ├── done.md                  # Done workflow agent
│   ├── grow.md                  # Grow workflow agent
│   └── shared/                  # Shared patterns (error handling, principles, etc.)
└── skills/keep/
    ├── SKILL.md                 # Keep skill intelligence
    ├── references/              # File format specs, workflows
    └── scripts/                 # GitHub helpers, scoring algorithm

Commands

/keep:start [issue-number]

Start work on a GitHub issue with full context loading. Automatically detects and resumes interrupted work.

/keep:start 1234

What it does:

• Intelligent resume: Detects if you're resuming previous work on this issue
  • Recent work (< 24h): Instantly resumes with cached data, skips GitHub fetch
  • Moderate (24-48h): Asks whether to resume cached or refetch fresh data
  • Stale (> 48h): Refetches from GitHub to ensure latest status
• Fetches issue from GitHub (when starting fresh or data is stale)
• Loads relevant CLAUDE.md files for context
• Reads recent work from .claude/state.md and archive
• Creates/updates .claude/work/1234.md tracking file
• Suggests approach based on project patterns

Proactive resume detection: Keep watches for session boundaries. When you start a new conversation and have active work from a recent session (< 48h), Claude will proactively suggest resuming:

You: [starts new session]
Claude: "I see you were working on issue #1234 (Add rate limiting) - last updated
        6 hours ago. You had made good progress: middleware 80% complete, 3 decisions
        captured. Want to pick up where you left off?"

Zero-issues workflow: When no issue number is provided and no issues exist:

1. Discover - Searches planning docs (ROADMAP.md, TODO.md) and code signals (TODO/FIXME comments, missing tests)
2. Synthesize - Generates 3-5 actionable issue suggestions with source attribution
3. Create - You select which issues to create, Keep generates and posts them to GitHub
4. Start - You pick which issue to work on, Keep begins normal workflow

Flags:

• --offline - Skip GitHub, work locally only

/keep:save

Save progress and capture learnings.

/keep:save
/keep:save --sync  # Also post update to GitHub

What it does:

• Reviews recent conversation for progress, decisions, learnings
• Filters through "6-month test" - only captures high-value insights
• Updates .claude/work/{issue}.md with timestamped entries
• Checks if patterns emerged (3+ high-value decisions in same area)
• Suggests CLAUDE.md updates when threshold met AND passes quality filter
• Enforces strict size limits: 200 lines (root), 150 lines (module)
• Requires pruning when files >80% capacity
• Optional: Sync progress summary to GitHub

Flags:

• --sync - Force sync to GitHub
• --local - Skip GitHub sync confirmation

/keep:done

Complete work and sync to GitHub.

/keep:done
/keep:done --close  # Also close the issue

What it does:

• Generates comprehensive summary of work completed
• Suggests CLAUDE.md updates for accumulated learnings
• Detects associated PR on current branch
• Posts completion summary to GitHub issue (includes PR link if exists)
• Smart PR-aware issue closing:
  • PR merged: Notes issue auto-closed via PR (GitHub auto-closes)
  • PR open: Keeps issue open (will auto-close when PR merges)
  • PR closed (unmerged): Asks if you want to close manually
  • No PR: Asks about closing issue
• Archives work file to .claude/archive/
• Updates session state
• Recommends next work based on continuity + priority

Flags:

• --close - Close the GitHub issue without asking
• --no-close - Leave issue open without asking
• --no-sync - Skip GitHub interaction
• --no-recommend - Skip next work suggestions

/keep:grow [directory]

Create or update CLAUDE.md files for project context.

/keep:grow .              # Analyze project root
/keep:grow src/auth       # Analyze specific module
/keep:grow --update       # Update existing CLAUDE.md
/keep:grow . --condense   # Prune bloated CLAUDE.md

What it does:

• Analyzes directory for non-obvious patterns and gotchas
• Applies "6-month test" - would this matter later?
• Assesses if CLAUDE.md would be valuable
• Generates concise CLAUDE.md proposal (with line counts)
• Validates size: 200 line max (root), 150 line max (module)
• Requires pruning if >80% capacity before adding content
• Shows proposal for review/editing
• Creates file if approved and within size limits

When to use:

• Initial setup on existing project (create root CLAUDE.md)
• Document a module after non-obvious patterns emerge
• Update existing CLAUDE.md with new learnings
• Condense bloated CLAUDE.md files
• Manually trigger if automatic suggestion was missed

When NOT to use:

• Obvious file structure
• Standard framework patterns only
• No surprising gotchas

Flags:

• --update - Update existing CLAUDE.md
• --condense - Prune bloated CLAUDE.md to fit size limits
• --force - Create even if patterns unclear

Example Workflow

# Start work on issue
/keep:start 1234

# Work on implementation...
# Save progress periodically
/keep:save

# Continue working...
# Save again at natural breakpoints
/keep:save

# Complete and sync
/keep:done --close

Keep automatically:

• Captures decisions and learnings from your saves
• Suggests updating src/auth/CLAUDE.md when patterns emerge (3+ decisions in same area)
• Posts comprehensive summary to GitHub issue #1234
• Recommends issue #1250 as next work (builds on #1234, same area)

Workflow Patterns & User Cadence

Natural Rhythm

Keep works best when used at natural checkpoints in your workflow:

Start of work:

• New session? Claude may suggest resuming recent work
• Starting new issue? Run /keep:start [issue]
• Not sure what to work on? Run /keep:start for recommendations

During work (every 30-45 min or at natural breakpoints):

• Made key decisions? Run /keep:save
• Implemented a feature? Run /keep:save
• Learning something non-obvious? Run /keep:save
• Use --sync flag if you want to post update to GitHub

Completing work:

• Tests pass and PR up? Run /keep:done
• Keep will summarize, recommend next work, and archive
• Use --close to auto-close issue, --no-recommend to skip suggestions

Context gaps:

• Missing docs for a module? Run /keep:grow [directory]
• Keep will analyze and propose CLAUDE.md content
• Happens automatically after 3+ decisions in same area via /keep:save

Example Session

# Morning: Start fresh
/keep:start 1234

# Work for 45 min, implement auth middleware
/keep:save

# Lunch break - checkpoint progress
/keep:save --sync

# Afternoon: finish implementation
# ... more work ...

# Tests pass, PR created
/keep:done --close

# Keep recommends issue #1250 (builds on #1234)
/keep:start 1250

Tips

• Don't overthink it: Save when it feels natural, not on a strict schedule
• Use flags: --sync for GitHub updates, --no-recommend to skip suggestions
• Let patterns emerge: After 3+ saves in a directory, Keep suggests documentation
• Offline works: All commands work without GitHub, just skip sync features

Features

Intelligent Learning Capture

When you run /keep:save, Keep captures from recent conversation:

• Decisions - Technical choices with rationale (filtered through "6-month test")
• Learnings - Non-obvious gotchas, surprises, framework quirks
• Patterns - Critical approaches that prevent mistakes
• Progress - What you accomplished

Quality filter:

• Only captures insights that pass "6-month test" - would this matter later?
• Skips obvious patterns, implementation details, standard framework usage
• Focuses on gotchas, security/performance implications, architectural "why"

Context Evolution

When high-value patterns emerge (3+ decisions passing quality filter):

• Keep suggests creating/updating CLAUDE.md files
• Shows proposed changes as diffs with line counts
• Enforces strict size limits (200 lines root, 150 lines module)
• Requires pruning when >80% capacity before adding
• Gets your approval before updating
• Keeps context ruthlessly concise and high-value

Smart Recommendations

After completing work, Keep recommends next issues based on:

• Continuity (30%) - Same area as recent work (hot cache)
• Priority (30%) - Labels like "urgent", "high-priority"
• Freshness (20%) - Recently updated issues
• Dependencies (20%) - Blockers cleared

GitHub Integration

Optional but powerful:

• Fetches issue details and dependencies
• Posts concise progress updates
• Generates professional completion summaries
• Gracefully degrades when offline

Optimized Context Usage

Keep uses a gatekeeper sub-agent architecture for minimal context consumption:

• Gatekeeper sub-agents centralize common operations (GitHub, state, CLAUDE.md, quality)
• ~180 lines of duplication eliminated across workflows
• 65-80% reduction in context per command vs traditional approaches
• Each workflow (start/save/done/grow) operates in its own context window
• References loaded on-demand only when needed
• Main skill reduced to 222 lines (from 341)
• No context pollution between workflows

Gatekeeper sub-agents handle:

• github-gatekeeper - GitHub operations with offline support
• state-gatekeeper - State and work file management
• claudemd-gatekeeper - CLAUDE.md proposals and size validation
• quality-gatekeeper - Quality assessment and 6-month test

This means:

• Faster command execution
• More room for your actual work
• Reduced token usage
• Better performance on long sessions
• Consistent error handling and offline support

See ARCHITECTURE.md for technical implementation details.

File Formats

.claude/work/{issue}.md

Tracks a single issue with:

• Progress log (timestamped entries)
• Decisions made (with rationale)
• Learnings captured
• Files modified
• Tests status
• Next actions

.claude/state.md

Current session state:

• Active issue and progress
• Recent completed work (last 3)
• Open questions and blockers
• Context (hot areas)

Root CLAUDE.md

Project-wide context (auto-loaded by Claude Code):

• Tech stack
• Architecture patterns
• Project structure
• Development setup
• Conventions
• Recent changes

Module CLAUDE.md (e.g., src/auth/CLAUDE.md)

Domain-specific context (auto-loaded when working in directory):

• Purpose of module
• Key patterns and abstractions
• API/interface
• Recent learnings and gotchas
• Common mistakes
• Dependencies and testing

See skills/keep/references/file-formats.md for complete specifications.

Advanced Usage

Offline Mode

Keep works without GitHub:

/keep-start --offline
# Provide issue details manually
# Keep tracks locally, can sync later

Custom Scripts

Keep includes helper scripts:

github_sync.py - GitHub API operations with retry logic:

python ${CLAUDE_PLUGIN_ROOT}/skills/keep/scripts/github_sync.py fetch-issue 1234

score_issues.py - Score open issues for recommendations:

gh issue list --json number,title,labels,body,updatedAt | \
  python ${CLAUDE_PLUGIN_ROOT}/skills/keep/scripts/score_issues.py --recent-work .claude/state.md

Context Growth

Manually trigger CLAUDE.md creation or updates:

# Analyze and create root CLAUDE.md
/keep:grow .

# Document a specific module
/keep:grow src/auth

# Update existing CLAUDE.md with new patterns
/keep:grow src/api --update

Keep also suggests CLAUDE.md updates automatically during /keep:save when patterns emerge (3+ decisions in same area).

Configuration

Keep is designed to work with minimal configuration. All intelligence lives in skills/keep/SKILL.md.

To customize behavior, edit the skill file to adjust:

• Learning thresholds (default: 3 decisions)
• Scoring weights (default: 30% continuity, 30% priority, 20% freshness, 20% dependencies)
• Auto-save intervals (if enabled)

Philosophy

Intelligence over automation - Keep suggests and learns rather than enforcing rigid processes.

Minimal ceremony - No multi-stage pipelines, complex frontmatter, or file renaming ceremonies.

Progressive disclosure - Context grows naturally as patterns emerge, not created prematurely.

Fail gracefully - Works offline, without GitHub, with minimal files. Degrades features, never breaks workflows.

Solo-first - Optimized for individual developers, extensible for teams.

Comparison to Alternatives

Feature	Keep	Complex PM Tools
Commands	4 core	50+
Files to manage	Minimal	Hundreds
Setup time	< 5 minutes	Hours
Context loaders	Native CLAUDE.md	Custom
Offline support	✅ Full	❌ Limited
Learning curve	Low	High
Ceremony	Minimal	High

Requirements

• Claude Code
• gh CLI (optional, for GitHub integration)
• Git repository (optional, for best experience)

License

MIT

Contributing

This is a personal project but suggestions welcome! The skill is designed to be customized - edit skills/keep/SKILL.md to suit your workflow.

Learn More

• Architecture: ARCHITECTURE.md - Context optimization and sub-agent design
• Skill documentation: skills/keep/SKILL.md - Core philosophy and principles
• File format specs: skills/keep/references/file-formats.md
• Workflow examples: skills/keep/references/workflows.md
• GitHub comment templates: skills/keep/references/templates/
• Troubleshooting: skills/keep/references/troubleshooting.md
• Zero-issues workflow: skills/keep/references/zero-issues.md
• GitHub scripts: skills/keep/scripts/