claudetools/.claude/ONBOARDING.md

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.

---

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.

Why a repo instead of just using Claude directly?

• 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.
• 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.
• The vault (separate repo) stores all credentials encrypted so Claude can access them without us typing passwords every session.

---

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:

1. Creates a local identity file (so it knows who's at the keyboard)
2. Sets your git name/email for commits
3. Registers your machine in the shared users list

After that, every session log and git commit is attributed to you.

Machine-local configuration

Some configuration files are machine-local (gitignored, not synced) because they contain machine-specific paths or settings:

File	Purpose	Auto-created?
.claude/identity.json	Your name, email, vault path	YES — during onboarding
.claude/current-mode	Work mode (dev, infra, client, etc.)	YES — defaults to "general"

.claude/current-mode is used by coordination hooks to determine behavior:

• In dev mode: Hooks show active locks as warnings but don't block
• In other modes: Hooks enforce coordination protocol more strictly

You never need to manually create this file — the UserPromptSubmit hook initializes it automatically on first run. Claude updates it when switching modes (e.g., when you say "work on Dataforth" switches to client mode).

GuruRMM repo — one-time setup per machine

The GuruRMM repo (projects/msp-tools/guru-rmm/) requires one extra step after cloning or first use. Run this from the repo root:

bash scripts/install-hooks.sh

This does three things permanently:

• Points git at scripts/hooks/ so pre-commit checks run automatically (and stay current as hooks evolve — no re-install after updates)
• Sets core.autocrlf=false and core.eol=lf for this repo (prevents sqlx migration checksum drift from Windows CRLF line endings)
• Sets core.autocrlf=false globally on this machine

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.

---

The slash commands (most important daily tools)

Type these in Claude Code's prompt. They're shortcuts for common operations.

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.
/sync	Pull + push changes to/from Gitea	Start of session (get latest), end of session (push yours)
/context	Searches session logs and credentials for previous work	"What did we do for Dataforth last week?" or "What's the password for AD2?"
/checkpoint	Git commit + database context save	After completing a feature or fix
/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 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 SOPS vault (how credentials work)

We store ALL credentials in an encrypted vault (separate git repo). Files are YAML encrypted with age/SOPS. Claude can decrypt them on the fly.

How Claude accesses a credential:

# Always via the ClaudeTools wrapper — never a hardcoded path
bash "$CLAUDETOOLS_ROOT/.claude/scripts/vault.sh" get-field clients/dataforth/ad2.sops.yaml credentials.password

Why this matters:

• We never hardcode passwords in scripts or session logs (they're vault references)
• The vault syncs across machines via Gitea (same as claudetools)
• Encryption uses an age key — this key needs to be on each machine that decrypts

Setup required on each machine:

1. Clone the vault repo somewhere convenient (e.g., ~/vault on Mac/Linux, D:\vault on Windows)

2. Add vault_path to .claude/identity.json (created during onboarding):

   {
     "user": "howard",
     "vault_path": "/Users/howard/vault"
   }
   

   This is the only place the path lives — no hardcoded paths in any shared file.

3. Install your age key. Mike will give you the key file. Drop it at:

   • Windows: C:\Users\<you>\AppData\Roaming\sops\age\keys.txt
   • Mac/Linux: ~/.config/sops/age/keys.txt

Without the age key, vault commands fail. Everything else works fine.

---

How Claude knows about our infrastructure

CLAUDE.md (the brain)

.claude/CLAUDE.md is the master instructions file. Claude reads it at the start of every session. It tells Claude:

• Who we are (AZ Computer Guru, MSP)
• How to behave (delegate to agents, no emojis, use vault for creds)
• What projects exist (GuruRMM, Dataforth, ClaudeTools API)
• 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.

CONTEXT.md files (per-project state)

Each major project has a CONTEXT.md that captures:

• Server IPs, ports, credentials references
• Current deployment state
• Recent session logs (what was done last)
• Anti-patterns (things NOT to do, learned from past mistakes)
• What to work on next

These files are the single source of truth for "where are we on this project."

Session logs (the history)

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
• Full credentials used (unredacted — needed for future sessions)
• Infrastructure changes made
• Commands that worked and errors that didn't
• What's still pending

This is why /save matters. Without it, the next person (or the next Claude session) starts from scratch.

---

Skills (auto-invoked behaviors)

Skills are more powerful than commands — some trigger automatically.

Skill	Auto-invokes?	What it does
frontend-design	YES — after any UI change	Validates visual correctness, accessibility, design quality
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
skill-creator	On request	Helps build new custom skills
theme-factory	On request	Apply visual themes to HTML artifacts

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.

---

Agents (specialized workers)

Claude Code can spawn sub-agents for specific tasks. These are defined in .claude/agents/. The main ones you'll encounter:

Agent	What it does	When Claude uses it
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
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
Gitea Agent	Git commits, pushes, branch operations	Commit workflow
Backup Agent	Backup operations	Before destructive changes

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.

---

Local AI tools (when available)

Ollama (local LLM)

Ollama runs AI models locally on your GPU. Used for tasks that don't need Claude's full reasoning power — summarization, classification, data extraction.

Models we use:

• qwen3:14b — general purpose (summarization, drafting)
• codestral:22b — code generation assistance
• nomic-embed-text — embeddings for semantic search

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):

curl -s http://100.92.127.64:11434/api/tags

If that returns models, you're connected. Claude automatically uses the right URL based on which machine you're on (reads from identity.json).

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

GrepAI (semantic code search)

Searches code by MEANING rather than exact text. "How does auth work?" finds authentication code even if the word "auth" doesn't appear.

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).

---

Project structure

D:\claudetools\
  .claude/           — Claude's brain (CLAUDE.md, agents, skills, memory, commands)
  session-logs/      — General work logs
  projects/
    dataforth-dos/   — Dataforth test datasheet pipeline (AD2, testdatadb)
    msp-tools/
      guru-rmm/      — GuruRMM agent + server (Rust, our product)
    newsletter/      — Marketing newsletters
  clients/
    dataforth/       — Dataforth-specific client docs
    pavon/           — Pavon/client docs
    ...              — Other clients
  credentials.md     — Quick-reference credentials (vault is source of truth)
  CONTEXT.md         — Root-level project context

D:\vault\            — SOPS-encrypted credentials (separate repo)
  infrastructure/    — Our servers (Jupiter, Uranus, pfSense, etc.)
  clients/           — Client credentials
  services/          — Service credentials (Cloudflare, Azure, Gitea, etc.)
  projects/          — Project-specific secrets

---

Daily workflow

Starting a work session

1. Open Claude Code in the project directory
2. Claude greets you by name (reads identity.json)
3. Tell Claude what you're working on — it auto-loads the right context
4. Work normally — ask questions, make changes, run commands

Ending a work session

1. /save — creates the session log (DO THIS EVERY TIME)
2. /sync — pushes everything to Gitea
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.

---

Things to know

Claude remembers across sessions — via session logs and memory files, not magic. If you don't /save, the next session starts cold.

Credentials are in the vault — don't ask Mike for passwords; ask Claude. It decrypts from the vault.

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.

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