claudetools/.claude/CLAUDE.md

ClaudeTools Project Context

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.

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.

---

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)

---

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 locally with GPU acceleration for tasks that don't need Claude-level reasoning.

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)

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

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