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

```bash
# 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):

```bash
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
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:**
```bash
curl "http://localhost:8000/api/conversation-contexts/recall?project_id=$PROJECT_ID&limit=10" \
  -H "Authorization: Bearer $JWT_TOKEN"
```

**Save important context:**
```python
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:**
```python
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
```bash
curl http://localhost:8000/api/projects \
  -H "Authorization: Bearer $JWT_TOKEN"
```

### Create New Project
```python
POST /api/projects
{
  "name": "New Website",
  "client_id": "client-uuid",
  "status": "planning"
}
```

### Log Decision
```python
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
```python
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
```bash
# 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
```bash
# 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
```bash
# 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`