Add top-level README and setup validation script
- README.md: Comprehensive overview of the configuration - Quick start guide - Feature summary - Directory structure - Key commands and skills - Maintenance commands - automation/validate-setup.sh: Validation script that checks: - Directory structure - Core files - Plugin manifest - Hooks configuration and executability - Skills and their scripts - State files (JSON validity) - Gmail integration - Documentation coverage Run with: ~/.claude/automation/validate-setup.sh 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
OpenCode Test
130
README.md
Normal file
130
README.md
Normal file
@@ -0,0 +1,130 @@
|
|||||||
|
# Will's Claude Code Configuration
|
||||||
|
|
||||||
|
Personal assistant and multi-agent system for homelab management.
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start a session
|
||||||
|
claude
|
||||||
|
|
||||||
|
# Use the personal assistant
|
||||||
|
/pa what's on my calendar today?
|
||||||
|
|
||||||
|
# Check system health
|
||||||
|
/sysadmin:health
|
||||||
|
|
||||||
|
# Check cluster status
|
||||||
|
/k8s:cluster-status
|
||||||
|
```
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
| Feature | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| **Personal Assistant** | Natural language interface via `/pa` |
|
||||||
|
| **Gmail Integration** | Read emails, check urgent, search |
|
||||||
|
| **Calendar Integration** | View agenda, check schedule |
|
||||||
|
| **Kubernetes Management** | Cluster health, deployments, diagnostics |
|
||||||
|
| **System Administration** | Health checks, updates, autonomy control |
|
||||||
|
| **Usage Tracking** | Session statistics and history |
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.claude/
|
||||||
|
├── .claude-plugin/ # Plugin manifest (for distribution)
|
||||||
|
├── agents/ # Agent persona definitions
|
||||||
|
├── automation/ # Systemd timers, scripts
|
||||||
|
├── commands/ # Slash commands (/pa, /gcal, etc.)
|
||||||
|
├── hooks/ # Event handlers (SessionStart, PreCompact)
|
||||||
|
├── mcp/ # MCP integrations (Gmail, delegation)
|
||||||
|
├── skills/ # Agent skills (gmail, gcal, k8s, sysadmin)
|
||||||
|
├── state/ # Shared state files (JSON)
|
||||||
|
├── workflows/ # Workflow definitions (design docs)
|
||||||
|
├── CLAUDE.md # Shared memory for all agents
|
||||||
|
└── README.md # This file
|
||||||
|
```
|
||||||
|
|
||||||
|
Each directory has its own README with details.
|
||||||
|
|
||||||
|
## Key Commands
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `/pa <request>` | Natural language request to personal assistant |
|
||||||
|
| `/gcal [today\|tomorrow\|week]` | Calendar agenda |
|
||||||
|
| `/usage [today\|week\|month]` | Usage statistics |
|
||||||
|
| `/sysadmin:health` | System health check |
|
||||||
|
| `/sysadmin:update` | Package updates |
|
||||||
|
| `/k8s:cluster-status` | Kubernetes health |
|
||||||
|
| `/k8s:diagnose` | Troubleshoot K8s issues |
|
||||||
|
|
||||||
|
## Skills (Auto-Invoked)
|
||||||
|
|
||||||
|
Skills are triggered automatically based on your request:
|
||||||
|
|
||||||
|
| Trigger | Skill |
|
||||||
|
|---------|-------|
|
||||||
|
| "check my email" | gmail |
|
||||||
|
| "what's on today" | gcal |
|
||||||
|
| "cluster status" | k8s-quick-status |
|
||||||
|
| "system health" | sysadmin-health |
|
||||||
|
| "usage stats" | usage |
|
||||||
|
|
||||||
|
## Hooks
|
||||||
|
|
||||||
|
| Event | Action |
|
||||||
|
|-------|--------|
|
||||||
|
| Session Start | Load context, check pending items |
|
||||||
|
| Pre-Compact | Remind to preserve important context |
|
||||||
|
|
||||||
|
## Agent Hierarchy
|
||||||
|
|
||||||
|
```
|
||||||
|
Personal Assistant (Opus)
|
||||||
|
└── Master Orchestrator (Opus)
|
||||||
|
├── linux-sysadmin (Sonnet)
|
||||||
|
├── k8s-orchestrator (Opus)
|
||||||
|
│ └── k8s-diagnostician, argocd-operator, etc.
|
||||||
|
└── programmer-orchestrator (Opus)
|
||||||
|
└── code-planner, code-implementer, code-reviewer
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `CLAUDE.md` | Shared instructions for all agents |
|
||||||
|
| `settings.json` | Claude Code settings |
|
||||||
|
| `state/component-registry.json` | Routing and discovery |
|
||||||
|
| `state/autonomy-levels.json` | Permission levels |
|
||||||
|
|
||||||
|
## Plugin Installation
|
||||||
|
|
||||||
|
This configuration can be installed as a plugin:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Add as local marketplace
|
||||||
|
/plugin marketplace add ~/.claude
|
||||||
|
|
||||||
|
# Install
|
||||||
|
/plugin install will-homelab@will-homelab-dev
|
||||||
|
```
|
||||||
|
|
||||||
|
## Maintenance
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Validate component registry
|
||||||
|
python3 ~/.claude/automation/validate-registry.py
|
||||||
|
|
||||||
|
# Regenerate registry from files
|
||||||
|
python3 ~/.claude/automation/generate-registry.py
|
||||||
|
|
||||||
|
# Check systemd timers
|
||||||
|
systemctl --user list-timers
|
||||||
|
```
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
172
automation/validate-setup.sh
Executable file
172
automation/validate-setup.sh
Executable file
@@ -0,0 +1,172 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# Validate the Claude Code configuration setup
|
||||||
|
# Run this after changes to ensure everything is properly configured
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
CLAUDE_DIR="${HOME}/.claude"
|
||||||
|
ERRORS=0
|
||||||
|
WARNINGS=0
|
||||||
|
|
||||||
|
# Colors
|
||||||
|
RED='\033[0;31m'
|
||||||
|
GREEN='\033[0;32m'
|
||||||
|
YELLOW='\033[1;33m'
|
||||||
|
NC='\033[0m' # No Color
|
||||||
|
|
||||||
|
pass() { echo -e "${GREEN}✓${NC} $1"; }
|
||||||
|
fail() { echo -e "${RED}✗${NC} $1"; ((ERRORS++)); }
|
||||||
|
warn() { echo -e "${YELLOW}!${NC} $1"; ((WARNINGS++)); }
|
||||||
|
|
||||||
|
echo "Validating Claude Code configuration..."
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check required directories
|
||||||
|
echo "=== Directory Structure ==="
|
||||||
|
for dir in agents commands hooks mcp skills state workflows automation; do
|
||||||
|
if [[ -d "${CLAUDE_DIR}/${dir}" ]]; then
|
||||||
|
pass "${dir}/ exists"
|
||||||
|
else
|
||||||
|
fail "${dir}/ missing"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check required files
|
||||||
|
echo "=== Core Files ==="
|
||||||
|
for file in CLAUDE.md README.md settings.json .gitignore; do
|
||||||
|
if [[ -f "${CLAUDE_DIR}/${file}" ]]; then
|
||||||
|
pass "${file} exists"
|
||||||
|
else
|
||||||
|
fail "${file} missing"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check plugin manifest
|
||||||
|
echo "=== Plugin Structure ==="
|
||||||
|
if [[ -f "${CLAUDE_DIR}/.claude-plugin/plugin.json" ]]; then
|
||||||
|
pass "plugin.json exists"
|
||||||
|
if python3 -c "import json; json.load(open('${CLAUDE_DIR}/.claude-plugin/plugin.json'))" 2>/dev/null; then
|
||||||
|
pass "plugin.json is valid JSON"
|
||||||
|
else
|
||||||
|
fail "plugin.json is invalid JSON"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
warn "plugin.json missing (optional for local use)"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check hooks
|
||||||
|
echo "=== Hooks ==="
|
||||||
|
if [[ -f "${CLAUDE_DIR}/hooks/hooks.json" ]]; then
|
||||||
|
pass "hooks.json exists"
|
||||||
|
if python3 -c "import json; json.load(open('${CLAUDE_DIR}/hooks/hooks.json'))" 2>/dev/null; then
|
||||||
|
pass "hooks.json is valid JSON"
|
||||||
|
else
|
||||||
|
fail "hooks.json is invalid JSON"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
warn "hooks.json missing"
|
||||||
|
fi
|
||||||
|
|
||||||
|
for script in session-start.sh pre-compact.sh; do
|
||||||
|
if [[ -x "${CLAUDE_DIR}/hooks/scripts/${script}" ]]; then
|
||||||
|
pass "hooks/scripts/${script} is executable"
|
||||||
|
elif [[ -f "${CLAUDE_DIR}/hooks/scripts/${script}" ]]; then
|
||||||
|
fail "hooks/scripts/${script} exists but not executable"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check skills
|
||||||
|
echo "=== Skills ==="
|
||||||
|
for skill in gmail gcal k8s-quick-status sysadmin-health usage programmer-add-project; do
|
||||||
|
skill_dir="${CLAUDE_DIR}/skills/${skill}"
|
||||||
|
if [[ -f "${skill_dir}/SKILL.md" ]]; then
|
||||||
|
pass "${skill}/SKILL.md exists"
|
||||||
|
|
||||||
|
# Check for scripts directory
|
||||||
|
if [[ -d "${skill_dir}/scripts" ]]; then
|
||||||
|
script_count=$(find "${skill_dir}/scripts" -type f \( -name "*.py" -o -name "*.sh" \) | wc -l)
|
||||||
|
if [[ ${script_count} -gt 0 ]]; then
|
||||||
|
pass "${skill}/scripts/ has ${script_count} script(s)"
|
||||||
|
|
||||||
|
# Check executability
|
||||||
|
while IFS= read -r script; do
|
||||||
|
[[ -f "$script" ]] || continue
|
||||||
|
if [[ -x "$script" ]]; then
|
||||||
|
pass "$(basename "$script") is executable"
|
||||||
|
else
|
||||||
|
fail "$(basename "$script") not executable"
|
||||||
|
fi
|
||||||
|
done < <(find "${skill_dir}/scripts" -type f \( -name "*.py" -o -name "*.sh" \) 2>/dev/null)
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
fail "${skill}/SKILL.md missing"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check state files
|
||||||
|
echo "=== State Files ==="
|
||||||
|
for file in component-registry.json autonomy-levels.json model-policy.json; do
|
||||||
|
state_file="${CLAUDE_DIR}/state/${file}"
|
||||||
|
if [[ -f "${state_file}" ]]; then
|
||||||
|
pass "state/${file} exists"
|
||||||
|
if python3 -c "import json; json.load(open('${state_file}'))" 2>/dev/null; then
|
||||||
|
pass "state/${file} is valid JSON"
|
||||||
|
else
|
||||||
|
fail "state/${file} is invalid JSON"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
fail "state/${file} missing"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check Gmail setup
|
||||||
|
echo "=== Gmail Integration ==="
|
||||||
|
if [[ -d "${CLAUDE_DIR}/mcp/gmail/venv" ]]; then
|
||||||
|
pass "Gmail venv exists"
|
||||||
|
if [[ -f "${CLAUDE_DIR}/mcp/gmail/venv/bin/python" ]]; then
|
||||||
|
pass "Gmail venv has Python"
|
||||||
|
else
|
||||||
|
fail "Gmail venv missing Python"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
warn "Gmail venv not set up"
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [[ -f "${HOME}/.gmail-mcp/credentials.json" ]]; then
|
||||||
|
pass "Gmail credentials exist"
|
||||||
|
else
|
||||||
|
warn "Gmail credentials missing (~/.gmail-mcp/credentials.json)"
|
||||||
|
fi
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check READMEs
|
||||||
|
echo "=== Documentation ==="
|
||||||
|
readme_count=0
|
||||||
|
for dir in agents commands hooks mcp skills state workflows; do
|
||||||
|
if [[ -f "${CLAUDE_DIR}/${dir}/README.md" ]]; then
|
||||||
|
readme_count=$((readme_count + 1))
|
||||||
|
else
|
||||||
|
warn "${dir}/README.md missing"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
pass "${readme_count}/7 directory READMEs present"
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Summary
|
||||||
|
echo "=== Summary ==="
|
||||||
|
if [[ ${ERRORS} -eq 0 && ${WARNINGS} -eq 0 ]]; then
|
||||||
|
echo -e "${GREEN}All checks passed!${NC}"
|
||||||
|
elif [[ ${ERRORS} -eq 0 ]]; then
|
||||||
|
echo -e "${YELLOW}${WARNINGS} warning(s), 0 errors${NC}"
|
||||||
|
else
|
||||||
|
echo -e "${RED}${ERRORS} error(s), ${WARNINGS} warning(s)${NC}"
|
||||||
|
fi
|
||||||
|
|
||||||
|
exit ${ERRORS}
|
||||||
Reference in New Issue
Block a user