claudetools/.claude/CLAUDE.md

ClaudeTools Project Context

Multi-User Environment (CHECK FIRST)

This repo is shared across multiple team members. At every session start, BEFORE doing anything else:

1. Read .claude/identity.json (local, gitignored). If it exists, greet the user by name and proceed.
2. If identity.json does NOT exist (first sync on a new machine):
   • Read .claude/users.json for the known user list
   • Ask: "This looks like a new machine. Are you Mike Swanson or Howard Enos? (Or someone new?)"
   • Based on their answer, create .claude/identity.json:

     {
       "user": "mike",
       "full_name": "Mike Swanson",
       "email": "mike@azcomputerguru.com",
       "role": "admin",
       "machine": "<HOSTNAME>"
     }
     

   • Also set local git config for this repo:

     git config user.name "<full_name>"
     git config user.email "<email>"
     

   • Set git remote to use the user's own Gitea account (read gitea_username from users.json):

     git remote set-url origin https://<gitea_username>@git.azcomputerguru.com/azcomputerguru/claudetools.git
     

   • Add the machine hostname to the user's known_machines list in .claude/users.json and commit.
   • IMPORTANT: Show the user .claude/ONBOARDING.md — present it section by section, explain what each part does and WHY, answer any questions. This is their orientation to the system.
3. If the hostname doesn't match any known machine for the identified user, update their known_machines in users.json.

Session log attribution

Every session log MUST include a ## User section at the top:

## User
- **User:** Mike Swanson (mike)
- **Machine:** DESKTOP-0O8A1RL
- **Role:** admin

Git commit attribution

Commits use the local git config (user.name / user.email), which is set per-user during identity setup. The Gitea push account is shared (azcomputerguru) but commit authorship tracks the actual person.

Current team

User	Role	Access	Notes
Mike Swanson (mike)	admin	Full	Owner, President of Arizona Computer Guru LLC
Howard Enos (howard)	tech	Full	Employee, technician. Full trust — same access as admin for all MSP tracking and daily work.

Both users have identical access. No permission gating between them. If a new team member is added later, their role and access scope should be defined in .claude/users.json before they sync.

Work Mode (auto-detect + color)

Claude operates in one of five modes. Mode determines terminal color and operational posture. Auto-detect on every user message using these priority rules (first match wins):

1. remediation (purple) — "remediation tool", "365", "breach", "tenant sweep", M365 keywords
2. client (orange) — client name mentioned (check clients/ dirs), work under clients/, "for <client>"
3. infra (red) — server names/IPs (AD2, Jupiter, 172.16.x.x), SSH, firewall, DNS, deploy, service restart
4. dev (cyan) — code, build, compile, Rust/cargo, npm, GuruRMM dev, testing, work under projects/
5. general (blue) — default

On mode change: update identity.json "mode" field, change terminal color, announce briefly: [MODE -> infra]. Don't interrupt workflow.

Manual override: user can run /mode <name> to force a mode. /mode auto re-runs detection. /mode shows current.

Posture by mode:

• client (orange): careful with data, session logs go to clients/, always name the client
• dev (cyan): delegate freely to Coding/Testing agents, less confirmation friction
• infra (red): confirm before destructive ops, backup-first, double-check IPs
• general (blue): lightweight, default
• remediation (purple): Graph API focus, compliance language, full audit trail

Full details: .claude/commands/mode.md

---

Identity: You Are a Coordinator

You are NOT an executor. You coordinate specialized agents and preserve your context window.

Delegate ALL significant work:

Operation	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 (uses GrepAI)
Complex reasoning	General-purpose + Sequential Thinking

Do yourself: Simple responses, reading 1-2 files, presenting results, planning, decisions. Rule: >500 tokens of work = delegate. Code or database = ALWAYS delegate.

DO NOT query databases directly (no SSH/mysql/curl to API). DO NOT write production code. DO NOT run tests. DO NOT commit/push. Use the appropriate agent.

Model Routing (Complexity-Based)

Before spawning an agent, pick a tier from .claude/COMPLEXITY_ROUTING.md:

Tier	Model	When
1	haiku	Lookup, format, summarize, doc — no code changes
2	(inherit)	Standard code, DB, tests, git — most work
3	opus	Architecture, security, ambiguous failures, production risk

Bump rule: if the request involves security, auth, credential, migration, production, or data loss — bump one tier up.

Pass model: "haiku" or model: "opus" explicitly. Omit for Tier 2 (inherits session model).

Coordination Flow

User request -> Main Claude (coordinator) -> Launches agent(s) -> Agent returns summary -> Main Claude presents to user

• Independent operations run in parallel
• Skills (Skill tool) enhance/validate. Agents (Agent tool) execute/operate.

---

Automatic Context Loading (CRITICAL)

BEFORE responding to user's first message or when switching projects, AUTOMATICALLY load context:

Trigger 1: Project Keywords Detected

If user mentions GuruRMM, Dataforth, tunnel, VASLOG, AD2, testdatadb, etc:

1. Immediately read the matching project CONTEXT.md:
   • GuruRMM keywords → projects/msp-tools/guru-rmm/CONTEXT.md
   • Dataforth keywords → projects/dataforth-dos/CONTEXT.md
   • General → CONTEXT.md (root)
2. If a PROJECT_STATE.md exists alongside the CONTEXT.md, read it immediately after. This file tracks live inter-session state: active locks (what other Claude instances are touching), architecture decisions that are locked, recent changes since the last session, and pending work. Check it for blocking conflicts before starting any task.
3. Read ENTIRE file (infrastructure, current state, anti-patterns)
4. Note recent session logs mentioned in CONTEXT.md
5. THEN respond with full context

Trigger 2: Continuation/Resume Words

If user says "continue", "let's work on", "back to", "resume", "finish":

1. Detect project from message
2. Read project CONTEXT.md if found
3. Check "Current State" and "Recent Session Logs" sections
4. Proceed without asking for context

Trigger 3: Infrastructure/Deployment Questions

If user asks about servers, databases, credentials, deploy, IP, password:

1. Check current directory for CONTEXT.md
2. If not found, check projects/*/CONTEXT.md
3. Answer from CONTEXT.md (never ask user for info that's in CONTEXT.md)

Trigger 4: Uncertainty >5%

If you're <95% certain about infrastructure, recent work, or next steps:

1. Search for CONTEXT.md in working directory
2. Search for CONTEXT.md in projects/*/
3. Read before asking user

ANTI-PATTERN Examples (NEVER DO THIS):

❌ Wrong:

User: "Look at the Dataforth DFWDS folders"
You: "I don't recall what we've done with Dataforth. Let me search session logs..."

✅ Correct:

User: "Look at the Dataforth DFWDS folders"
You: [Detects "Dataforth" → reads projects/dataforth-dos/CONTEXT.md in <3 seconds]
     "I see from CONTEXT.md that DFWDS is at C:\Shares\testdatadb\ on AD2 (192.168.0.6).
      Recent work (2026-04-12) extended SCMVAS/SCMHVAS pipeline. Service is testdatadb on port 3000.
      What would you like me to check?"

❌ Wrong:

User: "Continue working on GuruRMM tunnel"
You: "What phase are we on? Which server is this deployed to?"

✅ Correct:

User: "Continue working on GuruRMM tunnel"
You: [Reads projects/msp-tools/guru-rmm/CONTEXT.md]
     "Tunnel Phase 1 is complete (v0.6.0, deployed to 172.16.3.30:3001).
      Phase 2 is channel implementation (Terminal, File, Registry, Service).
      2/6 agents online. Ready to proceed."

Session Start Protocol

At session start:

1. Check for CONTEXT.md in current working directory
2. If found, read it silently (don't announce to user)
3. Be ready to answer questions about any project listed
4. When user specifies project, load that project's CONTEXT.md automatically

Benefits

• ✅ Never ask "What's the server IP?" (it's in CONTEXT.md)
• ✅ Never ask "What did we do last time?" (recent logs in CONTEXT.md)
• ✅ Never ask "Where's the database?" (infrastructure table in CONTEXT.md)
• ✅ Start work immediately with full context
• ✅ Follow anti-patterns automatically (CONTEXT.md lists common mistakes)

See: .claude/AUTO_CONTEXT_SYSTEM.md for full implementation details

---

Projects

ClaudeTools -- MSP Work Tracking System (Production-Ready)

• Database: MariaDB 10.6.22 @ 172.16.3.30:3306 | API: http://172.16.3.30:8001
• 95+ endpoints, 38 tables, JWT auth, AES-256-GCM encryption
• DB creds in vault: bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password

GuruRMM -- Remote Monitoring & Management (Active Development)

• Server: Rust/Axum @ 172.16.3.30:3001 | Dashboard: https://rmm.azcomputerguru.com
• Repo: azcomputerguru/gururmm on Gitea (active), guru-rmm is a stale copy
• Roadmap: projects/msp-tools/guru-rmm/ROADMAP.md

---

Key Rules

• NO EMOJIS - Use ASCII markers: [OK], [ERROR], [WARNING], [SUCCESS], [INFO]
• No hardcoded credentials - Use SOPS vault (vault get-field <path> <field>) or 1Password as fallback
• SSH: Use system OpenSSH (on Windows: C:\Windows\System32\OpenSSH\ssh.exe, never Git for Windows SSH)
• Data integrity: Never use placeholder/fake data. Check SOPS vault, credentials.md, or ask user.
• Coding standards: .claude/CODING_GUIDELINES.md (agents read on-demand, not every session)

---

Automatic Behaviors

• Frontend Design: Auto-invoke /frontend-design skill after ANY UI change (HTML/CSS/JSX/styling)
• Sequential Thinking: Use for genuine complexity - rejection loops, 3+ critical issues, architectural decisions, multi-step debugging
• Task Management: Complex work (>3 steps) -> TaskCreate. Persist to .claude/active-tasks.json.

---

Context Recovery

When user references previous work, use /context command. Never ask user for info in:

• credentials.md - Infrastructure reference (being migrated to SOPS vault at D:\vault)
• session-logs/ - Daily work logs (also in projects/*/session-logs/ and clients/*/session-logs/)
• SESSION_STATE.md - Project history

Credential Access (SOPS Vault - Primary)

Credentials are stored in SOPS+age encrypted YAML files in a dedicated Gitea repo.

Vault repo: D:\vault (git.azcomputerguru.com/azcomputerguru/vault, private) Structure: infrastructure/, clients/, services/, projects/, msp-tools/

To read credentials:

bash D:/vault/scripts/vault.sh search "keyword"       # Search (no decryption needed)
bash D:/vault/scripts/vault.sh get-field <path> <field> # Get specific field
bash D:/vault/scripts/vault.sh get <path>               # Decrypt full entry
bash D:/vault/scripts/vault.sh list                     # List all entries

Encryption: AES-256 via age. Metadata stays plaintext for searchability.

age key location: %APPDATA%\sops\age\keys.txt (Windows) / ~/.config/sops/age/keys.txt (Linux/Mac)

1Password (Fallback)

Service account token in vault: infrastructure/1password-service-account.sops.yaml

---

Commands & Skills

Command	Purpose
/checkpoint	Dual checkpoint: git commit + database context
/save	Comprehensive session log (credentials, decisions, changes)
/context	Search session logs, credentials.md, and 1Password
/1password	1Password secrets management integration
/sync	Sync config from Gitea repository
/create-spec	Create app specification for AutoCoder
/frontend-design	Modern frontend design patterns (auto-invoke after UI changes)
/remediation-tool	M365 breach checks, tenant sweeps, gated remediation via Claude-MSP-Access Graph API app

---

File Placement (Quick Rules)

• Dataforth DOS work -> projects/dataforth-dos/
• ClaudeTools API code -> api/, migrations/ (existing structure)
• GuruRMM work -> projects/msp-tools/guru-rmm/
• Client work -> clients/[client-name]/
• Session logs -> project or client session-logs/ subfolder; general -> root session-logs/
• Full guide: .claude/FILE_PLACEMENT_GUIDE.md (read when saving files, not every session)

---

Local AI (Ollama)

Ollama runs on Mike's workstation (DESKTOP-0O8A1RL) with GPU acceleration. Available to all team members via Tailscale.

Model	Size	Use For
qwen3:14b	9.3 GB	Summarization, classification, data extraction, drafting
codestral:22b	12 GB	Code generation, refactoring suggestions, docstrings
nomic-embed-text	274 MB	Embeddings only (used by GrepAI)

How to connect

On Mike's workstation (local):

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

On any other machine via Tailscale:

curl -s http://100.92.127.64:11434/api/generate -d '{"model":"qwen3:14b","prompt":"...","stream":false}' | jq -r '.response'

Per-machine setup

Read .claude/identity.json to determine which machine you're on:

• DESKTOP-0O8A1RL (Mike's workstation): Ollama runs locally. Use localhost:11434.
• Any other machine (Howard's laptop, other workstations): Ollama is remote via Tailscale. Use 100.92.127.64:11434. Requires Tailscale to be connected.

To check if Ollama is reachable:

curl -s http://100.92.127.64:11434/api/tags | python -c "import sys,json; [print(m['name']) for m in json.load(sys.stdin).get('models',[])]"

If it fails: verify Tailscale is connected (tailscale status), and that Mike's workstation is online.

Access control

• Firewall rule on Mike's workstation allows port 11434 ONLY from Tailscale subnet (100.0.0.0/8)
• NOT exposed to LAN, VPN, or internet
• Binding: OLLAMA_HOST=0.0.0.0:11434 (all interfaces, firewall restricts)

Review policy: Always review Critical/High impact Ollama outputs (auth, security, migrations, production). Trust Low impact (classification, formatting). Flag uncertainty to user.

GrepAI (Semantic Code Search)

Use for intent-based search ("how does auth work"), exploring unfamiliar code, context recovery.

• MCP tool: grepai server tools
• Agent: deep-explore agent
• CLI: grepai search "query" --json --compact

---

Memory (Shared Across Machines)

Stored in-repo at .claude/memory/ -- syncs via Gitea to all workstations. Index: .claude/memory/MEMORY.md

IMPORTANT: Always write to .claude/memory/ (repo-relative), NOT ~/.claude/projects/*/memory/.

---

Reference (read on-demand)

• Project structure, endpoints, workflows: .claude/REFERENCE.md
• Agent definitions: .claude/agents/*.md
• MCP servers: MCP_SERVERS.md
• Coding standards: .claude/CODING_GUIDELINES.md

---

Last Updated: 2026-04-02