HALO

Run HALO agent-trace analyses, schedule recurring reports, and pull report markdown from the CLI.

HALO analyzes your agent's traces and produces a markdown report that flags anomalies, errors, inefficiencies, and opportunities to improve reliability, latency, cost, and tool usage. The report is written to read like a brief you can paste straight into a coding agent to apply the fixes.

Use inf halo to kick off a one-off analysis, schedule recurring ones, watch a run reach completion, and read the resulting report.

How HALO is organized

A run is one analysis of one agent over one time window. Each completed run produces exactly one report.
A conversation is the thread a run lives in. The first assistant message is the original report; any follow-up questions you ask add more runs and more assistant messages to the same conversation.
A schedule fires recurring runs for one agent on a cadence (hourly, daily, weekly, or monthly).

The report markdown is the assistant message content inside a conversation. There is no separate "report" artifact to download, so reading a report means reading its conversation.

Quickstart: run an analysis and read the report

# 1. Find the agent you want to analyze
inf halo agent list

# 2. Start a run for that agent over the last 24h
inf halo run create --agent-uuid <agent-uuid>

# 3. Wait for it to finish (prints the run id from step 2)
inf halo run poll <run-id>

# 4. Read the report (the assistant message in the conversation)
inf halo conversation get <conversation-id>

inf halo run create prints both the run-id and the conversation-id. The report prints in full from inf halo conversation get — no --json required. Add --json only when you want the raw structured payload for scripting.

`inf halo agent`

List the agents HALO sees in your project's recent traces. You need an agent's UUID to start a run or create a schedule.

inf halo agent list

Alias: inf halo agent ls

Options

Flag	Required	Description	Default
`--time-range <range>`	No	Trace window to scan for agents: `1h`, `6h`, `12h`, `1d`, `3d`, `7d`, `14d`, `30d`, `90d`	`30d`

`inf halo run`

Create and inspect HALO runs.

`inf halo run create`

Start a manual analysis for one agent over a time window.

inf halo run create --agent-uuid <agent-uuid>

In an interactive terminal you can omit --agent-uuid to pick from recent agents. In non-interactive or --json mode, --agent-uuid is required.

Options

Flag	Required	Description	Default
`--agent-uuid <id>`	No (required non-interactively)	Agent UUID from `inf halo agent list`	Interactive picker
`--prompt <text>`	No	Prompt steering the analysis	Default HALO prompt
`--window-start-at <iso>`	No	Window start, ISO datetime	Derived from `--lookback-hours`
`--window-end-at <iso>`	No	Window end, ISO datetime	Now
`--lookback-hours <n>`	No	Window length when `--window-start-at` is omitted	`24`
`--model-id <id>`	No	Catalog HALO model id	Catalog default
`--span-limit <n>`	No	Per-run span cap	`10000`
`--max-subagent-depth <n>`	No	Engine recursion ceiling (1–5)	`3`
`--max-turns <n>`	No	Per-agent turn ceiling (1–100)	`50`
`--agent-time-range <range>`	No	Trace window preset used when picking an agent interactively	`30d`

`inf halo run poll`

Poll a run until it reaches a terminal state (completed, failed, cancelled, timed_out, or no_traces). Exits 0 only on completed.

inf halo run poll <run-id>

Options

Flag	Required	Description	Default
`--interval <seconds>`	No	Poll interval	`5`
`--timeout <seconds>`	No	Total timeout	`1800` (30 min)

`inf halo run get`

Fetch a run's status and its referenced trace dataset. This returns run metadata, not the report text — read the conversation for the report.

inf halo run get <run-id>

`inf halo run events`

List the structured event timeline for a run (started, heartbeat, agent steps, completed, failed).

inf halo run events <run-id>

Options

Flag	Required	Description	Default
`--limit <n>`	No	Max events to return	`100`

`inf halo run cancel`

Request cancellation of an in-flight run.

inf halo run cancel <run-id> --reason "no longer needed"

Options

Flag	Required	Description	Default
`--reason <text>`	No	Reason recorded for the cancellation	`user-cancelled`

`inf halo conversation`

Inspect HALO conversations and read their reports.

Alias: inf halo conv

`inf halo conversation list`

List conversations in the active project, newest first.

inf halo conversation list

Alias: inf halo conversation ls

Options

Flag	Required	Description	Default
`--limit <n>`	No	Max conversations to return	`50`

`inf halo conversation get`

Print a conversation with its messages, runs, and trace datasets. The assistant messages are the report markdown — the first assistant message is the original report; later ones answer follow-up questions in the same thread. Message content prints in full.

inf halo conversation get <conversation-id>

Add --json to get the raw payload (every message, run, and trace dataset) for scripting.

`inf halo schedule`

Manage recurring HALO analyses. Each schedule targets one agent and fires runs on a cadence.

`inf halo schedule list`

inf halo schedule list

Alias: inf halo schedule ls

Flag	Required	Description	Default
`--include-archived`	No	Include archived schedules	`false`

`inf halo schedule get`

inf halo schedule get <schedule-id>

`inf halo schedule runs`

List recent runs fired by a schedule.

inf halo schedule runs <schedule-id>

Flag	Required	Description	Default
`--limit <n>`	No	Max runs to return	`50`

`inf halo schedule create`

inf halo schedule create \
  --title "Daily checkout-agent review" \
  --agent-uuid <agent-uuid> \
  --frequency daily \
  --hours 9 \
  --minutes 0 \
  --timezone America/Los_Angeles

Flag	Required	Description	Default
`--title <title>`	Yes	Human-readable schedule title	-
`--agent-uuid <id>`	Yes	Agent the schedule analyzes (from `inf halo agent list`)	-
`--frequency <freq>`	Yes	`hourly`, `daily`, `weekly`, or `monthly`	-
`--prompt <text>`	No	Prompt steering each run	Default HALO prompt
`--hours <list>`	For daily/weekly/monthly	Comma-separated hours (0–23)	-
`--minutes <list>`	Yes	Comma-separated minutes (0–59)	-
`--days-of-week <list>`	For weekly	Comma-separated days (0=Sun…6=Sat)	-
`--days-of-month <list>`	For monthly	Comma-separated days (1–31)	-
`--timezone <tz>`	No	IANA timezone	`UTC`
`--model-id <id>`	No	Catalog HALO model id	Catalog default
`--span-limit <n>`	No	Per-run span cap	`10000`
`--lookback-hours <n>`	No	How far back each run looks, independent of cadence	`24`
`--max-subagent-depth <n>`	No	Engine recursion ceiling (1–5)	`3`
`--max-turns <n>`	No	Per-agent turn ceiling (1–100)	`50`
`--enabled <bool>`	No	Whether the schedule fires	`true`

`inf halo schedule update`

Update mutable fields on a schedule. Accepts the same flags as create (all optional), keyed by <schedule-id>.

# Pause a schedule
inf halo schedule update <schedule-id> --enabled false

# Repoint it at a different agent and widen the window
inf halo schedule update <schedule-id> --agent-uuid <other-agent> --lookback-hours 168

`inf halo schedule archive` / `unarchive`

Archive a schedule so it stops firing, or restore it later.

inf halo schedule archive <schedule-id>
inf halo schedule unarchive <schedule-id>

archive prompts for confirmation. Pass -y / --yes to skip the prompt.

Common workflows

# Run an analysis end-to-end and capture the report markdown to a file
RUN=$(inf halo run create --agent-uuid <agent-uuid> --json)
RUN_ID=$(echo "$RUN" | jq -r '.runId')
CONV_ID=$(echo "$RUN" | jq -r '.conversationId')

inf halo run poll "$RUN_ID"

# Extract just the original report (first assistant message) as markdown
inf halo conversation get "$CONV_ID" --json \
  | jq -r '.messages | map(select(.role == "assistant"))[0].content' \
  > halo-report.md

inf trace and inf span inspect the underlying traces HALO analyzes.
The MCP server exposes the same reports to AI coding assistants via list_halo_conversations and get_halo_conversation.

On this page