Add Linux PC onboarding guide for Claude Code
Comprehensive guide for fresh Linux installs to understand: - Coordinator identity and delegation model - NO EMOJIS rule and ASCII markers - Agent delegation patterns - Database/API/Gitea infrastructure - Ollama and GrepAI setup - Available commands (/sync, /context, etc.) - File organization and context recovery - Self-check verification steps Machine: Mikes-MacBook-Air.local Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
375
.claude/machines/LINUX_PC_ONBOARDING.md
Normal file
375
.claude/machines/LINUX_PC_ONBOARDING.md
Normal file
@@ -0,0 +1,375 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user