> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inference.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Metadata text="cli/halo/quickstart" />

```bash theme={"system"}
# 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.

<Metadata text="cli/halo/agent-list" />

```bash theme={"system"}
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.

<Metadata text="cli/halo/run-create" />

```bash theme={"system"}
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`.

<Metadata text="cli/halo/run-poll" />

```bash theme={"system"}
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.

<Metadata text="cli/halo/run-get" />

```bash theme={"system"}
inf halo run get <run-id>
```

### `inf halo run events`

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

<Metadata text="cli/halo/run-events" />

```bash theme={"system"}
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.

<Metadata text="cli/halo/run-cancel" />

```bash theme={"system"}
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.

<Metadata text="cli/halo/conversation-list" />

```bash theme={"system"}
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.

<Metadata text="cli/halo/conversation-get" />

```bash theme={"system"}
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`

<Metadata text="cli/halo/schedule-list" />

```bash theme={"system"}
inf halo schedule list
```

**Alias:** `inf halo schedule ls`

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

### `inf halo schedule get`

<Metadata text="cli/halo/schedule-get" />

```bash theme={"system"}
inf halo schedule get <schedule-id>
```

### `inf halo schedule runs`

List recent runs fired by a schedule.

<Metadata text="cli/halo/schedule-runs" />

```bash theme={"system"}
inf halo schedule runs <schedule-id>
```

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

### `inf halo schedule create`

<Metadata text="cli/halo/schedule-create" />

```bash theme={"system"}
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>`.

<Metadata text="cli/halo/schedule-update" />

```bash theme={"system"}
# 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.

<Metadata text="cli/halo/schedule-archive" />

```bash theme={"system"}
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

<Metadata text="cli/halo/workflows" />

```bash theme={"system"}
# 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
```

## Related commands

* [`inf trace`](/cli/traces) and [`inf span`](/cli/spans) inspect the underlying traces HALO analyzes.
* The [MCP server](/integrations/mcp-server) exposes the same reports to AI coding assistants via `list_halo_conversations` and `get_halo_conversation`.