ai-tools

One source of truth for AI-agent context, commands, output styles, settings, and MCP servers — installed once per device so every machine stays in sync.

Setting up a new machine? Follow SETUP.md — the end-to-end runbook that ties this repo and homelab together (prereqs, SSH key, Tailscale, hl-* commands). The section below covers just this repo's installer.

What gets installed

Repo file	Linked / registered to	Purpose
AGENTS.md	~/.claude/CLAUDE.md	Your context, preferences, conventions
commands/*.md	~/.claude/commands/	Slash commands (/new-tsd, /review-pr, …)
output-styles/*.md	~/.claude/output-styles/	Switchable personas (/output-style)
skills/<name>/	~/.claude/skills/<name>/	Skills — loaded when a task matches their description
agents/*.md	~/.claude/agents/	Subagents — run in their own context, report back a conclusion
claude/settings.json	~/.claude/settings.json	Baseline permission allowlist
claude/mcp-servers.json	user-scope MCP (claude mcp add-json)	github, homelab, homelab-calendar, terraform, rea
.env.example → secrets.env	sourced by ~/.zshenv (zsh) / ~/.bashrc — .zshenv so the desktop app sees it too	Tokens (gitignored, never committed)
shell/profile.ps1	sourced by both PowerShell $PROFILEs	oh-my-zsh-style Windows shell: nav + git aliases, PSReadLine, Starship prompt
shell/aliases.sh	sourced by ~/.zshrc / ~/.bashrc	Same nav + git aliases on Mac/Linux (prompt untouched — omz stays)

AGENTS.md is AI-agnostic — other tools (Cursor, Copilot, Windsurf) can point at the same file; uncomment the relevant block in the install scripts. The commands, output styles, settings, and MCP wiring are Claude Code-specific.

Install (once per machine)

Mac / Linux:

git clone https://github.com/brignano/ai-tools ~/.ai-tools
chmod +x ~/.ai-tools/install.sh
~/.ai-tools/install.sh --dry-run   # preview — touches nothing
~/.ai-tools/install.sh             # apply

Windows (any PowerShell — elevation optional, see below):

git clone https://github.com/brignano/ai-tools $env:USERPROFILE\.ai-tools
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
~\.ai-tools\install.ps1 -DryRun    # preview
~\.ai-tools\install.ps1            # apply

Then fill in tokens and reload your shell:

$EDITOR ~/.ai-tools/secrets.env    # paste HOMELAB_MCP_TOKEN, TFE_TOKEN, GITHUB_MCP_TOKEN
exec $SHELL                        # reload so Claude Code sees them
ai-refresh                         # re-register MCP servers that were waiting on a token
claude

The installer is safe to re-run: it refuses to clobber files it didn't install, prunes stale links for commands, styles, skills and agents you've deleted, and re-registers MCP servers idempotently.

Windows link types. Symlinks need Administrator or Developer Mode (Settings > System > For developers). Without either, install.ps1 uses hard links instead — same result day to day, but git pull replaces files rather than editing them, which breaks a hard link, so re-run install.ps1 after pulling. It records what it installed in ~/.claude/.ai-tools-links.json, so a re-run refreshes its own files and leaves yours alone; anything you edited yourself is saved alongside as <name>.bak before being relinked.

MCP servers

claude/mcp-servers.json is the source of truth; the installers register each one at user scope, and skip (and unregister) a server this machine can't run yet, saying why: its stdio command isn't installed (docker, uvx) or a ${VAR} it needs is empty in secrets.env. Fill the gap and re-run ai-refresh.

Server	Needs
github	GITHUB_MCP_TOKEN (fine-grained PAT). GitHub's MCP OAuth has no dynamic client registration, so Claude Code can't log in to it itself
homelab	HOMELAB_MCP_TOKEN: Bearer + MCP_BEARER_TOKEN from the homelab's docker/proxy/.env (not a Grafana token); Tailscale up
homelab-calendar	Same HOMELAB_MCP_TOKEN, nothing new. Read-only iCloud calendars via Home Assistant (homelab docker/mcp-calendar/); Tailscale up
terraform	Docker; TFE_TOKEN (HCP Terraform user token) for workspaces
rea	Node.js 22.19+ / 24.11+ (npx). REA: reverse engineer apps you don't have source for (Electron/JS, APKs, .NET, websites, HAR/pcap captures) with no extra installs; native binaries also need Ghidra, Hopper or IDA (npx -y rea-agents@6.4.0 doctor). Pinned; bump it together with skills/reverse-engineer-anything/

Servers listed under _retired are unregistered on every run: Slack, Vercel, Notion and aws-mcp. Use their claude.ai connectors instead — no per-machine login, uvx or AWS credentials, and Slack's MCP server needs a registered Slack app anyway.

Why some connectors aren't here

Anything you've added at claude.ai connectors is already available in Claude Code automatically when you're signed in with a claude.ai account — nothing to install. The entries above exist because they are worth pinning in git regardless: the config is versioned, and they keep working if your auth is ever an API key, Bedrock, or a profile, in which case connectors are not loaded at all.

Gmail, Google Calendar and Microsoft 365 cannot be moved here. Their upstream identity providers only accept the redirect URL claude.ai registered, so local OAuth from Claude Code is not possible. Connect them at claude.ai and they appear in Claude Code on their own.

If a server here points at the same URL as a claude.ai connector, this one wins and /mcp lists the connector as hidden.

Update (any machine)

ai-refresh              # pull + re-run the installer
ai-refresh --dry-run    # show what would change, touch nothing

ai-refresh is defined in your shell profile by install.sh, and on Windows by shell/profile.ps1 (which install.ps1 wires into $PROFILE; -DryRun works too), so it exists on every machine after the first install (open a new shell, or exec $SHELL, to pick it up). It refuses to run if the checkout has uncommitted changes, so it can never clobber local edits, and it leaves your working directory unchanged.

It's a shell function, not an alias — an alias can't take --dry-run, guard on a dirty tree, or return a non-zero exit code.

If the repo isn't at the path baked in at install time, point it somewhere else:

AI_TOOLS_DIR=/path/to/ai-tools ai-refresh

$env:AI_TOOLS_DIR = "C:\path\to\ai-tools"; ai-refresh

Equivalent by hand:

cd ~/.ai-tools && git pull        # symlinks update instantly
~/.ai-tools/install.sh            # only needed if you added/removed a command, style,
                                  # skill or agent, or changed MCP
                                  # (on Windows without symlinks, always re-run install.ps1)

What's NOT handled

Installing Claude Code itself, and claude login/auth — do those once per machine manually. Sign in with your claude.ai account so its connectors (Gmail, Slack, Notion, AWS, ...) load.

Structure

ai-tools/
├── AGENTS.md              # Source of truth — context, preferences, conventions
├── commands/             # Slash commands
├── output-styles/        # Switchable personas / system instructions
├── skills/               # One directory per skill (SKILL.md + bundled files)
├── agents/               # Subagent definitions, one .md each
├── claude/
│   ├── settings.json     # Baseline permission allowlist (no secrets)
│   └── mcp-servers.json  # MCP server defs with ${VAR} secret placeholders
├── shell/
│   ├── profile.ps1       # Windows shell: aliases, PSReadLine, Starship init
│   ├── aliases.sh        # Mac/Linux: same aliases for zsh/bash
│   └── starship.toml     # robbyrussell-style prompt config (Windows only — the
│                         #   Mac keeps its oh-my-zsh prompt)
├── .env.example          # Template → copy to secrets.env (gitignored)
├── install.sh            # Mac/Linux installer
└── install.ps1           # Windows installer (no WSL)

Adding things

• Command: drop a .md (with description / argument-hint frontmatter) in commands/, git push, then git pull + re-run install elsewhere.
• Output style: same, in output-styles/ (frontmatter: name, description).
• Skill: add skills/<name>/SKILL.md (frontmatter: name, description) plus any files it uses, then re-run install. See skills/README.md for what belongs here versus a repo's own .claude/skills/.
• Agent: drop a .md (frontmatter: name, description, optional tools) in agents/, then re-run install. See agents/README.md.
• MCP server: add it to claude/mcp-servers.json (use ${VAR} for any secret, add the var to .env.example), then re-run install.
• Permission: add a pattern to claude/settings.json permissions.allow.
• Shell alias: add it to both shell/profile.ps1 (PowerShell) and shell/aliases.sh (zsh/bash), git push — no re-install needed, profiles source the repo files directly.
• Another AI tool: uncomment its block in both install scripts.