claudetools/START_HERE.md

🚀 ClaudeTools - Start Here

Welcome! This is your MSP Work Tracking System with AI Context Recall.

---

⚡ Quick Start (First Time)

1. Start the API

# Open terminal in D:\ClaudeTools
api\venv\Scripts\activate
python -m api.main

✅ API running at: http://localhost:8000 📚 Docs available at: http://localhost:8000/api/docs

---

2. Enable Context Recall (One-Time Setup)

Open a NEW terminal (keep API running):

cd D:\ClaudeTools
bash scripts/setup-context-recall.sh

This will:

• ✅ Generate JWT token
• ✅ Detect/create project
• ✅ Configure environment
• ✅ Test the system
• ✅ Enable automatic context injection

Takes ~2 minutes - then you're done forever!

---

3. Verify Everything Works

bash scripts/test-context-recall.sh

Should show:

✅ API connectivity
✅ Authentication
✅ Context recall working
✅ Context saving working
✅ Hooks executing

---

🎯 What You Get

Cross-Machine Context Continuity

Machine A: "Build user authentication"
  → Context saves automatically

Machine B (tomorrow): "Continue with that project"
  → Context recalls automatically
  → Claude knows: "You were implementing JWT auth..."

Zero effort required - hooks handle everything!

---

📖 How To Use

Normal Claude Code Usage

Just use Claude Code as normal - context recall happens automatically:

1. Before each message → Hook recalls relevant context from database
2. After each task → Hook saves new context to database
3. Cross-machine → Same context on any machine

Manual Context Operations

Recall context for current project:

curl "http://localhost:8000/api/conversation-contexts/recall?project_id=$PROJECT_ID&limit=10" \
  -H "Authorization: Bearer $JWT_TOKEN"

Save important context:

POST /api/conversation-contexts
{
  "project_id": "uuid",
  "title": "Implemented feature X",
  "dense_summary": "Added JWT auth with Argon2 hashing...",
  "tags": ["auth", "security", "jwt"]
}

Check project state:

GET /api/project-states/by-project/{project_id}

---

📂 Key Files You Should Know

File	Purpose
.claude/claude.md	Auto-loaded context (read on Claude startup)
SESSION_STATE.md	Complete project history
.claude/context-recall-config.env	Your JWT token & settings
.claude/hooks/user-prompt-submit	Auto-recalls context
.claude/hooks/task-complete	Auto-saves context

---

🔧 Common Tasks

View All Projects

curl http://localhost:8000/api/projects \
  -H "Authorization: Bearer $JWT_TOKEN"

Create New Project

POST /api/projects
{
  "name": "New Website",
  "client_id": "client-uuid",
  "status": "planning"
}

Log Decision

POST /api/decision-logs
{
  "project_id": "uuid",
  "decision_type": "technical",
  "decision_text": "Using PostgreSQL for main database",
  "rationale": "ACID compliance, JSON support, mature",
  "impact": "high"
}

Track Work Session

POST /api/sessions
{
  "project_id": "uuid",
  "machine_id": "uuid",
  "started_at": "2026-01-16T10:00:00Z"
}

---

🎛️ Configuration

Database:

• Host: 172.16.3.20:3306
• Database: claudetools
• User: claudetools
• Password: In C:\Users\MikeSwanson\claude-projects\shared-data\credentials.md

API:

• URL: http://localhost:8000
• Docs: http://localhost:8000/api/docs
• Auth: JWT Bearer tokens

Context Recall:

• Config: .claude/context-recall-config.env
• Min Score: 5.0 (adjustable)
• Max Contexts: 10 (adjustable)

---

🐛 Troubleshooting

API Won't Start

# Check if already running
netstat -ano | findstr :8000

# Test database connection
python test_db_connection.py

Context Recall Not Working

# Run diagnostics
bash scripts/test-context-recall.sh

# Check hook permissions
ls -l .claude/hooks/
# Should show: -rwxr-xr-x (executable)

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

Need to Reset

# Re-run setup
bash scripts/setup-context-recall.sh

---

📊 System Status

Current State:

• ✅ 130 API endpoints operational
• ✅ 43 database tables migrated
• ✅ 99.1% test pass rate
• ✅ Context recall system ready
• ✅ Encryption & auth working
• ✅ Claude Code hooks installed

What's Built:

• Core APIs (Machines, Clients, Projects, Sessions, Tags)
• MSP Work Tracking (Work Items, Tasks, Billable Time)
• Infrastructure Management (Sites, Infrastructure, Services, Networks, Firewalls, M365)
• Credentials Management (Encrypted storage, Audit logs, Incidents)
• Context Recall (Conversations, Snippets, Project States, Decisions)

---

📚 Documentation

Quick References:

• .claude/CONTEXT_RECALL_QUICK_START.md - One-page context recall guide
• .claude/claude.md - Auto-loaded project context
• SESSION_STATE.md - Complete implementation history

Full Guides:

• CONTEXT_RECALL_SETUP.md - Detailed setup instructions
• .claude/CONTEXT_RECALL_ARCHITECTURE.md - System architecture
• .claude/hooks/README.md - Hook documentation
• .claude/hooks/EXAMPLES.md - Real-world examples

Test Reports:

• TEST_PHASE5_RESULTS.md - Phase 5 API tests
• TEST_CONTEXT_RECALL_RESULTS.md - Context recall tests

---

🎯 Next Steps

1. ✅ You are here - Reading this guide
2. ⏭️ Start API - python -m api.main
3. ⏭️ Run setup - bash scripts/setup-context-recall.sh
4. ⏭️ Test system - bash scripts/test-context-recall.sh
5. ✨ Start using Claude Code - Context recall is automatic!

---

💡 Pro Tips

Token Efficiency:

• Context compression achieves 90-95% reduction
• Only relevant context injected (filtered by tags, relevance)
• Automatic deduplication

Cross-Machine Workflow:

1. Work on any machine
2. Context saves to database automatically
3. Switch machines anytime
4. Context recalls automatically
5. Zero manual syncing needed

Building Institutional Memory:

• Every decision auto-tagged
• Patterns emerge over time
• Knowledge grows with usage
• Most-used snippets ranked higher

---

Need Help? Check .claude/claude.md for comprehensive context or SESSION_STATE.md for project history.

Ready to go? Run: bash scripts/setup-context-recall.sh