# Headless Claude - N8N Server Diagnostics

Automated server monitoring system: N8N triggers Claude Code in headless mode to diagnose and remediate home server issues.

## Agent SDK Reference

Full docs: https://code.claude.com/docs/en/headless
CLI reference: https://code.claude.com/docs/en/cli-reference
Agent SDK (Python/TS): https://platform.claude.com/docs/en/agent-sdk/overview

## Key CLI Patterns

### Invocation
All headless invocations use `-p` (print/prompt mode). This is non-interactive — no user prompts, no skill slash commands.

```bash
claude -p "<prompt>" \
  --output-format json \
  --json-schema '<schema>' \
  --allowedTools "Read,Grep,Glob,Bash(python3 ~/.claude/skills/server-diagnostics/client.py *)"
```

### Structured Output (`--json-schema`)
- When `--json-schema` is provided, the response JSON has a `structured_output` field conforming to the schema
- Falls back to `result` field (free text) if schema is not used
- Always parse `structured_output` first, `result` as fallback

### Tool Permissions (`--allowedTools`)
- Uses permission rule syntax with prefix matching
- **Space before `*` matters**: `Bash(python3 *)` matches `python3 <anything>`, but `Bash(python3*)` also matches `python3something`
- Scope Bash narrowly — prefer `Bash(python3 ~/.claude/skills/server-diagnostics/client.py *)` over broad `Bash`

### Session Resumption
```bash
session_id=$(claude -p "..." --output-format json | jq -r '.session_id')
claude -p "follow up" --resume "$session_id"
```

### System Prompt Customization
- `--append-system-prompt` adds to default behavior
- `--system-prompt` fully replaces default prompt

## Infrastructure

| Component | Location | Notes |
|---|---|---|
| Claude Code LXC | CT 300, 10.10.0.148 | Runs claude CLI, SSH keys to targets |
| N8N | CT 210, 10.10.0.210 | Workflow orchestration |
| Target server | paper-dynasty, 10.10.0.88 | Docker containers monitored |
| Diagnostics skill | `~/.claude/skills/server-diagnostics/` on CT 300 | Python client + config |

## Project Structure

- `PRD.md` — Product requirements (v2.0)
- `n8n-workflow-import.json` — Production N8N workflow (importable)
- `docs/n8n-workflow-design.md` — Full 10-node workflow design
- `docs/skill-architecture.md` — Server diagnostics skill spec
- `docs/lxc-setup-guide.md` — LXC provisioning
- `docs/n8n-setup-instructions.md` — N8N credential setup

## Phase Status

- Phase 1 (Foundation): **Complete** — live, polling every 5 min
- Phase 2 (Enhancement): Pending — alert dedup, expanded monitoring
- Phase 3 (Expansion): Pending — multi-server, Proxmox VMs/LXCs
