claudetools/.claude/commands

Claude Code Commands

Custom commands that extend Claude Code's capabilities.

Available Commands

/snapshot - Quick Context Save

Save conversation context on-demand without requiring a git commit.

Usage:

/snapshot
/snapshot "Custom title"
/snapshot --important
/snapshot --offline

When to use:

• Save progress without committing code
• Capture important discussions
• Remember exploratory changes
• Switching contexts/machines
• Multiple times per hour

Documentation: snapshot.md Quick Start: .claude/SNAPSHOT_QUICK_START.md

---

/checkpoint - Full Git + Context Save

Create git commit AND save context to database.

Usage:

/checkpoint

When to use:

• Code is ready to commit
• Reached stable milestone
• Completed feature/fix
• End of work session
• Once or twice per feature

Documentation: checkpoint.md

---

/sync - Cross-Machine Context Sync

Synchronize queued contexts across machines.

Usage:

/sync

When to use:

• Manually trigger sync
• After offline work
• Before switching machines
• Check queue status

Documentation: sync.md

---

/create-spec - App Specification

Create comprehensive application specification for AutoCoder.

Usage:

/create-spec

When to use:

• Starting new project
• Documenting existing app
• Preparing for AutoCoder
• Architecture planning

Documentation: create-spec.md

---

Command Comparison

Command	Git Commit	Context Save	Speed	Use Case
/snapshot	No	Yes	Fast	Save progress
/checkpoint	Yes	Yes	Slower	Save code + context
/sync	No	No	Fast	Sync contexts
/create-spec	No	No	Medium	Create spec

Common Workflows

Daily Development

Morning:
  - Start work
  - /snapshot Research phase

Mid-day:
  - Complete feature
  - /checkpoint

Afternoon:
  - More work
  - /snapshot Progress update

End of day:
  - /checkpoint
  - /sync

Research Heavy

Research:
  - /snapshot multiple times
  - Capture decisions

Implementation:
  - /checkpoint for features
  - Link code to research

New Project

Planning:
  - /create-spec
  - /snapshot Architecture decisions

Development:
  - /snapshot frequently
  - /checkpoint for milestones

Setup

Required for context commands:

bash scripts/setup-context-recall.sh

This configures:

• JWT authentication token
• API endpoint URL
• Project ID
• Context recall settings

Configuration file: .claude/context-recall-config.env

Documentation

Quick References:

• .claude/SNAPSHOT_QUICK_START.md - Snapshot guide
• .claude/SNAPSHOT_VS_CHECKPOINT.md - When to use which
• .claude/CONTEXT_RECALL_QUICK_START.md - Context recall system

Full Documentation:

• snapshot.md - Complete snapshot docs
• checkpoint.md - Complete checkpoint docs
• sync.md - Complete sync docs
• create-spec.md - Complete spec creation docs

Implementation:

• SNAPSHOT_IMPLEMENTATION.md - Technical details

Testing

Test snapshot:

bash scripts/test-snapshot.sh

Test context recall:

bash scripts/test-context-recall.sh

Test sync:

bash .claude/hooks/sync-contexts

Troubleshooting

Commands not working:

# Check configuration
cat .claude/context-recall-config.env

# Verify executable
ls -l .claude/commands/

# Make executable
chmod +x .claude/commands/*

Context not saving:

# Check API connection
curl -I http://172.16.3.30:8001/api/health

# Regenerate token
bash scripts/setup-context-recall.sh

# Check logs
tail -f .claude/context-queue/sync.log

Project ID issues:

# Set manually
git config --local claude.projectid "$(uuidgen)"

# Verify
git config --local claude.projectid

Adding Custom Commands

Structure:

.claude/commands/
├── command-name           # Executable bash script
└── command-name.md        # Documentation

Template:

#!/bin/bash
# Command description

set -euo pipefail

# Load configuration
source .claude/context-recall-config.env

# Command logic here
echo "Hello from custom command"

Make executable:

chmod +x .claude/commands/command-name

Test:

bash .claude/commands/command-name

Use in Claude Code:

/command-name

Command Best Practices

Snapshot:

• Use frequently (multiple per hour)
• Descriptive titles
• Don't over-snapshot (meaningful moments)
• Tag auto-extraction works best with good context

Checkpoint:

• Only checkpoint clean state
• Good commit messages
• Group related changes
• Don't checkpoint too often

Sync:

• Run before switching machines
• Run after offline work
• Check queue status periodically
• Auto-syncs on most operations

Create-spec:

• Run once per project
• Update when architecture changes
• Include all important details
• Use for AutoCoder integration

Advanced Usage

Snapshot with importance:

/snapshot --important "Critical architecture decision"

Offline snapshot:

/snapshot --offline "Working without network"

Checkpoint with message:

/checkpoint
# Follow prompts for commit message

Sync specific project:

# Edit sync script to filter by project
bash .claude/hooks/sync-contexts

Integration

With Context Recall:

• Commands save to database
• Automatic recall in future sessions
• Cross-machine continuity
• Searchable knowledge base

With AutoCoder:

• /create-spec generates AutoCoder input
• Commands track project state
• Context feeds AutoCoder sessions
• Complete audit trail

With Git:

• /checkpoint creates commits
• /snapshot preserves git state
• No conflicts with git workflow
• Clean separation of concerns

Support

Questions:

• Check documentation in this directory
• See .claude/CLAUDE.md for project overview
• Review test scripts for examples

Issues:

• Verify configuration
• Check API connectivity
• Review error messages
• Test with provided scripts

Updates:

• Update via git pull
• Regenerate config if needed
• Test after updates
• Check for breaking changes

---

Quick command reference:

• /snapshot - Quick save (no commit)
• /checkpoint - Full save (with commit)
• /sync - Sync contexts
• /create-spec - Create app spec

Setup: bash scripts/setup-context-recall.sh Test: bash scripts/test-snapshot.sh Docs: Read the .md file for each command