Cal Corum babf062d6a docs: archive headless-claude design docs to legacy/

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>

2026-03-01 08:15:13 -06:00

2.6 KiB

Raw Blame History

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.

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

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

2.6 KiB Raw Blame History