azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add gururmm one-time setup step to ONBOARDING

Browse Source 
Documents bash scripts/install-hooks.sh requirement after cloning gururmm.
Explains the sqlx migration checksum / CRLF root cause so the step makes
sense and doesn't get skipped.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-04-19 08:23:01 -07:00
parent cb300a193c
commit 9c820c16fa
1 changed files with 261 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

507
.claude/ONBOARDING.md
View File

@@ -1,246 +1,261 @@
# Welcome to ClaudeTools — Onboarding Guide # Welcome to ClaudeTools — Onboarding Guide
Hey! This guide explains how our Claude Code setup works, WHY it's built the way it is, and how to use it effectively for daily MSP work. Read this once, then use it as reference when something feels unfamiliar. Hey! This guide explains how our Claude Code setup works, WHY it's built the way it is, and how to use it effectively for daily MSP work. Read this once, then use it as reference when something feels unfamiliar.
--- ---
## What is this? ## What is this?
ClaudeTools is our shared workspace for **Claude Code** — the AI coding + automation assistant. It's a git repo that syncs across our workstations via Gitea (our self-hosted Git server). Everything Claude learns, every session log, every automation script, every project we build — it all lives here and stays in sync. ClaudeTools is our shared workspace for **Claude Code** — the AI coding + automation assistant. It's a git repo that syncs across our workstations via Gitea (our self-hosted Git server). Everything Claude learns, every session log, every automation script, every project we build — it all lives here and stays in sync.
**Why a repo instead of just using Claude directly?** **Why a repo instead of just using Claude directly?**
- Claude Code loses context between sessions. This repo IS the memory. - Claude Code loses context between sessions. This repo IS the memory.
- Session logs preserve what we did, what creds we used, what decisions we made. - Session logs preserve what we did, what creds we used, what decisions we made.
- CLAUDE.md tells Claude HOW to behave specifically for our org (not generic defaults). - CLAUDE.md tells Claude HOW to behave specifically for our org (not generic defaults).
- Skills and commands give us reusable shortcuts for common MSP tasks. - Skills and commands give us reusable shortcuts for common MSP tasks.
- The vault (separate repo) stores all credentials encrypted so Claude can access them without us typing passwords every session. - The vault (separate repo) stores all credentials encrypted so Claude can access them without us typing passwords every session.
--- ---
## First time setup ## First time setup
When you open Claude Code for the first time on a new machine, Claude will ask who you are. Just answer with your name. Claude then: When you open Claude Code for the first time on a new machine, Claude will ask who you are. Just answer with your name. Claude then:
1. Creates a local identity file (so it knows who's at the keyboard) 1. Creates a local identity file (so it knows who's at the keyboard)
2. Sets your git name/email for commits 2. Sets your git name/email for commits
3. Registers your machine in the shared users list 3. Registers your machine in the shared users list
After that, every session log and git commit is attributed to you. After that, every session log and git commit is attributed to you.
--- ### GuruRMM repo — one-time setup per machine
## The slash commands (most important daily tools) The GuruRMM repo (`projects/msp-tools/guru-rmm/`) requires one extra step after cloning or first use. Run this from the repo root:
Type these in Claude Code's prompt. They're shortcuts for common operations. ```bash
bash scripts/install-hooks.sh
| Command | What it does | When to use | ```
|---------|-------------|-------------|
| `/save` | Saves a comprehensive session log (what you did, creds used, decisions made) | **End of every significant work session.** This is how future-you (or future-me) recovers context. | This does three things permanently:
| `/sync` | Pull + push changes to/from Gitea | Start of session (get latest), end of session (push yours) | - Points git at `scripts/hooks/` so pre-commit checks run automatically (and stay current as hooks evolve — no re-install after updates)
| `/context` | Searches session logs and credentials for previous work | "What did we do for Dataforth last week?" or "What's the password for AD2?" | - Sets `core.autocrlf=false` and `core.eol=lf` for this repo (prevents sqlx migration checksum drift from Windows CRLF line endings)
| `/checkpoint` | Git commit + database context save | After completing a feature or fix | - Sets `core.autocrlf=false` globally on this machine
| `/scc` | Save + Commit + Push (all three in one shot) | Quick end-of-session wrap-up |
| `/1password` | Access secrets from 1Password | When vault doesn't have a credential | **Why this matters:** sqlx verifies migration files by sha384 hash. A file committed with CRLF line endings hashes differently than the same file with LF — the server sees the mismatch and refuses to start. The `.gitattributes` file handles new commits automatically; this command configures the git client for existing checkouts.
### Why these exist ---
Without `/save`, you'd lose everything when a session ends. Without `/sync`, your work stays on one machine. Without `/context`, you'd re-discover the same information every session. These three commands are 90% of daily usage. ## The slash commands (most important daily tools)
--- Type these in Claude Code's prompt. They're shortcuts for common operations.
## The SOPS vault (how credentials work) | Command | What it does | When to use |
|---------|-------------|-------------|
We store ALL credentials in an encrypted vault at `D:\vault\` (separate git repo). Files are YAML encrypted with age/SOPS. Claude can decrypt them on the fly. | `/save` | Saves a comprehensive session log (what you did, creds used, decisions made) | **End of every significant work session.** This is how future-you (or future-me) recovers context. |
| `/sync` | Pull + push changes to/from Gitea | Start of session (get latest), end of session (push yours) |
**How Claude accesses a credential:** | `/context` | Searches session logs and credentials for previous work | "What did we do for Dataforth last week?" or "What's the password for AD2?" |
```bash | `/checkpoint` | Git commit + database context save | After completing a feature or fix |
bash D:/vault/scripts/vault.sh get-field clients/dataforth/ad2.sops.yaml credentials.password | `/scc` | Save + Commit + Push (all three in one shot) | Quick end-of-session wrap-up |
``` | `/1password` | Access secrets from 1Password | When vault doesn't have a credential |
**Why this matters:** ### Why these exist
- We never hardcode passwords in scripts or session logs (they're vault references)
- The vault syncs across machines via Gitea (same as claudetools) Without `/save`, you'd lose everything when a session ends. Without `/sync`, your work stays on one machine. Without `/context`, you'd re-discover the same information every session. These three commands are 90% of daily usage.
- Encryption uses an age key at `%APPDATA%\sops\age\keys.txt` — this key needs to be on each machine that decrypts
---
**Your machine needs the age key.** Mike will give you the key file. Drop it at:
``` ## The SOPS vault (how credentials work)
C:\Users\<you>\AppData\Roaming\sops\age\keys.txt
``` We store ALL credentials in an encrypted vault at `D:\vault\` (separate git repo). Files are YAML encrypted with age/SOPS. Claude can decrypt them on the fly.
Without this file, vault commands fail. Everything else works fine. **How Claude accesses a credential:**
```bash
--- bash D:/vault/scripts/vault.sh get-field clients/dataforth/ad2.sops.yaml credentials.password
```
## How Claude knows about our infrastructure
**Why this matters:**
### CLAUDE.md (the brain) - We never hardcode passwords in scripts or session logs (they're vault references)
- The vault syncs across machines via Gitea (same as claudetools)
`.claude/CLAUDE.md` is the master instructions file. Claude reads it at the start of every session. It tells Claude: - Encryption uses an age key at `%APPDATA%\sops\age\keys.txt` — this key needs to be on each machine that decrypts
- **Who we are** (AZ Computer Guru, MSP) **Your machine needs the age key.** Mike will give you the key file. Drop it at:
- **How to behave** (delegate to agents, no emojis, use vault for creds) ```
- **What projects exist** (GuruRMM, Dataforth, ClaudeTools API) C:\Users\<you>\AppData\Roaming\sops\age\keys.txt
- **How to load context** automatically when you mention a project keyword ```
**Key behavior:** If you say "work on Dataforth", Claude automatically reads `projects/dataforth-dos/CONTEXT.md` before responding. Same for "GuruRMM" → reads `projects/msp-tools/guru-rmm/CONTEXT.md`. This means Claude starts every project conversation with full context — server IPs, current state, recent work, anti-patterns to avoid. Without this file, vault commands fail. Everything else works fine.
### CONTEXT.md files (per-project state) ---
Each major project has a `CONTEXT.md` that captures: ## How Claude knows about our infrastructure
- Server IPs, ports, credentials references
- Current deployment state ### CLAUDE.md (the brain)
- Recent session logs (what was done last)
- Anti-patterns (things NOT to do, learned from past mistakes) `.claude/CLAUDE.md` is the master instructions file. Claude reads it at the start of every session. It tells Claude:
- What to work on next
- **Who we are** (AZ Computer Guru, MSP)
These files are the **single source of truth** for "where are we on this project." - **How to behave** (delegate to agents, no emojis, use vault for creds)
- **What projects exist** (GuruRMM, Dataforth, ClaudeTools API)
### Session logs (the history) - **How to load context** automatically when you mention a project keyword
Every significant work session gets a log saved to `session-logs/` (root for general, or `projects/*/session-logs/` for project-specific). These include: **Key behavior:** If you say "work on Dataforth", Claude automatically reads `projects/dataforth-dos/CONTEXT.md` before responding. Same for "GuruRMM" → reads `projects/msp-tools/guru-rmm/CONTEXT.md`. This means Claude starts every project conversation with full context — server IPs, current state, recent work, anti-patterns to avoid.
- What was accomplished
- Full credentials used (unredacted — needed for future sessions) ### CONTEXT.md files (per-project state)
- Infrastructure changes made
- Commands that worked and errors that didn't Each major project has a `CONTEXT.md` that captures:
- What's still pending - Server IPs, ports, credentials references
- Current deployment state
**This is why `/save` matters.** Without it, the next person (or the next Claude session) starts from scratch. - Recent session logs (what was done last)
- Anti-patterns (things NOT to do, learned from past mistakes)
--- - What to work on next
## Skills (auto-invoked behaviors) These files are the **single source of truth** for "where are we on this project."
Skills are more powerful than commands — some trigger automatically. ### Session logs (the history)
| Skill | Auto-invokes? | What it does | Every significant work session gets a log saved to `session-logs/` (root for general, or `projects/*/session-logs/` for project-specific). These include:
|-------|--------------|-------------| - What was accomplished
| `frontend-design` | YES — after any UI change | Validates visual correctness, accessibility, design quality | - Full credentials used (unredacted — needed for future sessions)
| `stop-slop` | YES — always active | Prevents generic/lazy AI output. Enforces quality. | - Infrastructure changes made
| `remediation-tool` | When you say "remediation tool" or "365" | M365 tenant investigation via our Graph API app | - Commands that worked and errors that didn't
| `skill-creator` | On request | Helps build new custom skills | - What's still pending
| `theme-factory` | On request | Apply visual themes to HTML artifacts |
**This is why `/save` matters.** Without it, the next person (or the next Claude session) starts from scratch.
### Why "stop-slop" exists
---
Without it, Claude defaults to generic patterns (purple gradients, Inter font, emoji-heavy prose). Our `stop-slop` skill enforces our standards: ASCII markers instead of emojis, specific rather than vague, no filler phrases.
## Skills (auto-invoked behaviors)
---
Skills are more powerful than commands — some trigger automatically.
## Agents (specialized workers)
| Skill | Auto-invokes? | What it does |
Claude Code can spawn sub-agents for specific tasks. These are defined in `.claude/agents/`. The main ones you'll encounter: |-------|--------------|-------------|
| `frontend-design` | YES — after any UI change | Validates visual correctness, accessibility, design quality |
| Agent | What it does | When Claude uses it | | `stop-slop` | YES — always active | Prevents generic/lazy AI output. Enforces quality. |
|-------|-------------|-------------------| | `remediation-tool` | When you say "remediation tool" or "365" | M365 tenant investigation via our Graph API app |
| **Database Agent** | Runs SQL queries on our databases | Any database operation — Claude should NEVER query directly | | `skill-creator` | On request | Helps build new custom skills |
| **Code Review Agent** | Reviews code changes for quality/security | After any code modification | | `theme-factory` | On request | Apply visual themes to HTML artifacts |
| **Coding Agent** | Writes production code | When Claude needs to generate code (not just edit) |
| **Explore Agent** | Searches codebases quickly | When looking for files, patterns, or understanding code | ### Why "stop-slop" exists
| **Gitea Agent** | Git commits, pushes, branch operations | Commit workflow |
| **Backup Agent** | Backup operations | Before destructive changes | Without it, Claude defaults to generic patterns (purple gradients, Inter font, emoji-heavy prose). Our `stop-slop` skill enforces our standards: ASCII markers instead of emojis, specific rather than vague, no filler phrases.
**Why agents?** Claude has a limited context window. If it does everything itself, it runs out of memory mid-conversation. Agents handle heavy work in isolation and return just the summary. Also: separation of concerns — the Code Review Agent can independently evaluate code the Coding Agent wrote. ---
--- ## Agents (specialized workers)
## Local AI tools (when available) Claude Code can spawn sub-agents for specific tasks. These are defined in `.claude/agents/`. The main ones you'll encounter:
### Ollama (local LLM) | Agent | What it does | When Claude uses it |
|-------|-------------|-------------------|
Ollama runs AI models locally on your GPU. Used for tasks that don't need Claude's full reasoning power — summarization, classification, data extraction. | **Database Agent** | Runs SQL queries on our databases | Any database operation — Claude should NEVER query directly |
| **Code Review Agent** | Reviews code changes for quality/security | After any code modification |
**Models we use:** | **Coding Agent** | Writes production code | When Claude needs to generate code (not just edit) |
- `qwen3:14b` — general purpose (summarization, drafting) | **Explore Agent** | Searches codebases quickly | When looking for files, patterns, or understanding code |
- `codestral:22b` — code generation assistance | **Gitea Agent** | Git commits, pushes, branch operations | Commit workflow |
- `nomic-embed-text` — embeddings for semantic search | **Backup Agent** | Backup operations | Before destructive changes |
**Ollama runs on Mike's workstation** and is shared via Tailscale. You don't need to install it locally. **Why agents?** Claude has a limited context window. If it does everything itself, it runs out of memory mid-conversation. Agents handle heavy work in isolation and return just the summary. Also: separation of concerns — the Code Review Agent can independently evaluate code the Coding Agent wrote.
**To use from your machine (Tailscale must be connected):** ---
```bash
curl -s http://100.92.127.64:11434/api/tags ## Local AI tools (when available)
```
### Ollama (local LLM)
If that returns models, you're connected. Claude automatically uses the right URL based on which machine you're on (reads from `identity.json`).
Ollama runs AI models locally on your GPU. Used for tasks that don't need Claude's full reasoning power — summarization, classification, data extraction.
If it fails: check that Tailscale is connected (`tailscale status`) and Mike's workstation is online.
**Models we use:**
### GrepAI (semantic code search) - `qwen3:14b` — general purpose (summarization, drafting)
- `codestral:22b` — code generation assistance
Searches code by MEANING rather than exact text. "How does auth work?" finds authentication code even if the word "auth" doesn't appear. - `nomic-embed-text` — embeddings for semantic search
**Status:** Requires setup per-machine (index build). The `deep-explore` agent uses it. If it's not installed, Claude uses regular grep (still works, just less smart). **Ollama runs on Mike's workstation** and is shared via Tailscale. You don't need to install it locally.
--- **To use from your machine (Tailscale must be connected):**
```bash
## Project structure curl -s http://100.92.127.64:11434/api/tags
```
```
D:\claudetools\ If that returns models, you're connected. Claude automatically uses the right URL based on which machine you're on (reads from `identity.json`).
.claude/ — Claude's brain (CLAUDE.md, agents, skills, memory, commands)
session-logs/ — General work logs If it fails: check that Tailscale is connected (`tailscale status`) and Mike's workstation is online.
projects/
dataforth-dos/ — Dataforth test datasheet pipeline (AD2, testdatadb) ### GrepAI (semantic code search)
msp-tools/
guru-rmm/ — GuruRMM agent + server (Rust, our product) Searches code by MEANING rather than exact text. "How does auth work?" finds authentication code even if the word "auth" doesn't appear.
newsletter/ — Marketing newsletters
clients/ **Status:** Requires setup per-machine (index build). The `deep-explore` agent uses it. If it's not installed, Claude uses regular grep (still works, just less smart).
dataforth/ — Dataforth-specific client docs
pavon/ — Pavon/client docs ---
... — Other clients
credentials.md — Quick-reference credentials (vault is source of truth) ## Project structure
CONTEXT.md — Root-level project context
```
D:\vault\ — SOPS-encrypted credentials (separate repo) D:\claudetools\
infrastructure/ — Our servers (Jupiter, Uranus, pfSense, etc.) .claude/ — Claude's brain (CLAUDE.md, agents, skills, memory, commands)
clients/ — Client credentials session-logs/ — General work logs
services/ — Service credentials (Cloudflare, Azure, Gitea, etc.) projects/
projects/ — Project-specific secrets dataforth-dos/ — Dataforth test datasheet pipeline (AD2, testdatadb)
``` msp-tools/
guru-rmm/ — GuruRMM agent + server (Rust, our product)
--- newsletter/ — Marketing newsletters
clients/
## Daily workflow dataforth/ — Dataforth-specific client docs
pavon/ — Pavon/client docs
### Starting a work session ... — Other clients
1. Open Claude Code in the project directory credentials.md — Quick-reference credentials (vault is source of truth)
2. Claude greets you by name (reads identity.json) CONTEXT.md — Root-level project context
3. Tell Claude what you're working on — it auto-loads the right context
4. Work normally — ask questions, make changes, run commands D:\vault\ — SOPS-encrypted credentials (separate repo)
infrastructure/ — Our servers (Jupiter, Uranus, pfSense, etc.)
### Ending a work session clients/ — Client credentials
1. `/save` — creates the session log (DO THIS EVERY TIME) services/ — Service credentials (Cloudflare, Azure, Gitea, etc.)
2. `/sync` — pushes everything to Gitea projects/ — Project-specific secrets
3. Close Claude Code ```
### When switching projects mid-session ---
Just say "let's work on GuruRMM" or "switch to Dataforth" — Claude reads the relevant CONTEXT.md and picks up where the last session left off.
## Daily workflow
---
### Starting a work session
## Things to know 1. Open Claude Code in the project directory
2. Claude greets you by name (reads identity.json)
**Claude remembers across sessions** — via session logs and memory files, not magic. If you don't `/save`, the next session starts cold. 3. Tell Claude what you're working on — it auto-loads the right context
4. Work normally — ask questions, make changes, run commands
**Credentials are in the vault** — don't ask Mike for passwords; ask Claude. It decrypts from the vault.
### Ending a work session
**Git commits are attributed to YOU** — your name and email appear on every commit from your machine. 1. `/save` — creates the session log (DO THIS EVERY TIME)
2. `/sync` — pushes everything to Gitea
**Production deployments need care** — Claude will warn before destructive operations (git push --force, database drops, service restarts). Read the warnings. 3. Close Claude Code
**If Claude seems confused about a project** — say `/context` and ask it to search for recent work. Or read the project's CONTEXT.md yourself. ### When switching projects mid-session
Just say "let's work on GuruRMM" or "switch to Dataforth" — Claude reads the relevant CONTEXT.md and picks up where the last session left off.
**If something breaks** — session logs have the full history. `git log` shows what changed and who changed it. Gitea keeps everything.
---
---
## Things to know
## Getting help
**Claude remembers across sessions** — via session logs and memory files, not magic. If you don't `/save`, the next session starts cold.
- Ask Claude: "What commands do I have?" or "How do I access credentials?"
- Read `.claude/CLAUDE.md` for the full rulebook **Credentials are in the vault** — don't ask Mike for passwords; ask Claude. It decrypts from the vault.
- Check `session-logs/` for recent work examples
- Ask Mike **Git commits are attributed to YOU** — your name and email appear on every commit from your machine.
--- **Production deployments need care** — Claude will warn before destructive operations (git push --force, database drops, service restarts). Read the warnings.
*Last updated: 2026-04-16* **If Claude seems confused about a project** — say `/context` and ask it to search for recent work. Or read the project's CONTEXT.md yourself.
**If something breaks** — session logs have the full history. `git log` shows what changed and who changed it. Gitea keeps everything.
---
## Getting help
- Ask Claude: "What commands do I have?" or "How do I access credentials?"
- Read `.claude/CLAUDE.md` for the full rulebook
- Check `session-logs/` for recent work examples
- Ask Mike
---
*Last updated: 2026-04-16*