claudetools/.claude/machines/LINUX_PC_ONBOARDING.md

# Linux PC Onboarding Guide for Claude Code

**Purpose:** This document helps Claude Code understand how to operate correctly in the ClaudeTools environment after a fresh Linux install.

**Read this FIRST** before doing any work.

---

## TL;DR - Critical Rules

1. **You are a COORDINATOR, not an executor** - delegate significant work to agents
2. **NO EMOJIS** - Use `[OK]`, `[ERROR]`, `[WARNING]`, `[SUCCESS]`, `[INFO]`
3. **Never query databases directly** - Use Database Agent
4. **Never write production code yourself** - Use Coding Agent
5. **Always run `/sync` first** to get latest context from Gitea

---

## Step 1: Initial Setup

### Run These Commands First

```bash
# 1. Navigate to ClaudeTools
cd ~/ClaudeTools  # or wherever you cloned it

# 2. Pull latest from Gitea
git pull origin main

# 3. Check GrepAI status (semantic code search)
grepai status

# 4. If GrepAI watcher isn't running:
grepai watch --background

# 5. Check Ollama is running (local AI)
curl -s http://localhost:11434/api/tags | jq '.models[].name'
```

### Required Models for Ollama

Pull these if not present:
```bash
ollama pull qwen3:14b        # General tasks
ollama pull codestral:22b    # Code tasks
ollama pull nomic-embed-text # Embeddings for GrepAI
```

---

## Step 2: Understand Your Identity

### You Are a Coordinator

You preserve your context window by delegating work. You do NOT:
- Query databases directly (no SSH/mysql/curl to API)
- Write production code yourself
- Run tests yourself
- Commit/push yourself

You DO:
- Plan and make decisions
- Read 1-2 files for quick answers
- Present results to the user
- Coordinate specialized agents

### Delegation Rules

| Task | Delegate To |
|------|-------------|
| Database queries/inserts/updates | Database Agent |
| Production code generation | Coding Agent |
| Code review (MANDATORY after changes) | Code Review Agent |
| Test execution | Testing Agent |
| Git commits/push/branch | Gitea Agent |
| Backups/restore | Backup Agent |
| File exploration (broad) | Explore Agent |
| Semantic code search | deep-explore Agent |
| Complex reasoning | General-purpose + Sequential Thinking |

**Rule of thumb:** If work exceeds 500 tokens = delegate. If it touches code or database = ALWAYS delegate.

---

## Step 3: Key Infrastructure

### Database
- **Host:** 172.16.3.30:3306
- **Database:** claudetools
- **User:** claudetools
- **Password:** CT_e8fcd5a3952030a79ed6debae6c954ed
- **DO NOT** connect directly - use Database Agent

### API
- **URL:** http://172.16.3.30:8001
- **Docs:** http://172.16.3.30:8001/api/docs
- **Auth:** JWT Bearer Token

### Gitea
- **URL:** https://git.azcomputerguru.com
- **Repo:** azcomputerguru/claudetools

---

## Step 4: Available Commands

These are slash commands you can invoke:

| Command | Purpose |
|---------|---------|
| `/sync` | Sync with Gitea, pull latest, push local changes |
| `/checkpoint` | Git commit + database context snapshot |
| `/save` | Create comprehensive session log |
| `/context` | Search session logs and credentials for previous work |
| `/refresh-directives` | Re-read behavioral rules (do after sync) |

### First Thing Every Session

```
/sync
```

This pulls latest changes from other machines and pushes your local changes.

---

## Step 5: ASCII Markers (NO EMOJIS!)

**Never use emojis.** They cause encoding issues across platforms.

Use these instead:

| Marker | Use For |
|--------|---------|
| `[OK]` | Success, completed |
| `[SUCCESS]` | Task completed successfully |
| `[ERROR]` | Failure, problem |
| `[WARNING]` | Caution, potential issue |
| `[INFO]` | Informational message |
| `[CRITICAL]` | Severe error |

**Bad:**
```
✓ Task completed!
⚠ Warning: check config
```

**Good:**
```
[OK] Task completed!
[WARNING] Check config
```

---

## Step 6: Local AI (Ollama)

Ollama runs locally for tasks that don't need Claude-level reasoning.

### When to Use Ollama

**Good for:**
- Bulk/repetitive tasks (summarizing 50 logs)
- Boilerplate code generation
- Data extraction/classification
- Draft content you'll review

**Bad for (use Claude):**
- Architectural decisions
- Security-sensitive code
- Multi-step planning
- Final production output

### How to Call Ollama

```bash
# Simple prompt
curl -s http://localhost:11434/api/generate \
  -d '{"model":"qwen3:14b","prompt":"Summarize: ...","stream":false}' \
  | jq -r '.response'

# Code tasks
curl -s http://localhost:11434/api/chat \
  -d '{"model":"codestral:22b","messages":[{"role":"user","content":"..."}],"stream":false}' \
  | jq -r '.message.content'
```

### Review Policy for Ollama Output

| Impact Level | Review Required | Examples |
|--------------|-----------------|----------|
| Critical | ALWAYS verify against source | Auth, security, encryption, DB migrations |
| High | Review for correctness | API logic, business rules, infra scripts |
| Medium | Skim for obvious errors | Internal docs, session summaries, boilerplate |
| Low | Trust without review | Classification, reformatting, placeholders |

---

## Step 7: GrepAI (Semantic Search)

GrepAI indexes the codebase for natural language search.

### When to Use GrepAI vs Grep

**Use GrepAI for:**
- "How does authentication work?"
- "Find implementations related to user sessions"
- Exploring unfamiliar code areas
- Context recovery from session logs

**Use regular Grep for:**
- Exact text matches
- Known function/class names
- Simple pattern matching

### Commands

```bash
# Search
grepai search "how does JWT auth work" --json

# Call graph tracing
grepai trace callers "get_db"
grepai trace callees "create_user"

# Start watcher (if not running)
grepai watch --background

# Restart watcher (if results seem stale)
grepai watch --stop && grepai watch --background
```

---

## Step 8: File Organization

### Where to Put Things

| Content Type | Location |
|--------------|----------|
| ClaudeTools API code | `api/`, `migrations/` |
| Client work | `clients/[client-name]/` |
| Project work | `projects/[project-name]/` |
| Session logs | `session-logs/` or project-specific `session-logs/` |
| Scripts | Project-specific `scripts/` folder |
| Machine specs | `.claude/machines/` |

### Key Files to Know

- `credentials.md` - All infrastructure credentials (NEVER ask user for these)
- `SESSION_STATE.md` - Project history
- `.claude/CLAUDE.md` - Main behavioral rules (auto-loaded)
- `.claude/CODING_GUIDELINES.md` - Coding standards
- `.claude/agents/*.md` - Agent definitions

---

## Step 9: Context Recovery

When the user references previous work:

1. **Use `/context` command** to search session logs
2. **Check `credentials.md`** for infrastructure details
3. **Search session-logs/** for recent work
4. **Never ask user** for info that's in these files

### Session Log Locations

```
session-logs/                    # General logs
projects/*/session-logs/         # Project-specific
clients/*/session-logs/          # Client-specific
```

---

## Step 10: Automatic Behaviors

These happen automatically - don't forget them:

1. **After UI changes** (HTML/CSS/JSX) -> Auto-invoke `/frontend-design`
2. **Complex problems** (3+ issues, rejection loops) -> Use Sequential Thinking MCP
3. **After code changes** -> Code Review Agent reviews (MANDATORY)
4. **Complex tasks** (>3 steps) -> Create todo list with TodoWrite

---

## Step 11: SSH Configuration

On Linux, use system OpenSSH:

```bash
# Standard SSH
ssh user@host

# Never use paramiko or other SSH libraries when system SSH works
```

---

## Step 12: Self-Check After Setup

Run `/sync` and verify:

- [ ] Git pull successful
- [ ] Latest session logs visible
- [ ] GrepAI watcher running (`pgrep -f "grepai watch"`)
- [ ] Ollama responding (`curl http://localhost:11434/api/tags`)
- [ ] Can read credentials.md
- [ ] Understand delegation model

---

## Quick Reference Card

```
IDENTITY:       Coordinator (not executor)
EMOJIS:         NEVER (use [OK], [ERROR], etc.)
DATABASE:       Always delegate to Database Agent
CODE:           Always delegate to Coding Agent
FIRST COMMAND:  /sync
CONTEXT:        Check credentials.md and session-logs/
LOCAL AI:       Ollama for bulk tasks, review output
SEARCH:         GrepAI for intent, Grep for exact text
```

---

## Other Machines in This Environment

Check `.claude/machines/` for specs on:
- `mikes-macbook-air.md` - M4 MacBook Air (this doc was created there)
- (Add your machine spec after setup)

---

## Troubleshooting

### GrepAI Not Working
```bash
grepai watch --stop
grepai watch --background
```

### Ollama Not Responding
```bash
sudo systemctl status ollama
sudo systemctl restart ollama
```

### Git Push Rejected
```bash
git pull origin main --rebase
git push origin main
```

### Permission Issues
```bash
sudo chown -R $USER:$USER ~/ClaudeTools
```

---

## First Task After Reading This

1. Run `/sync` to pull latest
2. Run `/refresh-directives` to internalize rules
3. Create your machine spec file in `.claude/machines/`
4. You're ready to work!

---

**Created:** 2026-03-20
**Created By:** Claude on Mikes-MacBook-Air.local
**Purpose:** Help fresh Linux installs understand ClaudeTools behavioral expectations