Agents and LLM Usage

Agents & LLM Usage

Caeruleus treats LLM agents as first-class users. Two things make it agent-friendly:

1. Structured output. -o json / -o jsonl give token-efficient, machine-readable output an agent parses directly, without scraping human-formatted tables.
2. A portable Agent Skill. The repo ships skills/caeruleus/SKILL.md in the agentskills.io format, teaching any Agent Skills-compatible assistant the command surface and a recommended assessment methodology. Point an agent at a device and it runs the whole methodology end to end.

In our benchmark, Opus 4.8 (xHigh) with Caeruleus and its skill completed the task in 62% of the time and 70% of the tokens of the same model with free tool choice (which reached for hcitool and Bleak scripts).

Using the skill

Any Agent Skills-compatible assistant can load skills/caeruleus/SKILL.md. It tells the agent to:

• Prefer the tool's own help (caeruleus --help, caeruleus <cmd> --help, caeruleus recipes [keyword]) over guessing flags.
• Treat -o json output as authoritative and not re-run a command in text mode "for display" — the JSON is complete, and re-running doubles the BLE round-trip for zero new data.
• Chain recon → assess ... → conn-params, capture each step's JSON, and correlate the findings into a report.

Practical tips for agents

• Hold one connection. For many sequential operations, start sudo caeruleus serve -b $A once and dispatch with caeruleus send "read 0x0029", avoiding the ~1.5s reconnect per command. batch is the stdin equivalent. See Output & Automation.
• One central at a time. Most peripherals accept a single connection; don't fan out parallel connects to the same device. Offline steps that only read saved JSON artifacts can run in parallel.
• Recover deterministically. On a stuck link, caeruleus forget -b $A or caeruleus adapter power cycle; caeruleus doctor -o json reports health and the fix.
• Findings are data, not errors. Assessment commands exit 0 even when they find issues; read findings[], don't branch on exit code for "vulnerable or not."

Minimal agent loop

A=AA:BB:CC:DD:EE:FF
caeruleus doctor -o json
caeruleus recon -b $A -o json > recon.json
caeruleus assess check-auth -b $A -o json > checkauth.json
caeruleus assess encryption -b $A -o json > enc.json
# merge findings[] across files, dedupe by (uuid,title), rank by severity, write the report