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.

---

Project Overview

Type: MSP Work Tracking System | Status: Production-Ready (Phase 5 Complete) Database: MariaDB 10.6.22 @ 172.16.3.30:3306 | API: http://172.16.3.30:8001 Stats: 95+ endpoints, 38 tables, JWT auth, AES-256-GCM encryption

DB Connection: Host: 172.16.3.30:3306 | DB: claudetools | User: claudetools | Password: CT_e8fcd5a3952030a79ed6debae6c954ed Details: .claude/agents/DATABASE_CONNECTION_INFO.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.
• Full 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:

# Search by keyword (no decryption needed - metadata is plaintext)
bash D:/vault/scripts/vault.sh search "172.16.3.30"

# Get a specific field
bash D:/vault/scripts/vault.sh get-field infrastructure/gururmm-server.sops.yaml credentials.password

# Decrypt full entry
bash D:/vault/scripts/vault.sh get infrastructure/gururmm-server.sops.yaml

# List all entries
bash D:/vault/scripts/vault.sh list

Encryption: AES-256 via age. Metadata (kind, name, host, tags) stays plaintext for searchability. Only credentials, notes, and secret fields are encrypted.

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

Setup on new machines:

1. Install: winget install Mozilla.sops FiloSottile.age MikeFarah.yq (or brew/pacman)
2. Generate key: age-keygen -o ~/.config/sops/age/keys.txt
3. Clone: git clone git@git.azcomputerguru.com:azcomputerguru/vault.git
4. Add public key to keys/recipients.txt, push, then run vault rotate from existing machine

1Password (Fallback)

1Password remains available for browser autofill and as fallback. Service account token is in the vault: bash D:/vault/scripts/vault.sh get-field infrastructure/1password-service-account.sops.yaml credentials.token

---

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)
• 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. Use it for tasks that don't need Claude-level reasoning.

Available Models

Model	Size	Use For
qwen3:14b	9.3 GB	General sub-tasks: summarization, classification, data extraction, drafting
codestral:22b	12 GB	Code-specific sub-tasks: code generation, refactoring suggestions, docstring generation
nomic-embed-text	274 MB	Embeddings only (used by GrepAI, not for direct use)

GrepAI (Semantic Code Search)

GrepAI indexes the codebase using nomic-embed-text embeddings and provides semantic search via MCP server.

When to use GrepAI instead of Grep/Glob:

• Finding code by intent ("how does authentication work") rather than exact text
• Exploring unfamiliar areas of the codebase
• Finding related implementations across files
• Context recovery — searching session logs and credentials by meaning

How to use:

• MCP tool: Use the grepai MCP server tools directly (available after MCP loads)
• deep-explore agent: Delegate to the deep-explore agent for thorough semantic exploration
• CLI fallback: grepai search "your query" --json --compact

Maintenance: The watcher daemon runs in the background and auto-indexes file changes. If search results seem stale, run grepai watch --stop && grepai watch --background to restart it.

Using Ollama for Sub-Tasks

For bulk or repetitive work that doesn't require Claude's full reasoning, offload to local models via Ollama's API:

When to use Ollama:

• Processing many items in a loop (e.g., summarizing 50 session logs)
• Generating boilerplate or repetitive code patterns
• Data extraction/classification from structured text
• Draft content that Claude will review/refine
• Any task where speed > quality and results will be verified

When NOT to use Ollama (use Claude instead):

• Architectural decisions or complex reasoning
• Security-sensitive code review
• Tasks requiring tool use or multi-step planning
• Final output that goes directly to production

How to call Ollama:

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

# Chat format
curl -s http://localhost:11434/api/chat -d '{"model":"codestral:22b","messages":[{"role":"user","content":"Refactor this function: ..."}],"stream":false}' | jq -r '.message.content'

Ollama Output Review Policy

The coordinator (Claude) must review Ollama outputs based on impact level. Local models are useful but unreliable — they hallucinate, miss edge cases, and produce subtly wrong code.

Impact levels and review requirements:

Level	Review	Examples
Critical	ALWAYS review, verify against source	Code touching auth/security/encryption, credential handling, database migrations, production config, anything user-facing
High	Review for correctness, spot-check details	API endpoint logic, business rules, infrastructure scripts, client-specific work
Medium	Skim for obvious errors, trust if reasonable	Internal documentation drafts, session log summaries, data extraction from structured input, boilerplate code
Low	Trust without review	Classification/tagging of items, reformatting text, generating placeholder content for later editing

Review process for Critical/High:

1. Read Ollama's full output — don't just check if it "looks right"
2. Verify claims against actual files/data (e.g., if it says a function exists, confirm it does)
3. Check for: hallucinated function names, wrong parameter types, missing error handling, security gaps
4. If output is wrong or uncertain, redo the task yourself rather than patching Ollama's attempt

Batch processing pattern: When using Ollama for bulk tasks (e.g., processing N items), review the first 2-3 results fully before trusting the rest. If any are wrong, switch to doing it yourself or fix the prompt and reprocess.

Flag to user: If Ollama produces output for a Critical task and you are not confident in your review, tell the user explicitly: "This was generated by a local model and I'm not fully confident in [specific concern]."

---

Memory (Shared Across Machines)

Claude Code's auto-memory is stored in-repo at .claude/memory/ so it syncs via Gitea to all workstations.

IMPORTANT for all machines: Configure Claude Code to use the repo memory path, NOT the default ~/.claude/projects/ path. When the auto-memory system prompts you to write to ~/.claude/projects/-home-guru-ClaudeTools/memory/, write to .claude/memory/ (repo-relative) instead. The index file is .claude/memory/MEMORY.md.

This ensures memory created on one workstation (CachyOS, Mac, Windows) is available on all others after a git pull/sync.

---

Reference (read on-demand, not every session)

• Project structure, endpoints, workflows, troubleshooting: .claude/REFERENCE.md
• Agent definitions: .claude/agents/*.md
• MCP servers: MCP_SERVERS.md
• Coding standards: .claude/CODING_GUIDELINES.md
• Shared memory: .claude/memory/MEMORY.md (index) + .claude/memory/*.md (individual memories)

---

Last Updated: 2026-03-22