@stanco323/oh-my-claude-code 4.10.3

package/skills/hud/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: hud
+description: Configure HUD display options (layout, presets, display elements)
+argument-hint: "[setup|minimal|focused|full|status]"
+role: config-writer  # DOCUMENTATION ONLY - This skill writes to ~/.claude/ paths
+scope: ~/.claude/**  # DOCUMENTATION ONLY - Allowed write scope
+level: 2
+---
+
+# HUD Skill
+
+Configure the OMC HUD (Heads-Up Display) for the statusline.
+
+Note: All `~/.claude/...` paths in this guide respect `CLAUDE_CONFIG_DIR` when that environment variable is set.
+
+## Quick Commands
+
+| Command | Description |
+|---------|-------------|
+| `/oh-my-claudecode:hud` | Show current HUD status (auto-setup if needed) |
+| `/oh-my-claudecode:hud setup` | Install/repair HUD statusline |
+| `/oh-my-claudecode:hud minimal` | Switch to minimal display |
+| `/oh-my-claudecode:hud focused` | Switch to focused display (default) |
+| `/oh-my-claudecode:hud full` | Switch to full display |
+| `/oh-my-claudecode:hud status` | Show detailed HUD status |
+
+## Auto-Setup
+
+When you run `/oh-my-claudecode:hud` or `/oh-my-claudecode:hud setup`, the system will automatically:
+1. Check if `~/.claude/hud/omc-hud.mjs` exists
+2. Check if `statusLine` is configured in `~/.claude/settings.json`
+3. If missing, create the HUD wrapper script and configure settings
+4. Report status and prompt to restart Claude Code if changes were made
+
+**IMPORTANT**: If the argument is `setup` OR if the HUD script doesn't exist at `~/.claude/hud/omc-hud.mjs`, you MUST create the HUD files directly using the instructions below.
+
+### Setup Instructions (Run These Commands)
+
+**Step 1:** Check if setup is needed:
+```bash
+node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude');console.log(f.existsSync(p.join(d,'hud','omc-hud.mjs'))?'EXISTS':'MISSING')"
+```
+
+**Step 2:** Verify the plugin is installed:
+```bash
+node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude'),b=p.join(d,'plugins','cache','omc','oh-my-claudecode');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x)).sort((a,c)=>a.localeCompare(c,void 0,{numeric:true}));if(v.length===0){console.log('Plugin not installed - run: /plugin install oh-my-claudecode');process.exit()}const l=v[v.length-1],h=p.join(b,l,'dist','hud','index.js');console.log('Version:',l);console.log(f.existsSync(h)?'READY':'NOT_FOUND - try reinstalling: /plugin install oh-my-claudecode')}catch{console.log('Plugin not installed - run: /plugin install oh-my-claudecode')}"
+```
+
+**Step 3:** If omc-hud.mjs is MISSING or argument is `setup`, create the HUD directory and script:
+
+First, create the directory:
+```bash
+node -e "require('fs').mkdirSync(require('path').join(process.env.CLAUDE_CONFIG_DIR||require('path').join(require('os').homedir(),'.claude'),'hud'),{recursive:true})"
+```
+
+Then, use the Write tool to create `~/.claude/hud/omc-hud.mjs` with this exact content:
+
+```javascript
+#!/usr/bin/env node
+/**
+ * OMC HUD - Statusline Script
+ * Wrapper that imports from dev paths, plugin cache, or npm package
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+async function main() {
+  const home = homedir();
+  let pluginCacheVersion = null;
+  let pluginCacheDir = null;
+
+  // 1. Development paths (only when OMC_DEV=1)
+  if (process.env.OMC_DEV === "1") {
+    const devPaths = [
+      join(home, "Workspace/oh-my-claudecode/dist/hud/index.js"),
+      join(home, "workspace/oh-my-claudecode/dist/hud/index.js"),
+      join(home, "projects/oh-my-claudecode/dist/hud/index.js"),
+    ];
+
+    for (const devPath of devPaths) {
+      if (existsSync(devPath)) {
+        try {
+          await import(pathToFileURL(devPath).href);
+          return;
+        } catch { /* continue */ }
+      }
+    }
+  }
+
+  // 2. Plugin cache (for production installs)
+  // Respect CLAUDE_CONFIG_DIR so installs under a custom config dir are found
+  const configDir = process.env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+  const pluginCacheBase = join(configDir, "plugins", "cache", "omc", "oh-my-claudecode");
+  if (existsSync(pluginCacheBase)) {
+    try {
+      const versions = readdirSync(pluginCacheBase);
+      if (versions.length > 0) {
+        // Filter to only versions with built dist/hud/index.js
+        // This prevents picking an unbuilt new version after plugin update
+        const builtVersions = versions.filter(version => {
+          const pluginPath = join(pluginCacheBase, version, "dist/hud/index.js");
+          return existsSync(pluginPath);
+        });
+
+        if (builtVersions.length > 0) {
+          const latestVersion = builtVersions.sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).reverse()[0];
+          pluginCacheVersion = latestVersion;
+          pluginCacheDir = join(pluginCacheBase, latestVersion);
+          const pluginPath = join(pluginCacheDir, "dist/hud/index.js");
+          await import(pathToFileURL(pluginPath).href);
+          return;
+        }
+      }
+    } catch { /* continue */ }
+  }
+
+  // 3. npm package (global or local install)
+  try {
+    await import("oh-my-claudecode/dist/hud/index.js");
+    return;
+  } catch { /* continue */ }
+
+  // 4. Fallback: provide detailed error message with fix instructions
+  if (pluginCacheDir && existsSync(pluginCacheDir)) {
+    // Plugin exists but dist/ folder is missing - needs build
+    const distDir = join(pluginCacheDir, "dist");
+    if (!existsSync(distDir)) {
+      console.log(`[OMC HUD] Plugin installed but not built. Run: cd "${pluginCacheDir}" && npm install && npm run build`);
+    } else {
+      console.log(`[OMC HUD] Plugin dist/ exists but HUD not found. Run: cd "${pluginCacheDir}" && npm run build`);
+    }
+  } else if (existsSync(pluginCacheBase)) {
+    // Plugin cache directory exists but no built versions found
+    console.log("[OMC HUD] Plugin cache found but no built versions. Run: /oh-my-claudecode:omc-setup");
+  } else {
+    // No plugin installation found at all
+    console.log("[OMC HUD] Plugin not installed. Run: /oh-my-claudecode:omc-setup");
+  }
+}
+
+main();
+```
+
+**Step 3:** Make it executable (Unix only, skip on Windows):
+```bash
+node -e "if(process.platform==='win32'){console.log('Skipped (Windows)')}else{require('fs').chmodSync(require('path').join(process.env.CLAUDE_CONFIG_DIR||require('path').join(require('os').homedir(),'.claude'),'hud','omc-hud.mjs'),0o755);console.log('Done')}"
+```
+
+**Step 4:** Update settings.json to use the HUD:
+
+Read `~/.claude/settings.json`, then update/add the `statusLine` field.
+
+**IMPORTANT:** Do not use `~` in the command. On Unix, use `$HOME` to keep the path portable across machines. On Windows, use an absolute path because Windows does not expand `~` in shell commands.
+
+If you are on Windows, first determine the correct path:
+```bash
+node -e "const p=require('path').join(require('os').homedir(),'.claude','hud','omc-hud.mjs').split(require('path').sep).join('/');console.log(JSON.stringify(p))"
+```
+
+**IMPORTANT:** The command path MUST use forward slashes on all platforms. Claude Code executes statusLine commands via bash, which interprets backslashes as escape characters and breaks the path.
+
+Then set the `statusLine` field. On Unix it should stay portable and look like:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node $HOME/.claude/hud/omc-hud.mjs"
+  }
+}
+```
+
+On Windows the path uses forward slashes (not backslashes):
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node C:/Users/username/.claude/hud/omc-hud.mjs"
+  }
+}
+```
+
+Use the Edit tool to add/update this field while preserving other settings.
+
+**Step 5:** Clean up old HUD scripts (if any):
+```bash
+node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude'),t=p.join(d,'hud','omc-hud.mjs');try{if(f.existsSync(t)){f.unlinkSync(t);console.log('Removed legacy script')}else{console.log('No legacy script found')}}catch{}"
+```
+
+**Step 6:** Tell the user to restart Claude Code for changes to take effect.
+
+## Display Presets
+
+### Minimal
+Shows only the essentials:
+```
+[OMC] ralph | ultrawork | todos:2/5
+```
+
+### Focused (Default)
+Shows all relevant elements:
+```
+[OMC] branch:main | ralph:3/10 | US-002 | ultrawork skill:planner | ctx:67% | agents:2 | bg:3/5 | todos:2/5
+```
+
+### Full
+Shows everything including multi-line agent details:
+```
+[OMC] repo:oh-my-claudecode branch:main | ralph:3/10 | US-002 (2/5) | ultrawork | ctx:[████░░]67% | agents:3 | bg:3/5 | todos:2/5
+├─ O architect    2m   analyzing architecture patterns...
+├─ e explore     45s   searching for test files
+└─ s executor     1m   implementing validation logic
+```
+
+## Multi-Line Agent Display
+
+When agents are running, the HUD shows detailed information on separate lines:
+- **Tree characters** (`├─`, `└─`) show visual hierarchy
+- **Agent code** (O, e, s) indicates agent type with model tier color
+- **Duration** shows how long each agent has been running
+- **Description** shows what each agent is doing (up to 45 chars)
+
+## Display Elements
+
+| Element | Description |
+|---------|-------------|
+| `[OMC]` | Mode identifier |
+| `repo:name` | Git repository name (cyan) |
+| `branch:name` | Git branch name (cyan) |
+| `ralph:3/10` | Ralph loop iteration/max |
+| `US-002` | Current PRD story ID |
+| `ultrawork` | Active mode badge |
+| `skill:name` | Last activated skill (cyan) |
+| `ctx:67%` | Context window usage |
+| `agents:2` | Running subagent count |
+| `bg:3/5` | Background task slots |
+| `todos:2/5` | Todo completion |
+
+## Color Coding
+
+- **Green**: Normal/healthy
+- **Yellow**: Warning (context >70%, ralph >7)
+- **Red**: Critical (context >85%, ralph at max)
+
+## Configuration Location
+
+HUD config is stored in `~/.claude/settings.json` under the `omcHud` key (or your custom config directory if `CLAUDE_CONFIG_DIR` is set).
+
+Legacy config location (deprecated): `~/.claude/.omc/hud-config.json`
+
+## Manual Configuration
+
+You can manually edit the config file. Each option can be set individually - any unset values will use defaults.
+
+```json
+{
+  "preset": "focused",
+  "elements": {
+    "omcLabel": true,
+    "ralph": true,
+    "autopilot": true,
+    "prdStory": true,
+    "activeSkills": true,
+    "lastSkill": true,
+    "contextBar": true,
+    "agents": true,
+    "agentsFormat": "multiline",
+    "backgroundTasks": true,
+    "todos": true,
+    "thinking": true,
+    "thinkingFormat": "text",
+    "permissionStatus": false,
+    "apiKeySource": false,
+    "profile": true,
+    "promptTime": true,
+    "sessionHealth": true,
+    "useBars": true,
+    "showCallCounts": true,
+    "callCountsFormat": "auto",
+    "safeMode": true,
+    "maxOutputLines": 4
+  },
+  "thresholds": {
+    "contextWarning": 70,
+    "contextCompactSuggestion": 80,
+    "contextCritical": 85,
+    "ralphWarning": 7
+  },
+  "staleTaskThresholdMinutes": 30,
+  "contextLimitWarning": {
+    "threshold": 80,
+    "autoCompact": false
+  }
+}
+```
+
+### callCountsFormat
+
+Controls the call-count badge icon style:
+- `"auto"` (default): emoji on macOS/Linux, ASCII on Windows/WSL
+- `"emoji"`: force `🔧 🤖 ⚡`
+- `"ascii"`: force `T: A: S:`
+
+### safeMode
+
+When `safeMode` is `true` (default), the HUD strips ANSI codes and uses ASCII-only output to prevent terminal rendering corruption during concurrent updates. This is especially important on Windows and when using terminal multiplexers.
+
+### agentsFormat Options
+
+- `count`: agents:2
+- `codes`: agents:Oes (type-coded with model tier casing)
+- `codes-duration`: agents:O(2m)es (codes with duration)
+- `detailed`: agents:[architect(2m),explore,exec]
+- `descriptions`: O:analyzing code | e:searching (codes + what they're doing)
+- `tasks`: [analyzing code, searching...] (just descriptions)
+- `multiline`: Multi-line display with full agent details on separate lines
+
+## Troubleshooting
+
+If the HUD is not showing:
+1. Run `/oh-my-claudecode:hud setup` to auto-install and configure
+2. Restart Claude Code after setup completes
+3. If still not working, run `/oh-my-claudecode:omc-doctor` for full diagnostics
+
+**Legacy string format migration:** Older OMC versions wrote `statusLine` as a plain string (e.g., `"~/.claude/hud/omc-hud.mjs"`). Modern Claude Code (v2.1+) requires an object format. Running the installer or `/oh-my-claudecode:hud setup` will auto-migrate legacy strings to the correct object format:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node $HOME/.claude/hud/omc-hud.mjs"
+  }
+}
+```
+
+**Node 24+ compatibility:** The HUD wrapper script imports `homedir` from `node:os` (not `node:path`). If you encounter `SyntaxError: The requested module 'path' does not provide an export named 'homedir'`, re-run the installer to regenerate `omc-hud.mjs`.
+
+Manual verification:
+- HUD script: `~/.claude/hud/omc-hud.mjs`
+- Settings: `~/.claude/settings.json` should have `statusLine` configured as an object with `type` and `command` fields
+
+---
+
+*The HUD updates automatically every ~300ms during active sessions.*

package/skills/learner/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: learner
+description: Extract a learned skill from the current conversation
+level: 7
+---
+
+# Learner Skill
+
+This is a Level 7 (self-improving) skill. It has two distinct sections:
+- **Expertise**: Domain knowledge about what makes a good skill. Updated automatically as patterns are discovered.
+- **Workflow**: Stable extraction procedure. Rarely changes.
+
+Only the Expertise section should be updated during improvement cycles.
+
+---
+
+## Expertise
+
+> This section contains domain knowledge that improves over time.
+> It can be updated by the learner itself when new patterns are discovered.
+
+### Core Principle
+
+Reusable skills are not code snippets to copy-paste, but **principles and decision-making heuristics** that teach Claude HOW TO THINK about a class of problems.
+
+**The difference:**
+- BAD (mimicking): "When you see ConnectionResetError, add this try/except block"
+- GOOD (reusable skill): "In async network code, any I/O operation can fail independently due to client/server lifecycle mismatches. The principle: wrap each I/O operation separately, because failure between operations is the common case, not the exception."
+
+### Quality Gate
+
+Before extracting a skill, ALL three must be true:
+- "Could someone Google this in 5 minutes?" → NO
+- "Is this specific to THIS codebase?" → YES
+- "Did this take real debugging effort to discover?" → YES
+
+### Recognition Signals
+
+Extract ONLY after:
+- Solving a tricky bug that required deep investigation
+- Discovering a non-obvious workaround specific to this codebase
+- Finding a hidden gotcha that wastes time when forgotten
+- Uncovering undocumented behavior that affects this project
+
+### What Makes a USEFUL Skill
+
+1. **Non-Googleable**: Something you couldn't easily find via search
+   - BAD: "How to read files in TypeScript" ❌
+   - GOOD: "This codebase uses custom path resolution in ESM that requires fileURLToPath + specific relative paths" ✓
+
+2. **Context-Specific**: References actual files, error messages, or patterns from THIS codebase
+   - BAD: "Use try/catch for error handling" ❌
+   - GOOD: "The aiohttp proxy in server.py:42 crashes on ClientDisconnectedError - wrap StreamResponse in try/except" ✓
+
+3. **Actionable with Precision**: Tells you exactly WHAT to do and WHERE
+   - BAD: "Handle edge cases" ❌
+   - GOOD: "When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution matches package.json type field" ✓
+
+4. **Hard-Won**: Took significant debugging effort to discover
+   - BAD: Generic programming patterns ❌
+   - GOOD: "Race condition in worker.ts - the Promise.all at line 89 needs await before the map callback returns" ✓
+
+### Anti-Patterns (DO NOT EXTRACT)
+
+- Generic programming patterns (use documentation instead)
+- Refactoring techniques (these are universal)
+- Library usage examples (use library docs)
+- Type definitions or boilerplate
+- Anything a junior dev could Google in 5 minutes
+
+---
+
+## Workflow
+
+> This section contains the stable extraction procedure.
+> It should NOT be updated during improvement cycles.
+
+### Step 1: Gather Required Information
+
+- **Problem Statement**: The SPECIFIC error, symptom, or confusion that occurred
+  - Include actual error messages, file paths, line numbers
+  - Example: "TypeError in src/hooks/session.ts:45 when sessionId is undefined after restart"
+
+- **Solution**: The EXACT fix, not general advice
+  - Include code snippets, file paths, configuration changes
+  - Example: "Add null check before accessing session.user, regenerate session on 401"
+
+- **Triggers**: Keywords that would appear when hitting this problem again
+  - Use error message fragments, file names, symptom descriptions
+  - Example: ["sessionId undefined", "session.ts TypeError", "401 session"]
+
+- **Scope**: Almost always Project-level unless it's a truly universal insight
+
+### Step 2: Quality Validation
+
+The system REJECTS skills that are:
+- Too generic (no file paths, line numbers, or specific error messages)
+- Easily Googleable (standard patterns, library usage)
+- Vague solutions (no code snippets or precise instructions)
+- Poor triggers (generic words that match everything)
+
+### Step 3: Classify as Expertise or Workflow
+
+Before saving, determine if the learning is:
+- **Expertise** (domain knowledge, pattern, gotcha) → Save as `{topic}-expertise.md`
+- **Workflow** (operational procedure, step sequence) → Save as `{topic}-workflow.md`
+
+This classification ensures expertise can be updated independently without destabilizing workflows.
+
+### Step 4: Save Location
+
+- **User-level**: ~/.claude/skills/omc-learned/ - Rare. Only for truly portable insights.
+- **Project-level**: .omc/skills/ - Default. Version-controlled with repo.
+
+### Skill Body Template
+
+```markdown
+# [Skill Name]
+
+## The Insight
+What is the underlying PRINCIPLE you discovered? Not the code, but the mental model.
+
+## Why This Matters
+What goes wrong if you don't know this? What symptom led you here?
+
+## Recognition Pattern
+How do you know when this skill applies? What are the signs?
+
+## The Approach
+The decision-making heuristic, not just code. How should Claude THINK about this?
+
+## Example (Optional)
+If code helps, show it - but as illustration of the principle, not copy-paste material.
+```
+
+**Key**: A skill is REUSABLE if Claude can apply it to NEW situations, not just identical ones.
+
+## Related Commands
+
+- /oh-my-claudecode:note - Save quick notes that survive compaction (less formal than skills)
+- /oh-my-claudecode:ralph - Start a development loop with learning capture

package/skills/mcp-setup/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: mcp-setup
+description: Configure popular MCP servers for enhanced agent capabilities
+level: 2
+---
+
+# MCP Setup
+
+Configure Model Context Protocol (MCP) servers to extend Claude Code's capabilities with external tools like web search, file system access, and GitHub integration.
+
+## Overview
+
+MCP servers provide additional tools that Claude Code agents can use. This skill helps you configure popular MCP servers using the `claude mcp add` command-line interface.
+
+## Step 1: Show Available MCP Servers
+
+Present the user with available MCP server options using AskUserQuestion:
+
+**Question:** "Which MCP server would you like to configure?"
+
+**Options:**
+1. **Context7** - Documentation and code context from popular libraries
+2. **Exa Web Search** - Enhanced web search (replaces built-in websearch)
+3. **Filesystem** - Extended file system access with additional capabilities
+4. **GitHub** - GitHub API integration for issues, PRs, and repository management
+5. **All of the above** - Configure all recommended MCP servers
+6. **Custom** - Add a custom MCP server
+
+## Step 2: Gather Required Information
+
+### For Context7:
+No API key required. Ready to use immediately.
+
+### For Exa Web Search:
+Ask for API key:
+```
+Do you have an Exa API key?
+- Get one at: https://exa.ai
+- Enter your API key, or type 'skip' to configure later
+```
+
+### For Filesystem:
+Ask for allowed directories:
+```
+Which directories should the filesystem MCP have access to?
+Default: Current working directory
+Enter comma-separated paths, or press Enter for default
+```
+
+### For GitHub:
+Ask for token:
+```
+Do you have a GitHub Personal Access Token?
+- Create one at: https://github.com/settings/tokens
+- Recommended scopes: repo, read:org
+- Enter your token, or type 'skip' to configure later
+```
+
+## Step 3: Add MCP Servers Using CLI
+
+Use the `claude mcp add` command to configure each MCP server. The CLI automatically handles settings.json updates and merging.
+
+### Context7 Configuration:
+```bash
+claude mcp add context7 -- npx -y @upstash/context7-mcp
+```
+
+### Exa Web Search Configuration:
+```bash
+claude mcp add -e EXA_API_KEY=<user-provided-key> exa -- npx -y exa-mcp-server
+```
+
+### Filesystem Configuration:
+```bash
+claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem <allowed-directories>
+```
+
+### GitHub Configuration:
+
+**Option 1: Docker (local)**
+```bash
+claude mcp add -e GITHUB_PERSONAL_ACCESS_TOKEN=<user-provided-token> github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
+```
+
+**Option 2: HTTP (remote)**
+```bash
+claude mcp add --transport http github https://api.githubcopilot.com/mcp/
+```
+
+> Note: Docker option requires Docker installed. HTTP option is simpler but may have different capabilities.
+
+## Step 4: Verify Installation
+
+After configuration, verify the MCP servers are properly set up:
+
+```bash
+# List configured MCP servers
+claude mcp list
+```
+
+This will display all configured MCP servers and their status.
+
+## Step 5: Show Completion Message
+
+```
+MCP Server Configuration Complete!
+
+CONFIGURED SERVERS:
+[List the servers that were configured]
+
+NEXT STEPS:
+1. Restart Claude Code for changes to take effect
+2. The configured MCP tools will be available to all agents
+3. Run `claude mcp list` to verify configuration
+
+USAGE TIPS:
+- Context7: Ask about library documentation (e.g., "How do I use React hooks?")
+- Exa: Use for web searches (e.g., "Search the web for latest TypeScript features")
+- Filesystem: Extended file operations beyond the working directory
+- GitHub: Interact with GitHub repos, issues, and PRs
+
+TROUBLESHOOTING:
+- If MCP servers don't appear, run `claude mcp list` to check status
+- Ensure you have Node.js 18+ installed for npx-based servers
+- For GitHub Docker option, ensure Docker is installed and running
+- Run /oh-my-claudecode:omc-doctor to diagnose issues
+
+MANAGING MCP SERVERS:
+- Add more servers: /oh-my-claudecode:mcp-setup or `claude mcp add ...`
+- List servers: `claude mcp list`
+- Remove a server: `claude mcp remove <server-name>`
+```
+
+## Custom MCP Server
+
+If user selects "Custom":
+
+Ask for:
+1. Server name (identifier)
+2. Transport type: `stdio` (default) or `http`
+3. For stdio: Command and arguments (e.g., `npx my-mcp-server`)
+4. For http: URL (e.g., `https://example.com/mcp`)
+5. Environment variables (optional, key=value pairs)
+6. HTTP headers (optional, for http transport only)
+
+Then construct and run the appropriate `claude mcp add` command:
+
+**For stdio servers:**
+```bash
+# Without environment variables
+claude mcp add <server-name> -- <command> [args...]
+
+# With environment variables
+claude mcp add -e KEY1=value1 -e KEY2=value2 <server-name> -- <command> [args...]
+```
+
+**For HTTP servers:**
+```bash
+# Basic HTTP server
+claude mcp add --transport http <server-name> <url>
+
+# HTTP server with headers
+claude mcp add --transport http --header "Authorization: Bearer <token>" <server-name> <url>
+```
+
+## Common Issues
+
+### MCP Server Not Loading
+- Ensure Node.js 18+ is installed
+- Check that npx is available in PATH
+- Run `claude mcp list` to verify server status
+- Check server logs for errors
+
+### API Key Issues
+- Exa: Verify key at https://dashboard.exa.ai
+- GitHub: Ensure token has required scopes (repo, read:org)
+- Re-run `claude mcp add` with correct credentials if needed
+
+### Agents Still Using Built-in Tools
+- Restart Claude Code after configuration
+- The built-in websearch will be deprioritized when exa is configured
+- Run `claude mcp list` to confirm servers are active
+
+### Removing or Updating a Server
+- Remove: `claude mcp remove <server-name>`
+- Update: Remove the old server, then add it again with new configuration