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