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

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

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

# 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

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

# 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

grepai watch --stop
grepai watch --background

Ollama Not Responding

sudo systemctl status ollama
sudo systemctl restart ollama

Git Push Rejected

git pull origin main --rebase
git push origin main

Permission Issues

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