babf062d6a
Original planning folder (no git repo) for the server diagnostics system that runs on CT 300. Live deployment is on claude-runner; this preserves the Agent SDK reference, PRD with Phase 2/3 roadmap, and N8N workflow designs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
# 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
|