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 ~/ClaudeTools
cd ~/ClaudeTools
source api/venv/bin/activate  # Mac/Linux
# OR: api\venv\Scripts\activate  # Windows
python -m api.main

[OK] API running at: http://localhost:8000 [INFO] Docs available at: http://localhost:8000/api/docs

---

2. Enable Context Recall (One-Time Setup)

Open a NEW terminal (keep API running):

cd ~/ClaudeTools
bash scripts/setup-context-recall.sh

This will:

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

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

---

3. Verify Everything Works

bash scripts/test-context-recall.sh

Should show:

[OK] API connectivity
[OK] Authentication
[OK] Context recall working
[OK] Context saving working
[OK] 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.30:3306
• Database: claudetools
• User: claudetools
• Password: In credentials.md

API:

• Local: http://localhost:8000
• Production: http://172.16.3.30:8001
• 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
lsof -i :8000  # Mac/Linux
# OR: netstat -ano | findstr :8000  # Windows

# 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:

• [OK] 130 API endpoints operational
• [OK] 43 database tables migrated
• [OK] 99.1% test pass rate
• [OK] Context recall system ready
• [OK] Encryption & auth working
• [OK] 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. [OK] You are here - Reading this guide
2. [NEXT] Start API - python -m api.main
3. [NEXT] Run setup - bash scripts/setup-context-recall.sh
4. [NEXT] Test system - bash scripts/test-context-recall.sh
5. [NEXT] 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