# 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