claude-os/docs/QUICK_REFERENCE.md

Claude OS Quick Reference Guide

Version: 1.0.0 Date: 2025-10-30

---

🎯 Essential Commands

Claude OS Slash Commands

Command	Description	Example
/claude-os-init	Initialize new project with Claude OS	/claude-os-init
/claude-os-search [query]	Search across knowledge bases	/claude-os-search "appointment flow"
/claude-os-remember [content]	Quick save to project memories	/claude-os-remember "Fixed bug in controller by..."
/claude-os-save [title]	Full-featured save with KB selection	/claude-os-save "New Integration Pattern"
/claude-os-list	List all knowledge bases	/claude-os-list
/claude-os-session [action]	Manage development sessions	/claude-os-session start
/claude-os-triggers	Manage trigger phrases	/claude-os-triggers list

Skills (Auto-Trigger)

Skill	Trigger Phrases	What It Does
remember-this	"remember this:", "save this:", "document this:"	Automatically saves to memories
initialize-project	Manual invocation	Analyzes codebase, generates standards
memory	Manual invocation	Simple memory management

Agent-OS Commands (If Installed)

Command	Description	Use Case
/new-spec [name]	Initialize feature specification	/new-spec user-authentication
/create-spec	Full spec workflow with questions	After /new-spec, gather requirements
/plan-product	Create product documentation	Mission, roadmap, tech stack
/implement-spec [name]	Implement feature following tasks	/implement-spec user-authentication

---

📚 Knowledge Base Types

Auto-created for each project:

1. {project}-project_memories - Your AI's memory

   • Decisions made during development
   • Patterns discovered
   • Bug fixes and solutions
   • Architecture choices

2. {project}-project_profile - Standards & practices

   • Coding standards
   • Architecture documentation
   • Development practices
   • Tech stack details

3. {project}-project_index - Codebase index

   • File structure
   • Key components
   • Integration points

4. {project}-knowledge_docs - Documentation

   • Project README
   • API docs
   • User guides
   • Technical specifications

---

🔄 Common Workflows

Start New Session

# 1. Check if session exists (automatic prompt)
# 2. Choose: continue, start new, or just chat
# 3. Claude loads relevant memories automatically

Save Important Insight

# Quick save (to project_memories)
/claude-os-remember "Discovered that Rails 4 doesn't support X, use Y instead"

# Full save (choose KB and category)
/claude-os-save "Rails 4 API Workaround" MyProject-project_memories Troubleshooting

Search for Past Work

# Search all memories
/claude-os-search "how did we handle appointments"

# Search specific KB
/claude-os-search "integration patterns" MyProject-knowledge_docs

Create Feature Specification (with Agent-OS)

# 1. Initialize spec
/new-spec manual-appointment-times

# 2. Start spec creation workflow
/create-spec
# Answer 1-3 questions at a time
# Upload screenshots/mockups if needed
# Review generated spec.md and tasks.md

# 3. Implement the spec
/implement-spec manual-appointment-times
# Claude follows tasks.md step-by-step

# 4. Verify implementation
# Agent runs checks automatically

---

🔧 Production Commands (Server)

Service Management

# Start/Stop/Restart
sudo systemctl start claude-os
sudo systemctl stop claude-os
sudo systemctl restart claude-os
sudo systemctl status claude-os

# View logs in real-time
sudo journalctl -u claude-os -f
tail -f /opt/claude-os/logs/claude-os.log

Health Checks

# Check MCP server
curl http://localhost:8051/health

# Check Ollama
curl http://localhost:11434/api/tags

# List knowledge bases
curl http://localhost:8051/api/kb/list

# Get KB statistics
curl http://localhost:8051/api/kb/MyProject-knowledge_docs/stats

Backups

# Manual backup
/opt/claude-os/backup.sh

# Restore from backup
sudo systemctl stop claude-os
cp /opt/claude-os-backups/claude-os-YYYYMMDD_HHMMSS.db \
   /opt/claude-os/data/claude-os.db
sudo systemctl start claude-os

Copy Local Database to Production (SECRET SAUCE!)

# Copy your local Claude OS database (with all knowledge) to production
# This transfers ALL memories, indexed code, and learned patterns!

# From your Mac:
scp ~/Projects/claude-os/data/claude-os.db \
    deploy@staging.pistn.com:/tmp/claude-os-local.db

# On the server:
sudo systemctl stop claude-os
sudo cp /tmp/claude-os-local.db /opt/claude-os/data/claude-os.db
sudo chown deploy:deploy /opt/claude-os/data/claude-os.db
sudo systemctl start claude-os

# Verify:
curl http://localhost:8051/api/kb/list

Updates

# Quick update (runs git pull, pip install, restart)
/opt/claude-os/update.sh

# Manual update
cd /opt/claude-os
git pull origin main
source venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart claude-os

---

🌐 API Endpoints (For Integration)

Query Knowledge Base

curl -X POST "http://localhost:8051/api/query" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_name": "MyProject-knowledge_docs",
    "query": "How do I configure the feature?",
    "use_hybrid": true,
    "use_rerank": true
  }'

Create Project

curl -X POST "http://localhost:8051/api/projects" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "MyProject",
    "tech_stack": "Ruby on Rails",
    "database": "MySQL",
    "description": "Project description"
  }'

Upload Document

curl -X POST "http://localhost:8051/api/kb/MyProject-knowledge_docs/upload" \
  -F "file=@/path/to/document.md"

Import Directory

curl -X POST "http://localhost:8051/api/kb/MyProject-knowledge_docs/import" \
  -d "directory_path=/path/to/docs"

List Knowledge Bases

curl "http://localhost:8051/api/kb/list"

Delete Document

curl -X DELETE "http://localhost:8051/api/kb/MyProject-knowledge_docs/documents/filename.md"

---

🐛 Quick Troubleshooting

"Command not found: /claude-os-init"

# Re-run install script
cd /path/to/claude-os
./install.sh

"Connection refused to localhost:8051"

# Check if Claude OS is running
sudo systemctl status claude-os

# If not running, start it
sudo systemctl start claude-os

# Check logs for errors
sudo journalctl -u claude-os -n 50

"Database is locked"

# Stop service
sudo systemctl stop claude-os

# Check for multiple processes
ps aux | grep claude-os

# Kill any stuck processes
kill -9 <PID>

# Restart
sudo systemctl start claude-os

Slow Responses

# Check system load
uptime
htop

# Check if using correct model
ollama list

# Consider smaller model for speed
ollama pull llama3.1:3b
# Update config to use llama3.1:3b

Ollama Won't Start

# Check status
sudo systemctl status ollama

# Check if port is in use
sudo lsof -i :11434

# Restart Ollama
sudo systemctl restart ollama

# Verify model downloaded
ollama list

---

💡 Pro Tips

Trigger Phrases (Auto-Save)

When you say these, Claude automatically saves to memories:

• "Remember this:"
• "Save this:"
• "Document this:"
• "Note this:"
• "Keep in mind:"

Search Tips

• Use natural language: "how did we fix the bug"
• Be specific: "integration timeout error"
• Try variations: "auto accept" vs "automatic acceptance"

Session Management

• Start sessions for major features
• End sessions to save progress
• Resume sessions across days
• Sessions track: task, branch, decisions, blockers

Best Practices

1. Save liberally - Every insight makes Claude smarter
2. Search first - Before reinventing, check memories
3. Use sessions - Track complex features end-to-end
4. Document decisions - Why you chose approach X over Y
5. Update regularly - Run /opt/claude-os/update.sh weekly

---

📊 Performance Expectations

Local Development (Mac)

• Query response: 2-10 seconds
• Memory search: 1-3 seconds
• Document upload: < 1 second

Production Server (16 CPU / 32GB RAM)

• Simple queries: 1-5 seconds
• Complex queries: 5-15 seconds
• Concurrent users: 50+ without slowdown

---

🔐 Security Notes

Local Development

• Runs on localhost:8051
• Only accessible from your machine
• Data stays local

Production Server

• MCP server localhost only (127.0.0.1)
• External access via app (authenticated)
• Daily backups, 7-day retention
• No data sent to external APIs
• Ollama runs locally (not OpenAI)

---

📞 Support & Resources

Logs Locations

• Local: ~/Projects/claude-os/logs/
• Production: /opt/claude-os/logs/
• Systemd: sudo journalctl -u claude-os

Config Locations

• Local: ~/Projects/claude-os/claude-os-config.json
• Production: /opt/claude-os/claude-os-config.json
• Project: .claude-os/config.json

Documentation

• Full README: README.md
• Deployment Guide: docs/DEPLOYMENT_GUIDE.md
• Sharing Guide: SHARING_GUIDE.md

---

🎓 Cheat Sheet Summary

┌─────────────────────────────────────────────────┐
│           CLAUDE OS QUICK REFERENCE             │
├─────────────────────────────────────────────────┤
│ Search:     /claude-os-search "query"           │
│ Remember:   /claude-os-remember "content"       │
│ Save:       /claude-os-save "title"             │
│ List:       /claude-os-list                     │
│ Init:       /claude-os-init                     │
├─────────────────────────────────────────────────┤
│ Health:     curl localhost:8051/health          │
│ Status:     sudo systemctl status claude-os     │
│ Logs:       sudo journalctl -u claude-os -f     │
│ Backup:     /opt/claude-os/backup.sh            │
│ Update:     /opt/claude-os/update.sh            │
├─────────────────────────────────────────────────┤
│ Auto-save:  "remember this: ..."                │
│ Agent-OS:   /new-spec, /create-spec             │
│ Implement:  /implement-spec [name]              │
└─────────────────────────────────────────────────┘

---

Claude CLI + Claude OS = Invincible! 🚀