Mike Swanson
89e5118306
Completely removed the database context recall system while preserving database tables for safety. This major cleanup removes 80+ files and 16,831 lines of code. What was removed: - API layer: 4 routers (conversation-contexts, context-snippets, project-states, decision-logs) with 35+ endpoints - Database models: 5 models (ConversationContext, ContextSnippet, DecisionLog, ProjectState, ContextTag) - Services: 4 service layers with business logic - Schemas: 4 Pydantic schema files - Claude Code hooks: 13 hook files (user-prompt-submit, task-complete, sync-contexts, periodic saves) - Scripts: 15+ scripts (import, migration, testing, tombstone checking) - Tests: 5 test files (context recall, compression, diagnostics) - Documentation: 30+ markdown files (guides, architecture, quick starts) - Utilities: context compression, conversation parsing Files modified: - api/main.py: Removed router registrations - api/models/__init__.py: Removed model imports - api/schemas/__init__.py: Removed schema imports - api/services/__init__.py: Removed service imports - .claude/claude.md: Completely rewritten without context references Database tables preserved: - conversation_contexts, context_snippets, context_tags, project_states, decision_logs (5 orphaned tables remain for safety) - Migration created but NOT applied: 20260118_172743_remove_context_system.py - Tables can be dropped later when confirmed not needed New files added: - CONTEXT_SYSTEM_REMOVAL_SUMMARY.md: Detailed removal report - CONTEXT_SYSTEM_REMOVAL_COMPLETE.md: Final status - CONTEXT_EXPORT_RESULTS.md: Export attempt results - scripts/export-tombstoned-contexts.py: Export tool for future use - migrations/versions/20260118_172743_remove_context_system.py Impact: - Reduced from 130 to 95 API endpoints - Reduced from 43 to 38 active database tables - Removed 16,831 lines of code - System fully operational without context recall Reason for removal: - System was not actively used (no tombstoned contexts found) - Reduces codebase complexity - Focuses on core MSP work tracking functionality - Database preserved for safety (can rollback if needed) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
365 lines
6.4 KiB
Markdown
365 lines
6.4 KiB
Markdown
# 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:**
|
|
```bash
|
|
/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:**
|
|
```bash
|
|
/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:**
|
|
```bash
|
|
/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:**
|
|
```bash
|
|
/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
|
|
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
|
|
bash scripts/test-snapshot.sh
|
|
```
|
|
|
|
**Test context recall:**
|
|
```bash
|
|
bash scripts/test-context-recall.sh
|
|
```
|
|
|
|
**Test sync:**
|
|
```bash
|
|
bash .claude/hooks/sync-contexts
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
**Commands not working:**
|
|
```bash
|
|
# Check configuration
|
|
cat .claude/context-recall-config.env
|
|
|
|
# Verify executable
|
|
ls -l .claude/commands/
|
|
|
|
# Make executable
|
|
chmod +x .claude/commands/*
|
|
```
|
|
|
|
**Context not saving:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
#!/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:**
|
|
```bash
|
|
chmod +x .claude/commands/command-name
|
|
```
|
|
|
|
**Test:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
/snapshot --important "Critical architecture decision"
|
|
```
|
|
|
|
**Offline snapshot:**
|
|
```bash
|
|
/snapshot --offline "Working without network"
|
|
```
|
|
|
|
**Checkpoint with message:**
|
|
```bash
|
|
/checkpoint
|
|
# Follow prompts for commit message
|
|
```
|
|
|
|
**Sync specific project:**
|
|
```bash
|
|
# 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
|