9.2 KiB
9.2 KiB
ClaudeTools - Project Context
Last Updated: 2026-04-14 Status: Active - Production Stable
Quick Start - Infrastructure Overview
| Component | Location | Access | Notes |
|---|---|---|---|
| Production API | http://172.16.3.30:8001 | Public access | ClaudeTools work tracking API |
| Production DB | MariaDB @ 172.16.3.30:3306/claudetools | Vault credentials | 38 tables, AES-256-GCM encryption |
| Vault (SOPS) | D:\vault\ | age-encrypted YAML | Primary credential store |
| 1Password | Service account | Fallback | op://Projects/ClaudeTools * |
| Gitea Repo | git.azcomputerguru.com/azcomputerguru/claudetools | Active development | Main codebase |
Get DB credentials:
bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password
Current State (READ THIS FIRST)
Project Status
- API: 95+ endpoints, production-stable
- Database: 38 tables, fully encrypted sensitive fields
- Authentication: JWT-based, AES-256-GCM for API keys
- Deployment: Auto-deploy via Gitea webhooks (planned)
Active Subprojects
- GuruRMM - Remote monitoring system (see projects/msp-tools/guru-rmm/CONTEXT.md)
- Dataforth DOS - Test datasheet pipeline (see projects/dataforth-dos/CONTEXT.md)
Session Logs
- Project-specific: projects/*/session-logs/
- Client work: clients/*/session-logs/
- General: session-logs/ (root)
Anti-Patterns (DON'T DO THIS)
❌ DO NOT query database directly - Use Database Agent for ALL operations
❌ DO NOT write production code yourself - Delegate to Coding Agent, coordinate as needed
❌ DO NOT use emojis - ASCII markers only: [OK], [ERROR], [WARNING], [SUCCESS], [INFO]
❌ DO NOT hardcode credentials - Always use SOPS vault (primary) or 1Password (fallback)
❌ DO NOT skip Code Review Agent - MANDATORY after any code changes
❌ DO NOT execute >500 token operations directly - Delegate to appropriate agent
Where to Find Things
Repository Structure
ClaudeTools/
├── .claude/
│ ├── CLAUDE.md # Project instructions (directives)
│ ├── REFERENCE.md # Technical reference
│ ├── CODING_GUIDELINES.md # Code standards
│ ├── FILE_PLACEMENT_GUIDE.md # Where to save files
│ ├── agents/ # Agent definitions
│ └── memory/ # Persistent facts (syncs via Git)
├── credentials.md # Infrastructure reference (migrating to vault)
├── session-logs/ # General session logs
├── projects/
│ ├── msp-tools/guru-rmm/ # GuruRMM (CONTEXT.md there)
│ ├── dataforth-dos/ # Dataforth (CONTEXT.md there)
│ └── claudetools-api/ # API codebase (legacy)
├── clients/
│ └── [client-name]/ # Client-specific work
└── D:\vault\ # SOPS encrypted credentials (separate repo)
Credential Locations
Primary: SOPS Vault (D:\vault)
# Search for keywords (no decryption needed)
bash D:/vault/scripts/vault.sh search "claudetools"
# Get specific field
bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password
# List all entries
bash D:/vault/scripts/vault.sh list
Structure:
- infrastructure/ - Servers, network gear
- clients/ - Client-specific credentials
- services/ - External services (GitHub, APIs)
- projects/ - Project databases, APIs
- msp-tools/ - MSP application credentials
Fallback: 1Password
# ClaudeTools database credentials
op read "op://Projects/ClaudeTools Database/password"
# ClaudeTools API auth
op read "op://Projects/ClaudeTools API Auth/credential"
Common Operations
Start Work on Subproject
User: "Let's work on GuruRMM tunnel Phase 2"
Claude should:
1. Read projects/msp-tools/guru-rmm/CONTEXT.md (this file)
2. Check recent session logs referenced in CONTEXT.md
3. Understand current state, infrastructure, anti-patterns
4. Proceed without asking user for context
DO NOT:
- Ask user "what's the server IP?"
- Ask user "where is the database?"
- Ask user "what credentials should I use?"
All of this is in CONTEXT.md
Database Operations
# WRONG: Direct query
ssh user@172.16.3.30 "mysql -u claudetools -p claudetools -e 'SELECT * FROM ...'"
# RIGHT: Delegate to Database Agent
"Use Database Agent to query work_logs table for entries from last 7 days"
Deploy Code Changes
# WRONG: Deploy yourself
scp file.js user@172.16.3.30:/path/
# RIGHT: Follow project deployment process
# (See project-specific CONTEXT.md for deployment steps)
Project-Specific Context Files
When user says "work on [project]", read that project's CONTEXT.md FIRST:
| Project | CONTEXT.md Location | What It Contains |
|---|---|---|
| GuruRMM | projects/msp-tools/guru-rmm/CONTEXT.md | Server IPs, deployment, tunnel architecture, agent status |
| Dataforth DOS | projects/dataforth-dos/CONTEXT.md | AD2/AD1 infrastructure, testdatadb service, log formats |
| ClaudeTools API | (This file) | Main project overview, credential locations |
Coordination Rules (My Role)
I am a Coordinator, NOT an executor:
| Operation | Delegate To |
|---|---|
| Database queries/updates | Database Agent |
| Production code generation | Coding Agent |
| Code review (MANDATORY) | Code Review Agent |
| Test execution | Testing Agent |
| Git commit/push | Gitea Agent |
| Backups/restore | Backup Agent |
| File exploration | Explore Agent |
| Semantic code search | deep-explore Agent (GrepAI) |
| Complex reasoning | General-purpose + Sequential Thinking |
I do myself: Simple responses, reading 1-2 files, presenting results, planning, decisions
Rule: >500 tokens of work = delegate
Memory System
Location: .claude/memory/ (syncs across machines via Git)
Structure:
- MEMORY.md - Index of all facts
- [topic]-context.md - Topic-specific persistent facts
IMPORTANT: Always write to .claude/memory/ (repo-relative), NOT ~/.claude/projects/*/memory/
Session Log Locations
Follow these rules:
| Work Type | Save To |
|---|---|
| Dataforth DOS work | projects/dataforth-dos/session-logs/ |
| ClaudeTools API code | projects/claudetools-api/session-logs/ |
| GuruRMM work | projects/msp-tools/guru-rmm/session-logs/ |
| Client work | clients/[client-name]/session-logs/ |
| General/mixed work | session-logs/ (root) |
See: .claude/FILE_PLACEMENT_GUIDE.md for full rules
Auto-Invoke Skills
Frontend Design: Auto-invoke /frontend-design skill after ANY UI change (HTML/CSS/JSX/styling)
Sequential Thinking: Use for genuine complexity only:
- Rejection loops (3+ failed attempts)
- Critical architectural decisions
- Multi-step debugging with unclear root cause
- NOT for every task
Key Commands
| Command | Purpose | When |
|---|---|---|
/checkpoint |
Git commit + database context save | After code changes |
/save |
Comprehensive session log | End of session |
/context |
Search session logs + credentials | User references previous work |
/1password |
1Password operations | Manage secrets |
/sync |
Sync from Gitea | Update local config |
/refresh-directives |
Re-read CLAUDE.md | After summarization, large tasks |
Reference Documents (Read On-Demand)
- Project instructions: .claude/CLAUDE.md (my role, agent delegation rules)
- Technical reference: .claude/REFERENCE.md (endpoints, database, workflows)
- Coding standards: .claude/CODING_GUIDELINES.md (agents read, not every session)
- File placement: .claude/FILE_PLACEMENT_GUIDE.md (where to save files)
- MCP servers: MCP_SERVERS.md (available integrations)
- Agent definitions: .claude/agents/*.md (agent capabilities)
Troubleshooting
"I don't know the database password"
- Check: D:\vault\ (SOPS encrypted)
- Command:
bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password - Fallback: credentials.md (has 1Password references)
"Where is the GuruRMM server?"
- Check: projects/msp-tools/guru-rmm/CONTEXT.md
- Answer: 172.16.3.30 (listed in first table)
"How do I deploy Dataforth changes?"
- Check: projects/dataforth-dos/CONTEXT.md
- Section: "Common Operations → Deploy Code to AD2"
"I forgot my role as Coordinator"
- Read: .claude/CLAUDE.md
- Command:
/refresh-directives
Quick Links
- Credentials (vault): D:\vault\ (SOPS encrypted YAML)
- Credentials (legacy): credentials.md (migrating to vault)
- Gitea: http://172.16.3.20:3000/azcomputerguru/claudetools
- API Docs: http://172.16.3.30:8001/api/docs
When user says "work on [project]":
- Read [project]/CONTEXT.md FIRST (don't ask user for context)
- Check recent session logs mentioned in CONTEXT.md
- Understand infrastructure, anti-patterns, current state
- Proceed with work
This eliminates:
- "What's the server IP?" → In CONTEXT.md
- "Where's the database?" → In CONTEXT.md
- "What credentials?" → In CONTEXT.md
- "What did we do last time?" → In session logs referenced by CONTEXT.md