cli.md

---
title: Inference Gateway CLI
description: The Inference Gateway CLI (infer) - interactive chat, autonomous agents, Computer Use tools, MCP integration, A2A delegation, GitHub Action wizard, and remote messaging channels.
---

# Inference Gateway CLI

The Inference Gateway CLI (`infer`) is a powerful Go-based command-line tool providing comprehensive access to the Inference Gateway with interactive chat, autonomous agents, Computer Use tools, and development workflows.

> **Versioning:** the CLI is pre-1.0 and breaking changes are expected until it stabilises. The commands on this page install `@latest`, so there is no version number to keep in sync here - see the [releases page](https://github.com/inference-gateway/cli/releases) for what `latest` currently resolves to.

## Key Features

- **Zero-Configuration Setup** - Add API keys and start chatting
- **Autonomous Agent Mode** - Delegate complex tasks with iterative execution
- **Computer Use Tools** - GUI automation with screenshot, mouse, and keyboard control
- **Screen Recording** - Record the screen, a window, or a region to MP4 from chat ([Learn more](#screen-recording))
- **Rich Tool Integration** - File operations, code search, web access, GitHub via the `gh` CLI
- **Smart Safety System** - Configurable approval workflow with diff visualization
- **Beautiful TUI** - Scrollable interface with syntax highlighting and multiple themes
- **Web Terminal** - Browser-based interface with tabbed sessions
- **Remote Messaging Channels** - Control the agent from Telegram and other platforms ([Learn more](/cli-channels/))
- **Agent Skills** - Reusable, model-readable instruction folders loaded on demand, portable across vendors ([Learn more](/cli-skills/))
- **Custom Tools** - Add tools written in any language with one YAML manifest per tool ([Learn more](#custom-tools))
- **Plugins** - Claude Code-format skill bundles plus an always-on ruleset, managed with `infer plugins`
- **Frame Sources and Vision Annotation** - Let text-only models read screen and camera frames ([Learn more](#frame-sources-and-vision-annotation))
- **Cost Tracking** - Real-time token usage and cost calculation ([Learn more](#cost-tracking))

## Installation

> The CLI repository's [Installation guide](https://github.com/inference-gateway/cli/blob/main/docs/installation.md) is the canonical reference for every install channel; this section mirrors it.

### npm / npx (Recommended)

Run the CLI without installing anything (requires Node.js >= 18). The matching native binary is downloaded and cached on first use:

```bash
npx @inference-gateway/cli@latest --help
npx @inference-gateway/cli@latest chat
```

Or install it globally:

```bash
npm install -g @inference-gateway/cli
infer --help
```

Not recommended for production - prefer the install script, the Nix flake, the container image, or a source build. Prebuilt binaries cover Linux, macOS, and Windows on amd64/arm64.

### Install Script (Recommended)

Linux/macOS:

```bash
# Latest version
curl -fsSL https://raw.githubusercontent.com/inference-gateway/cli/main/install.sh | bash

# Specific version
curl -fsSL https://raw.githubusercontent.com/inference-gateway/cli/main/install.sh | bash -s -- --version v0.217.0

# Custom directory
curl -fsSL https://raw.githubusercontent.com/inference-gateway/cli/main/install.sh | bash -s -- --install-dir $HOME/.local/bin
```

Windows (PowerShell 5.1+ / pwsh) uses `install.ps1`, with `-Version` and an `INSTALL_DIR` environment variable for the same two options.

### Go Install

```bash
go install github.com/inference-gateway/cli/cmd/infer@latest
```

### Nix Flake / Flox

```bash
# Run without installing
nix run github:inference-gateway/cli

# Pin a release
nix run github:inference-gateway/cli/v0.217.0

# Install into your profile
nix profile install github:inference-gateway/cli
```

With [Flox](https://flox.dev), pin it in `.flox/env/manifest.toml` under `[install]` as `infer.flake = "github:inference-gateway/cli"`, then `flox activate`.

### Container Image

```bash
docker network create inference-gateway
docker run -d --name inference-gateway --network inference-gateway \
  --env-file .env \
  ghcr.io/inference-gateway/inference-gateway:latest

docker run -it --rm --network inference-gateway ghcr.io/inference-gateway/cli:latest chat
```

### Manual Download

Download binaries from the [GitHub releases page](https://github.com/inference-gateway/cli/releases) - `infer-<os>-<arch>` for Linux, macOS, and Windows on amd64/arm64 (rename the Windows binary to `infer.exe`). Verify the download against `checksums.txt` or its Cosign signature using the [Binary Verification guide](https://github.com/inference-gateway/cli/blob/main/docs/binary-verification.md), then make it executable and move it onto your `PATH` as `infer`.

### Build from Source

```bash
git clone https://github.com/inference-gateway/cli.git
cd cli
CGO_ENABLED=0 go build -tags purego -o infer ./cmd/infer
```

The build is fully cgo-free on macOS, Linux, and Windows - no C toolchain and no macOS SDK are required, and the same host cross-compiles every target. The `purego` build tag selects the pure-Go display and input backend and is used on all three platforms.

### Shell Completions

The CLI ships an `infer completion` subcommand (provided by [fang](https://github.com/charmbracelet/fang)) that generates completion scripts for **bash**, **zsh**, **fish**, and **powershell**. Enabling completions adds tab-completion for subcommands, flags, and many flag values.

```sh
# Zsh (current session)
source <(infer completion zsh)

# Zsh (persistent) - write to a directory on $fpath
infer completion zsh > "${fpath[1]}/_infer"

# Bash (current session)
source <(infer completion bash)

# Bash (persistent)
infer completion bash > /etc/bash_completion.d/infer

# Fish
infer completion fish > ~/.config/fish/completions/infer.fish

# PowerShell
infer completion powershell | Out-String | Invoke-Expression
```

Run `infer completion --help` to list the supported shells. After writing a persistent completion file, start a new shell (or re-source your shell rc) for it to take effect. If completions do not appear, see [Shell Completions Not Working](#shell-completions-not-working).

## Quick Start

![infer chat in plan mode fans out 5 read-only subagents to search a repository for docs gaps and drift, then opens each running subagent's live transcript from the list under the composer](/images/subagents.gif)

```bash
# Initialize configuration
infer init

# Generate AGENTS.md documentation for AI agents (recommended for new projects)
infer chat
> /init

# Check gateway status
infer status

# Start interactive chat
infer chat

# Launch web terminal
infer chat --web

# Headless mode
infer headless "Analyze this codebase and suggest improvements"

# Get help (styled output)
infer --help

# Show version
infer --version

# Enable shell completions for the current shell (zsh example)
source <(infer completion zsh)
```

### Generating AGENTS.md

For new projects, use the `/init` shortcut to automatically generate an `AGENTS.md` file. This file provides structured documentation that helps AI agents understand your project:

```bash
infer chat
> /init
```

The agent will:

1. Analyze your project structure with the Tree tool
2. Examine configuration files, build systems, and documentation
3. Generate comprehensive `AGENTS.md` including:
   - Project overview and technologies
   - Architecture and structure
   - Development environment setup
   - Key commands (build, test, lint, run)
   - Testing instructions
   - Project conventions and coding standards
   - Important files and configurations

This documentation helps other AI agents (and developers) quickly understand how to work with your project.

### How AGENTS.md reaches the model

The project-root `AGENTS.md` is injected whole into the system prompt as a `PROJECT INSTRUCTIONS (AGENTS.md)` section, after any custom instructions. It is capped by `agent.agents_md.max_lines` (default `399`) and `agent.agents_md.max_chars` (default `8000`); when the file exceeds either limit it is truncated with a marker. Both limits apply to the root file only. Turn the whole section off with `agent.agents_md.enabled: false`.

```yaml
agent:
  agents_md:
    enabled: true
    max_lines: 399
    max_chars: 8000
```

Environment variables: `INFER_AGENT_AGENTS_MD_ENABLED`, `INFER_AGENT_AGENTS_MD_MAX_LINES`, `INFER_AGENT_AGENTS_MD_MAX_CHARS`.

#### Nested AGENTS.md files

Following the [agents.md](https://agents.md) standard, an `AGENTS.md` in a subdirectory holds rules for that directory and **takes precedence over the root file there**. The CLI points the model at these nested files rather than injecting them, so the model reads a package brief with the Read tool only when it works in that directory - the system prompt stays small no matter how many briefs the repository has.

Discovery walks the working directory up to 4 levels deep and skips hidden directories and `node_modules`/`vendor` trees. The walk is lexical, so the system prompt stays byte-stable across turns and keeps prompt-cache prefix hits.

How the section renders depends on the project tree:

- **With `agent.context.tree_enabled` on** (the default): the `PROJECT STRUCTURE` listing already shows where the nested files are, so only the precedence rule is added.
- **With the tree off**: the precedence rule is followed by the nested paths, at most 20 entries. Beyond that the section notes how many more exist.

Nested files are never subject to `max_lines` / `max_chars`, since their content is not injected. When the root `AGENTS.md` is missing, nested files are still discovered and pointed at.

## Help and Version Output

The CLI's help, error, and version output are rendered with [fang](https://github.com/charmbracelet/fang), so every command produces styled, colorized output. The samples below are shown as plain text; in a real terminal the headings, flags, and errors are colorized.

### Help

`infer --help` (and `--help` on any subcommand) prints a styled usage page grouped into usage, commands, and flags. Note that `-v` is `--verbose`; version is the long-form `--version` flag.

```text
infer

A powerful command-line interface for managing and interacting with
the Inference Gateway.

USAGE
  infer [command] [--flags]

COMMANDS
  init           Initialize user configuration
  status         Check gateway health and resource usage
  chat           Interactive chat session (TUI)
  headless       Headless task execution
  config         Configuration management
  tools          Run and inspect agent tools directly
  completion     Generate the autocompletion script for the specified shell
  version        Show version information

FLAGS
  -h --help      Show help
  -v --verbose   Verbose output
     --version   Print version information
```

### Errors

Unknown commands and flags exit non-zero with a styled error message and no noisy usage dump (fang sets cobra's `SilenceErrors`/`SilenceUsage` and renders the error itself):

```text
$ infer badcmd
Error: unknown command "badcmd" for "infer"
$ echo $?
1
```

### Version

`infer --version` prints the version, styled by fang:

```text
$ infer --version
infer version vX.Y.Z
```

The standalone `version` subcommand is **kept for backwards compatibility** and prints the same information:

```bash
infer version
```

> The manual `--version` boolean flag was replaced by fang's built-in version handling (`fang.WithVersion`). Both `infer --version` and the `infer version` subcommand remain supported.

## Core Commands

| Command                  | Description                      | Key Features                                                     |
| ------------------------ | -------------------------------- | ---------------------------------------------------------------- |
| `infer init`             | Seed the userspace baseline      | Creates `~/.infer/` defaults - writes nothing to the project     |
| `infer status`           | Check gateway health             | Shows resource usage and connectivity                            |
| `infer chat`             | Interactive chat TUI             | Streaming, scrolling, tool expansion, mode switching             |
| `infer chat --web`       | Web-based terminal               | Browser interface, tabbed sessions, remote access                |
| `infer headless <task>`  | Autonomous task execution        | Background operation, task planning, validation                  |
| `infer headless --serve` | Long-lived AG-UI worker          | One run per `run_agent_input` frame over stdio, no task argument |
| `infer config <cmd>`     | Configuration management         | Generic `get`/`set` for any config key                           |
| `infer tools <cmd>`      | Run agent tools directly         | Execute a tool or validate a bash command                        |
| `infer stats`            | Summarize local telemetry        | Token usage, tool outcomes, and cost across sessions             |
| `infer traces`           | View a session's trace span tree | Offline span-tree viewer, `--list` and JSON output               |

### Chat Interface Features

**Navigation:**

- **Shift + Arrow Down/Up**: Scroll chat history
- **Ctrl+O**: Toggle tool result expansion
- **Ctrl+R**: Fuzzy search the project's prompt history (see below)
- **Ctrl+M** (**Alt+M** fallback): Toggle raw/rendered markdown
- **Shift+Tab**: Cycle agent modes (Standard -> Plan -> Auto-Accept -> Auto+Judge)
- **Ctrl+K**: Toggle model thinking blocks

**Capabilities:**

- Real-time streaming with syntax highlighting
- Mouse wheel and keyboard scrolling
- Model switching during conversation
- Tool result inspection
- Cost tracking in status bar
- Collapsible thinking blocks
- GitHub issue references - type `#` to insert and expand `#N` tokens (see below)
- Opt-in next-step suggestions as ghost text in the empty input (see below)

#### Prompt History Search (`Ctrl+R`)

`Ctrl+R` opens a fuzzy search over the current project's prompt history above the input:

- Type to filter - matches are highlighted, most recent prompts first, duplicates collapsed.
- **Up/Down** select an entry.
- **Enter** loads the highlighted prompt into the input for editing - it is **not** sent.
- **Esc** closes the overlay and leaves whatever you had typed untouched.

> **Muscle memory:** `Ctrl+R` used to toggle raw/rendered markdown. That toggle moved to **Ctrl+M**, with **Alt+M** as a fallback. Terminals without the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) report `Ctrl+M` as `Enter`, so use `Alt+M` there.

Both actions are rebindable in `.infer/keybindings.yaml` - `text_editing_history_search` for the search and `display_toggle_raw_format` for the markdown toggle. `infer keybindings list` prints the current bindings.

#### Next-Step Suggestions

When `chat.suggestions.enabled` is on, the CLI offers a **one-line next step** as dim ghost text in the empty chat input after an assistant turn completes. It is **opt in** and off by default:

```bash
infer config set chat.suggestions.enabled true
# then /reload in a running chat
```

The request is sent about two seconds after the turn completes, and only when the UI stayed quiet for that window - empty input, no typing, no autocomplete popup, no overlay form, no busy turn, no queued messages. So it costs **at most one small LLM call per completed turn**.

| Key                   | Action                                          |
| --------------------- | ----------------------------------------------- |
| `Tab` / `Right` arrow | Accept the suggestion into the input - not sent |
| `Esc`                 | Dismiss it and cancel the in-flight request     |
| Typing / a new turn   | Same - dismisses it and cancels the request     |

The call is **silent-fail**: a timeout, an error or a non-conforming answer leaves the input untouched and logs at debug level, so a flaky suggestion model never interrupts the chat.

```yaml
# .infer/config.yaml
chat:
  suggestions:
    enabled: true
    model: '' # Empty falls back to the active chat model, then agent.model
    context_messages: 4 # Recent non-hidden messages grounding the suggestion
    max_tokens: 512 # Output cap - an answer that hits it is discarded, not truncated
    timeout: 10 # Seconds before the request is abandoned
```

| Key                                 | Default | Description                                                                                                                        |
| ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `chat.suggestions.enabled`          | `false` | Master switch for the ghost-text suggestion                                                                                        |
| `chat.suggestions.model`            | `''`    | Model for the suggestion call. Empty falls back to the model the chat is using, then `agent.model` - a cheap, fast model fits here |
| `chat.suggestions.context_messages` | `4`     | How many recent non-hidden conversation messages ground the suggestion                                                             |
| `chat.suggestions.max_tokens`       | `512`   | Output token cap. Reasoning models spend thinking tokens against it                                                                |
| `chat.suggestions.timeout`          | `10`    | Seconds before the suggestion request is abandoned                                                                                 |

Each key has an `INFER_*` override - `INFER_CHAT_SUGGESTIONS_ENABLED`, `INFER_CHAT_SUGGESTIONS_MODEL`, `INFER_CHAT_SUGGESTIONS_CONTEXT_MESSAGES`, `INFER_CHAT_SUGGESTIONS_MAX_TOKENS` and `INFER_CHAT_SUGGESTIONS_TIMEOUT`. The system prompt lives in `prompts.yaml` under `chat.suggestions.system_prompt` and is overridden with `INFER_PROMPTS_CHAT_SUGGESTIONS_SYSTEM_PROMPT`.

#### GitHub Issue References (`#`)

Type `#` in the chat input to open a dropdown of the current repository's **open issues** - each entry shows the issue number, title, and state. The list is resolved through the [`gh` CLI](#github-operations) from the repo's git remote, newest first. Selecting an issue inserts a highlighted `#N` token into your message.

On submit, every `#N` token is expanded **inline** into that issue's title, body, and most recent comments (up to the latest 20) before the message is sent to the model - so the agent works from full issue context without a redundant `gh issue view` lookup.

```bash
infer chat
> Summarize #123 and propose a fix
# "#123" expands into the issue title, body, and recent comments before sending
```

**Prerequisite:** the [`gh` CLI](#github-operations) must be installed and authenticated, and the working directory must be a git repository with a remote. The feature **gracefully no-ops** when `gh` is missing, the directory is not a git repo, the repo has no remote, or authentication has expired - the dropdown simply shows nothing.

#### Resuming a session (`--session-id`)

`infer chat --session-id <id>` loads a persisted conversation before the TUI starts, letting you pick up where you left off. The session must have been persisted by a [storage backend](#conversation-management) (`storage.enabled: true`).

```bash
# Find session IDs from saved conversations
infer conversations list

# Resume a specific session
infer chat --session-id abc-123-def
```

**Session ID resolution:**

- A literal **UUID** is used as-is.
- Any **non-UUID** value is treated as a **session group key** and resolved through the session rollover chain to the latest session in that group.

**Fallback:** If the session cannot be loaded (e.g. the ID does not exist or storage is disabled), the CLI prints a visible notice and starts a new session under the requested ID — the same semantics as [`infer headless --session-id`](#resuming-a-session-session-id).

**Ignored in non-interactive modes:** The flag is ignored (with a printed notice) in `--web` mode and when input is piped (non-interactive).

#### Status indicator row

Below the chat input, a row of **status indicators** shows the current agent state. You can interact with these indicators using the keyboard:

| Key                    | Action                                            |
| ---------------------- | ------------------------------------------------- |
| `Down` arrow           | Focus the indicator row from the chat input       |
| `Left` / `Right` arrow | Cycle between indicators                          |
| `Enter`                | Open the matching view for the selected indicator |
| `Esc` / `Up` arrow     | Return focus to the chat input                    |

The selected indicator is highlighted as an **accent-colored pill**.

**Indicator labels:**

| Indicator | Label format                             | Description                                                                                                                                                                                                                                                                                                           |
| --------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tools     | `Tools: N (mode)`                        | `N` is the number of tools available in the current [agent mode](#agent-modes). `mode` is the active mode name (Standard, Plan, Auto-Accept, or Auto+Judge - the latter shown as `AUTO+JUDGE - <model>`). Opens the [`/tools` view](#tools-view).                                                                     |
| A2A       | `A2A: X/Y`                               | `X` is the number of connected A2A agents, `Y` is the total number of configured agents. Opens the [`/agents` view](#agents-view). When [liveness probes](#a2a-liveness-probes) are enabled, `X` counts down as agents fail and counts back up when they recover - the indicator stays live for the session lifetime. |
| Theme     | `Theme`                                  | Opens the theme selector to change the TUI color scheme.                                                                                                                                                                                                                                                              |
| Reconnect | `Reconnecting...` / `Reconnecting (N/M)` | Shown in red when the stream has stalled and the CLI is reconnecting. `N` is the current attempt, `M` is `client.retry.max_attempts`. Input is blocked until the stream recovers or all attempts are exhausted.                                                                                                       |
| Duration  | `3s` / `1m5s`                            | The time the agent has worked in this session, next to the cost indicator. Whole seconds only. Nothing is rendered before the session's first run.                                                                                                                                                                    |

##### Session working time

The duration indicator behaves like a stopwatch: it counts while the agent works, holds when the agent reaches a terminal state - completed, cancelled or failed - and resumes with the next run. A user interrupt stops the counter. While an approval or a question waits on you the display holds and then catches up once it is answered, so the waiting time counts.

The total is **saved with the session**, so [resuming a session](#resuming-a-session-session-id) continues its count. `/new`, a new session and a cleared conversation reset it to zero, the same way they reset the cost.

It is on by default and turned off like any other indicator:

```yaml
# .infer/config.yaml
chat:
  status_bar:
    indicators:
      duration: false # Hide the time the agent has worked in this session (default: true)
```

#### Background job list

While background jobs are tracked - [local subagents](#local-subagents-agent-tool), [A2A tasks](#a2a-integration), background shells, [screen recordings](#screen-recording) - they appear as a stacked list below the status indicators, one row per job with its label, kind and a live elapsed counter.

A subagent's row carries a child line with its run stats: tool calls that succeeded and failed, the tokens of its whole session and the slice the provider served from its prompt cache (`C.`). For a headless subagent the line counts up while it works. Each count's icon takes its status color - `✓` in the success color, `✗` in the error color - only while that count is above `0`; at `0` the icon is dimmed, so a run with no failures never shows a red `✗`. A finished row lingers with a green `✓` or a red `✗` for `chat.status_bar.subagent_linger_seconds` (default `5`), then drops.

```text
┌ npm run build shell       2.0s
│ reviewer      subagent ✓ 40.0s
│ └ 12 ✓ 1 ✗ · 61.2k tokens C.58.1k
└ tester        subagent ✗ 48.0s
  └ 3 ✓ 4 ✗ · 890 tokens
```

| Key               | Action                                                    |
| ----------------- | --------------------------------------------------------- |
| `Down` arrow      | Focus the job list from the status indicator row          |
| `Up` / `Down`     | Move the selection over the tracked jobs                  |
| `Enter`           | Show the selected job's transcript in place of the chat's |
| `Esc`             | Back to the chat's own transcript, then back to the input |
| `Up` (on top row) | Return focus to the status indicator row                  |

Typing any other text blurs the list and lands in the input. While a job is viewed, moving the selection follows it to the newly selected job, and the transcript refreshes once a second until the job is reaped.

**Scroll window.** The list shows at most **5 rows** so a large fan-out cannot push the status bar off screen, but the cap is a scroll window rather than a hard limit: with the list focused, the selection moves over **every** tracked job and the window scrolls to follow it, so any job can be selected and opened with `Enter`. Jobs outside the window are summarized by dim boundary markers - `N above` above the first row and `+N more` below the last. With the list unfocused the window sits at the top, so only `+N more` is shown.

#### Switching models (`/model`)

`/model` is the unified model command:

- `/model <name>` - **permanently** switch the active model for the rest of the session.
- `/model <name> <prompt...>` - run a **single** message with `<name>`, then restore the session model afterward. Handy for sending one hard question to a stronger model without changing your default.
- `/model` (no argument) - open the model picker.

```bash
infer chat
> /model deepseek/deepseek-v4-flash                              # switch the session model
> /model anthropic/claude-opus-4-8 Explain this stack trace    # one-off, then restore
```

##### Model picker labels

When you open the model picker (`/model` with no argument), each model may show a suffix label indicating its capabilities:

| Label       | Meaning                                                                                                          |
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `vision`    | The model accepts image input natively - pasted or @-referenced images are seen directly, no ImageDecode needed. |
| `audio`     | The model takes audio input (speech-to-text, multimodal chat).                                                   |
| `video`     | The model takes video input.                                                                                     |
| `image-gen` | The model generates images (e.g. DALL-E, GPT-Image) rather than text.                                            |
| `view-only` | The model cannot serve `/chat/completions` and therefore cannot be selected - see below.                         |

Labels are derived from the **gateway-reported modalities** (`/v1/models?include=modalities`), not from name patterns. A model gets the `vision` label when its input modalities include both `text` and `image`; it gets the `image-gen` label when its output modalities include `image` without `text`. Labels are appended to the metadata suffix after the context window and price:

```
ollama_cloud/glm-5.3-flash (1M, vision, video)
groq/whisper-large-v3      (?, $0.04/$0.00 per MTok, audio, view-only)
```

**Gateway version requirement:** Modalities-driven labels and the chat-capability filter require gateway v0.47+. Against an older gateway, models report no modalities, so no labels are shown and no model is chat-capable. Upgrade the running gateway to v0.47+ to see your catalog.

##### View-only models

Non-chat models - speech-to-text (e.g. `groq/whisper-*`), text-to-speech (e.g. `openai/tts-*`, `groq/playai-tts*`), image generation and video - are **listed** in the picker with a `view-only` marker, after the chat-capable rows. They are visible so you can see what the gateway offers, but pressing `Enter` on one is rejected with a notice (`<model> does not support chat and cannot be selected`) and the picker stays open. Only chat-capable models can be selected, and `/model <name>`, model validation and autocomplete are unaffected.

A model the gateway reports no modalities for (`"modalities": null`) is treated as not chat-capable, which is how most speech and embedding models arrive.

##### Filter tabs

The picker has two tab rows that are **ANDed** together, so `Free` + `Vision` lists only free vision models:

| Row        | Keys  | Tabs                                                           |
| ---------- | ----- | -------------------------------------------------------------- |
| Pricing    | `1-4` | `[1] All`, `[2] Free`, `[3] Pay-as-you-go`, `[4] Subscription` |
| Capability | `5-8` | `[5] Any`, `[6] Vision`, `[7] Audio`, `[8] Video`              |

`Vision` matches image **input**. `Audio` and `Video` match models that work with that modality on **either side**, so both speech-to-text and text-to-speech models appear under `Audio`. See [Model Categories](#model-categories-free-pay-as-you-go-subscription) for how the pricing tabs are derived.

The footer help line lists the full keymap:

```
↑↓ navigate · Enter select · / search · esc clear · 1-4 pricing · 5-8 capability · Ctrl+C cancel
```

Digits typed while the search input is active (`/`) go into the query, not the tabs.

#### Diff viewer and git staging

When the agent proposes file changes (or you open a diff), the diff viewer supports **patch-level** staging - select individual lines, split hunks, and stage or unstage everything at once. All keys are configurable in `.infer/keybindings.yaml` (category `diff_viewer`); the defaults:

| Key                 | Action                                                                        |
| ------------------- | ----------------------------------------------------------------------------- |
| `space` / `v`       | Start or clear a line-range selection within the current hunk                 |
| `a` / `u` / `enter` | Apply (stage/unstage) the selected lines - or the whole hunk if none selected |
| `s`                 | Split the current hunk into smaller, independently stageable blocks           |
| `]` / `[`           | Jump to the next / previous hunk                                              |
| `A`                 | Stage **all** changes (`git add -A`, including untracked files and deletions) |
| `U`                 | Unstage **all** changes (`git reset -q HEAD`)                                 |

Select a range with `space`/`v`, navigate, then apply to stage just those lines - or split a mixed hunk with `s` and stage each block separately. The footer hint reflects whether a selection is active, and hides `discard` when a staged file is selected (discard only applies to unstaged changes).

## Agent Modes

Toggle between modes anytime during chat using **Shift+Tab**.

| Mode                   | Tools                                    | Approval                            | Best For                                            |
| ---------------------- | ---------------------------------------- | ----------------------------------- | --------------------------------------------------- |
| **Standard** (Default) | All configured                           | Required for Write/Edit/Delete/Bash | General development, collaborative coding           |
| **Plan** (Read-Only)   | Read, Grep, Tree and read-only subagents | None                                | Code reviews, architecture analysis, planning       |
| **Auto-Accept** (YOLO) | All configured                           | None - immediate execution          | Trusted environments, rapid prototyping, automation |
| **Auto+Judge**         | All configured                           | An LLM judge answers every gate     | Unattended CI/headless runs that still want a gate  |

### Standard Mode

Full tool access with safety controls and approval prompts for sensitive operations.

```bash
infer chat
> "Refactor the authentication module to use environment variables"
# Agent analyzes code, proposes changes, requests approval before modifying
```

### Plan Mode

Analysis and planning without execution. Safe exploration of unfamiliar codebases.

```bash
infer chat
# Press Shift+Tab to switch to Plan Mode
> "How should I implement user authentication with JWT tokens?"
# Agent explores code structure and provides detailed plan
```

While planning, the agent can pause to ask you up to four multiple-choice clarifying questions with the [`AskUserQuestion`](#askuserquestion) tool, then fold your answers into the plan it submits for approval. The same tool is available in the other interactive modes, where the answers come back mid-task instead.

When the investigation spans several areas, the agent can fan it out to [local subagents](#local-subagents-agent-tool) that explore in parallel. In plan mode every subagent runs read-only, whatever its preset or tool allowlist says, so a delegated subagent may explore the repository but never change it. Ask for it directly ("Use 5 subagents to search this project for docs gaps and drift, then plan the fixes") and watch them work from the [background job list](#background-job-list) under the composer.

#### How mode instructions are delivered

Plan-mode instructions are **not** a system prompt. The system prompt at `message[0]` is byte-stable for the whole session - including across Shift+Tab mode switches - so the provider/local prompt (KV) cache keeps its prefix hits. The per-mode instructions ride along in the built-in `mode-change-reminder` ([`on_mode_change` trigger](#trigger-catalog)) that fires when the mode changes, substituted into its `{guidance}` placeholder.

`prompts.agent.mode_adjustment_plan` and `prompts.agent.mode_adjustment_auto` (env: `INFER_PROMPTS_AGENT_MODE_ADJUSTMENT_PLAN` / `_AUTO`) let you override that guidance. They ship empty - the built-in texts live in the mode-change reminder's guidance map. Precedence per mode, highest first:

| Priority    | Source                                                   |
| ----------- | -------------------------------------------------------- |
| 1 (Highest) | `guidance.<mode>` in your `reminders.yaml`               |
| 2           | `prompts.agent.mode_adjustment_<mode>` in `prompts.yaml` |
| 3 (Lowest)  | Built-in default guidance                                |

> **Deprecated names.** `prompts.agent.system_prompt_plan` / `system_prompt_auto` (env `INFER_PROMPTS_AGENT_SYSTEM_PROMPT_PLAN` / `_AUTO`) still load into the new fields with a deprecation warning; when both are set the new names win.
>
> **Trade-off:** since the mode-change reminder is the sole carrier of mode-specific instructions, setting `enabled: false` in `reminders.yaml` (or `INFER_REMINDERS_ENABLED=false`) means those instructions are never delivered. Tool restrictions still apply - only the guidance text is lost.

#### Approving a plan

When the plan is ready, the agent calls [`RequestPlanApproval`](#requestplanapproval); the chat TUI renders the saved plan in a dedicated panel and shows a status line - use the arrow keys to select an option and **Enter** to confirm. Three options are offered:

| Option                | Key           | Resulting mode  | Effect                                                                            |
| --------------------- | ------------- | --------------- | --------------------------------------------------------------------------------- |
| **Accept** (default)  | `Enter` / `y` | **Auto-Accept** | Executes the plan with no per-action approval prompts.                            |
| **Approve Each Step** | `s`           | **Standard**    | Executes the plan but prompts for approval on each Write/Edit/Delete/Bash action. |
| **Reject**            | `n`           | -               | Ends the session; reply with feedback and the agent re-iterates the plan.         |

> **The default Accept enables [Auto-Accept mode](#auto-accept-mode)** - unrestricted execution with no per-action approval. Pick **Approve Each Step** to accept the plan but keep the [Standard-mode](#standard-mode) approval gate on every action. The plan file stays on disk whichever you choose; rejecting a plan does not delete it.

### Auto-Accept Mode

Zero approval prompts for maximum speed. Use with caution in version-controlled environments.

```bash
infer chat
# Press Shift+Tab twice to switch to Auto-Accept Mode
> "Run the test suite, fix all failing tests, and commit the changes"
# Agent executes everything immediately
```

**Important for Auto-Accept:** Ensure clean git working tree and backups.

Because the per-action approval gate is off in this mode, the agent runs under a dedicated **destructive-action policy** delivered by the mode-change reminder (see [How mode instructions are delivered](#how-mode-instructions-are-delivered); override with `prompts.agent.mode_adjustment_auto`). It is told to stop and confirm before irreversible operations - deletes, `git push --force`, `git reset --hard`, dropping databases, `rm -rf`, publishing or releasing - to prefer the reversible path when no user is reachable, and never to print or publish a secret value. With reminders disabled this policy text is not delivered.

### Auto+Judge Mode

Autonomous like Auto-Accept, but the calls that would prompt a human are decided by an **LLM judge** instead of being waved through. Press **Shift+Tab** once more from Auto-Accept, or select the mode explicitly in headless runs:

```bash
infer headless --mode auto-with-judge "fix issue #42"
```

The judge is configured in its own [`judge.yaml`](/cli-judge-mode/#configuring-the-judge-judgeyaml) file, and the same gate is available in any mode via [`tools.safety.approval_behaviour: judge`](#approval-workflow). Both are off by default. See [Judge Mode](/cli-judge-mode/) for the verdict contract, `on_error` semantics, and observability.

### Headless Agent Stream Output

`infer headless <task>` runs the agent non-interactively and writes a **newline-delimited JSON (JSONL) stream** to stdout. Each line is one JSON object with a `type` discriminator, intended for programmatic consumers such as the [`infer-action` GitHub Action](/github-action/). The stream is additive: new `type` values may be introduced over time and consumers should ignore any `type` they do not recognize.

```bash
infer headless "Refactor the authentication module"
```

> **Secure by default.** A headless run executes in **standard** mode, so off-list or mutating actions are not auto-run - they are blocked (when no approver is reachable) or sent for IPC approval (under a channel manager). See [Headless secure-by-default](#headless-secure-by-default) to opt into more autonomy.

#### Output format (`--format`)

The output format is controlled by the `--format` flag (renamed from the legacy `--output-format`). It accepts four values:

- `json` (default) - newline-delimited JSON (JSONL), one compact object per line, suitable for programmatic consumption
- `json-pretty` - same per-turn stream as `json` with each object indented across multiple lines for human reading
- `ag-ui` - spec-compliant AG UI framed output with `TEXT_MESSAGE_START/CONTENT/END` framing and a fresh message id per turn. A `token_usage` custom event follows every LLM step. The terminal `RUN_FINISHED` event carries the session totals in its [`result`](#ag-ui-run-finished-result), or the [`cancelled` outcome](#ag-ui-cancelled-runs) when the turn was stopped. Resuming with `--session-id` opens the run with a [`MESSAGES_SNAPSHOT`](#ag-ui-resume-snapshot) of the restored conversation. Implied by [`--serve`](#serve-worker---serve)
- `text` - human-readable plain text output

```bash
# Default JSON output
infer headless "Refactor the authentication module"

# Human-readable pretty-printed JSON
infer headless "Analyze the codebase" --format json-pretty
```

> Machine consumers should keep using `json` for performance; `json-pretty` is for debugging and human inspection.

#### Stream event types

Every line in the `json` (or `json-pretty`) stream is a JSON object with a `type` discriminator. The stream is additive - new types may be introduced and consumers should ignore any they do not recognize.

| Type                   | When emitted                  | Description                                                                                                                                                                                                                                                                   |
| ---------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `info`                 | Once at start                 | Run metadata (model, session id)                                                                                                                                                                                                                                              |
| `assistant`            | Per turn                      | Assistant response with `content`, `reasoning_content`, `tool_calls`, `token_usage`                                                                                                                                                                                           |
| `tool`                 | Per tool call                 | Tool execution result. `content` holds the bare marshaled result (no legacy `Result of tool call:` / `Tool execution failed:` envelope). Structured `tool_execution` metadata (`tool_name`, `success`, `error`, `rejected`, `duration`) and the `failed` flag ride alongside. |
| `approval_request`     | When approval is needed       | Approval request metadata                                                                                                                                                                                                                                                     |
| `judge_verdict`        | Per judge decision            | Emitted under [judge mode](/cli-judge-mode/) or `approval_behaviour: judge` - tool, `decision`, `reason`, `model`, turn. Mirrored as a custom event in `ag-ui`.                                                                                                               |
| `computer_use_paused`  | On a `pause` control message  | Computer use was paused; carries the session `request_id` - see [pause and resume control](#pause-and-resume-control-ipc)                                                                                                                                                     |
| `computer_use_resumed` | On a `resume` control message | Computer use was resumed; carries the session `request_id`                                                                                                                                                                                                                    |
| `session_stats`        | Once at end                   | Token usage and cost summary (detailed below)                                                                                                                                                                                                                                 |
| `agent_error`          | Before stream starts          | Machine-readable error when the run fails before any turn (gateway unavailable, unknown model). For `ag-ui` format this is emitted as `RUN_ERROR`.                                                                                                                            |

##### One assistant line per LLM turn

Each completed LLM turn emits **exactly one** `assistant` line, in turn order - an empty turn (no content, no reasoning, no tool calls) emits none. That holds for a text-only turn the agent continued past because a `post_stream` **continuation nudge** fired (todo continuation, truncation continuation, empty-response continuation): the nudged turn keeps its own `assistant` line instead of being merged into the next turn's line. Consumers that walk the stream by turn can therefore treat `assistant` lines as the sequence of turns that produced output, and read the final answer from the `content` of the last `assistant` line.

The hidden system reminder a continuation nudge appends is **not** emitted to the stream. It exists only in the model-facing message history, so it never shows up as an `assistant` or `tool` line. Reminder text visible in a trace or under `logging.debug` is log output, not a stream line.

In the `ag-ui` format the same contract holds one level up: one `TEXT_MESSAGE_START` / `CONTENT` / `END` triple with a fresh message id per LLM turn, nudge-continued turns included.

**Exit codes:**

| Code | Meaning                     |
| ---- | --------------------------- |
| 0    | Task completed successfully |
| 1    | Task failed                 |
| 2    | Max turns exhausted         |

**Headless behavior:**

- **Subagent mode**: Headless runs always spawn subagents in `headless` mode, never tmux/interactive, regardless of `tools.agent.mode`.
- **Background tasks**: The run waits for in-flight background tasks (background shells, A2A tasks) before completing, bounded by `a2a.task.agent_mode_max_wait_seconds`.
- **Session rollover**: Long conversations automatically roll over into a new session id (session compact). A non-UUID `--session-id` is treated as a session-group key that follows these rollovers - useful for channel-based workflows.

#### Pause and resume control (IPC)

A host UI (the desktop app, or any process that owns the `infer headless` subprocess) can pause and resume an in-flight computer-use run by writing a control line to the agent's **stdin**, the same IPC pattern as `approval_response`:

```json
{ "type": "computer_use_control", "action": "pause" }
{ "type": "computer_use_control", "action": "resume" }
```

- Works with the `json`, `json-pretty`, and `ag-ui` formats, **with or without** `--require-approval`, and regardless of the [`computer_use.approval`](#computer-use-approval) level.
- **Pause** cancels the in-flight request and emits `computer_use_paused`.
- **Resume** restarts the run over the same conversation with a hidden `Please continue from where you left off.` message, and emits `computer_use_resumed`. The resume also clears the [cancellation the paused run carried](#ag-ui-cancelled-runs), so a pause and resume stays one successful run.
- A malformed line, an unknown `type`, or an unrecognized `action` is ignored (logged as a warning), so the stdin stream can carry `approval_response` and `computer_use_control` messages interleaved.

**Events out.** In the `json` / `json-pretty` stream both events are plain JSON lines carrying the session `request_id`:

```json
{ "type": "computer_use_paused", "request_id": "b7a1c3d2-..." }
{ "type": "computer_use_resumed", "request_id": "b7a1c3d2-..." }
```

In the `ag-ui` stream they arrive as `CUSTOM` events with the same names:

```json
{ "type": "CUSTOM", "name": "computer_use_paused", "value": { "request_id": "b7a1c3d2-..." } }
{ "type": "CUSTOM", "name": "computer_use_resumed", "value": { "request_id": "b7a1c3d2-..." } }
```

**Example.** Pause the run, then resume it a few seconds later:

```bash
{
  sleep 5
  echo '{"type":"computer_use_control","action":"pause"}'
  sleep 5
  echo '{"type":"computer_use_control","action":"resume"}'
} | infer headless --format json "Open the settings window and enable dark mode"
```

```json
{"type":"info","model":"...","session_id":"b7a1c3d2-..."}
{"type":"assistant","content":"Taking a screenshot to find the settings window..."}
{"type":"computer_use_paused","request_id":"b7a1c3d2-..."}
{"type":"computer_use_resumed","request_id":"b7a1c3d2-..."}
{"type":"assistant","content":"Continuing - clicking the appearance tab..."}
{"type":"session_stats","message":"Session complete","...":"..."}
```

#### Session stats summary line

When a session completes, the CLI emits a single `session_stats` line summarizing token usage and computed dollar cost for the run. This lets consumers report real run cost without re-implementing the per-model pricing table.

```json
{
  "type": "session_stats",
  "message": "Session complete",
  "timestamp": "2026-05-29T17:48:55+02:00",
  "model": "deepseek/deepseek-v4-flash",
  "prompt_tokens": 21000,
  "completion_tokens": 1260,
  "total_tokens": 22260,
  "requests": 7,
  "cost": { "input": 0.0021, "output": 0.0008, "total": 0.0029, "currency": "USD" }
}
```

**Fields:**

| Field               | Type   | Description                                                         |
| ------------------- | ------ | ------------------------------------------------------------------- |
| `type`              | string | Always `session_stats` for this line.                               |
| `message`           | string | Human-readable status, currently `Session complete`.                |
| `timestamp`         | string | RFC 3339 timestamp at which the line was emitted.                   |
| `model`             | string | Model used for the run. A single model is attributed per run.       |
| `prompt_tokens`     | number | Sum of input tokens across all requests in the run.                 |
| `completion_tokens` | number | Sum of output tokens across all requests in the run.                |
| `total_tokens`      | number | `prompt_tokens + completion_tokens`.                                |
| `requests`          | number | Number of LLM requests (turns that reported `usage`) in the run.    |
| `cost`              | object | Computed dollar cost for the run - see [Cost object](#cost-object). |

##### Cost object

| Field      | Type   | Description                                                                |
| ---------- | ------ | -------------------------------------------------------------------------- |
| `input`    | number | Cost attributed to `prompt_tokens` using the configured pricing table.     |
| `output`   | number | Cost attributed to `completion_tokens` using the configured pricing table. |
| `total`    | number | `input + output`.                                                          |
| `currency` | string | ISO 4217 currency code from `pricing.currency`. Defaults to `USD`.         |

When `pricing.enabled: false` (or pricing data is unavailable for the model), `input`, `output`, and `total` are all `0` while `currency` is still populated. The `cost` object is always present, giving consumers a stable schema.

**Behavior notes:**

- The line is **additive** - it does not replace any existing stream output.
- It is **emitted once** per run, at session completion (including on early errors).
- It is **always emitted in `agent` mode** - there is no flag to enable or disable it.
- Cost is attributed to a **single model per run**.
- Consumers should **ignore unknown `type` values** to remain forward-compatible.

##### AG-UI `RUN_FINISHED` result

In the `ag-ui` format the same totals ride on the terminal `RUN_FINISHED` event instead of a `session_stats` line. `result` carries the per-session totals, cumulative across the session (not just the current run):

```json
{
  "type": "RUN_FINISHED",
  "threadId": "b7a1c3d2-...",
  "runId": "9f4e1a0b-...",
  "result": {
    "inputTokens": 21000,
    "outputTokens": 1260,
    "cacheReadTokens": 18400,
    "totalToolCalls": 7,
    "cost": 0.0029,
    "lastInputTokens": 12800,
    "contextWindow": 128000
  }
}
```

| Key               | Type   | Description                                                                 |
| ----------------- | ------ | --------------------------------------------------------------------------- |
| `inputTokens`     | number | Total input tokens across the session.                                      |
| `outputTokens`    | number | Total output tokens across the session.                                     |
| `cacheReadTokens` | number | Tokens served from the prompt cache.                                        |
| `totalToolCalls`  | number | Tool calls issued across the session.                                       |
| `cost`            | number | Total session cost, in the configured currency.                             |
| `lastInputTokens` | number | Input tokens of the most recent request.                                    |
| `contextWindow`   | number | Model context window in tokens, omitted when the model's window is unknown. |

The event has **no `result`** when the run made no model request, so consumers must treat it as optional.

The same stats object is also streamed as a `CUSTOM` event named `token_usage` after every LLM step, before tool execution continues, so consumers can track cumulative usage while the run progresses. Its `value` keys match the `RUN_FINISHED` `result` above, including `contextWindow` being omitted when the model's window is unknown, and the event is not emitted until the session has made at least one model request:

```json
{
  "type": "CUSTOM",
  "name": "token_usage",
  "value": {
    "inputTokens": 21000,
    "outputTokens": 1260,
    "cacheReadTokens": 18400,
    "totalToolCalls": 7,
    "cost": 0.0029,
    "lastInputTokens": 12800,
    "contextWindow": 128000
  }
}
```

##### AG-UI cancelled runs

Every run is bracketed by `RUN_STARTED` and exactly one terminal `RUN_FINISHED` or `RUN_ERROR`. A **stopped** turn is not a failure: it ends as AG-UI 1.0 describes cancelled runs, a `RUN_FINISHED` carrying outcome `cancelled` and **no `result`**, rather than a `RUN_ERROR`:

```json
{
  "type": "RUN_FINISHED",
  "threadId": "b7a1c3d2-...",
  "runId": "9f4e1a0b-...",
  "outcome": "cancelled"
}
```

`RUN_ERROR` stays reserved for a run that actually failed (a panic, a gateway error, a worker that died mid-turn), so a host can tell "the user stopped this" apart from "this broke" without parsing error text.

A [computer-use pause](#pause-and-resume-control-ipc) cancels the in-flight request, so a paused run is a cancelled one. A later `computer_use_resumed` **clears** that cancellation - the pause and the resume stay **one successful run**, and the terminal event the host finally sees is an ordinary `RUN_FINISHED` with its `result`. Hosts should therefore treat `cancelled` as the outcome of the turn, not as a reason to tear down the thread.

The same outcome reaches [daemon](#daemon) clients that send an `interrupt` frame, since the worker's stdio stream and the daemon socket carry [identical frames](#shared-event-stream).

**For AG-UI consumers** (the [desktop app](/desktop/) sidecar, or any process hosting `infer headless --format ag-ui`): the per-step `token_usage` events stream the cumulative stats above, so live indicators stay current during the run instead of jumping once at `RUN_FINISHED`. Drive the context-percentage indicator from `lastInputTokens / contextWindow` - `lastInputTokens` is the live occupancy of the window, where `inputTokens` is a session-wide sum and will overshoot it. Hide the indicator when `contextWindow` is absent. Drive the cost indicator from `cost`, which is already the computed dollar total and needs no per-model pricing table on the client.

##### AG-UI computer-use activity and recording state

Under `--format ag-ui` the stream itself reports what a computer-use run is doing and whether a screen recording is up, so a host (the [desktop app](/desktop/) overlay and monitor, or any AG-UI client) renders them from standard events instead of reverse-engineering `Computer` tool arguments and `RecordStart` results.

**Computer-use activity.** Each pointer or keyboard action is written as an `ACTIVITY_SNAPSHOT` with `activityType` `computer_use`, keyed `computer_use:<toolCallId>`, **just before** the `Computer` tool performs it:

```json
{
  "type": "ACTIVITY_SNAPSHOT",
  "activityType": "computer_use",
  "messageId": "computer_use:call-1",
  "content": {
    "toolCallId": "call-1",
    "action": "click",
    "x": 812,
    "y": 344,
    "screenWidth": 1920,
    "screenHeight": 1080
  }
}
```

- Written for the pointer actions `move`, `click`, `double_click`, `triple_click` and the keyboard actions `type` and `key`. Keyboard actions carry no `x` and `y`.
- `x` and `y` are already scaled to **screen coordinates**, and `screenWidth`/`screenHeight` give the space they are relative to - an overlay can place a cursor marker without knowing the model's own resolution.
- The snapshot **replaces** the previous one with the same `messageId`, so a client keeps one live action entry per tool call.

**Recording state.** The `screenRecording` key of the [run state object](#shared-event-stream) carries `active`, and while a recording runs also where it writes and what it captures:

```json
{
  "type": "STATE_DELTA",
  "delta": [
    {
      "op": "add",
      "path": "/screenRecording",
      "value": {
        "active": true,
        "path": "/home/user/.infer/projects/my-app/tmp/media/recordings/session-1.mp4",
        "region": { "x": 0, "y": 0, "width": 1280, "height": 720 },
        "frameWidth": 1280,
        "frameHeight": 720
      }
    }
  ]
}
```

| Field                        | Value                                                                    |
| ---------------------------- | ------------------------------------------------------------------------ |
| `active`                     | Whether a recording is running right now - the only field when it is off |
| `path`                       | The file the recording is being written to                               |
| `region`                     | The captured region, `{x, y, width, height}`                             |
| `frameWidth` / `frameHeight` | The dimensions of the frames the recorder captures                       |

`region` and `frameWidth`/`frameHeight` are in the **frame space the recorder captures** - the same space screenshots and their annotations use - so a client can overlay the region without rescaling. This is the same state key the [daemon](#shared-event-stream) carries, because a session worker is an `infer headless --format ag-ui` process.

The full per-event reference lives with the CLI source, in [`docs/ag-ui-output.md`](https://github.com/inference-gateway/cli/blob/main/docs/ag-ui-output.md).

#### Writing the result to a file (`--result-file`)

`infer headless` accepts a `--result-file <path>` flag that **atomically** writes the final assistant message and the run outcome as JSON to `<path>` on exit. The [Agent tool](#local-subagents-agent-tool) uses it to harvest the result of an **interactive** (tmux pane) subagent only - headless subagents report each turn on stdout instead, see [`--keep-alive`](#keeping-the-session-alive---keep-alive). The flag is useful on its own whenever a script needs the final answer as a file rather than by parsing the stdout stream.

```bash
infer headless "Summarize the open PRs" --result-file /tmp/result.json
```

#### Keeping the session alive (`--keep-alive`)

`infer headless --keep-alive <task>` does not exit when the task turn ends. It keeps the process and the session alive and reads further work from stdin: each [`run_agent_input`](#serve-worker---serve) frame runs as **another turn in the same session**, so follow-ups keep the accumulated context instead of starting over. Every finished turn is reported as one `subagent_turn` line on stdout, and closing stdin (**EOF**) ends the run.

```bash
infer headless --keep-alive --session-id sub-1 "Review the auth module" <<'FRAMES'
{"type":"run_agent_input","input":{"messages":[{"id":"m2","role":"user","content":"Also cover the token refresh path"}]}}
FRAMES
```

Each turn prints a line like:

```json
{
  "type": "subagent_turn",
  "final_assistant": "...",
  "success": true,
  "session_id": "sub-1",
  "done": true,
  "stats": { "tools_succeeded": 3, "tools_failed": 0, "input_tokens": 1200, "output_tokens": 80 }
}
```

The line is the [`--result-file`](#writing-the-result-to-a-file---result-file) JSON shape plus `"type": "subagent_turn"` and `done`, so a consumer that already parses result files needs no new parser.

`--format text` and [`--serve`](#serve-worker---serve) are **rejected** with `--keep-alive`: the first has no frame to carry a turn line, and the second is already a long-lived worker with its own AG-UI protocol. This is the shape the [Agent tool](#local-subagents-agent-tool) spawns its async **headless** subagents in - see [headless keep-alive lifecycle](#headless-keep-alive-lifecycle).

#### Resuming a session (`--session-id`)

`infer headless --session-id <id>` loads a persisted conversation before the agent starts, letting you resume a previous session. The session must have been persisted by a [storage backend](#conversation-management) (`storage.enabled: true`).

```bash
# Find session IDs from saved conversations
infer conversations list

# Resume a specific session
infer headless "Continue the refactoring" --session-id abc-123-def
```

**Session ID resolution:**

- A literal **UUID** is used as-is.
- Any **non-UUID** value is treated as a **session group key** and resolved through the session rollover chain to the latest session in that group.

**Fallback:** If the session cannot be loaded (e.g. the ID does not exist or storage is disabled), the CLI prints a visible notice and starts a new session under the requested ID.

The same flag is also available on [`infer chat --session-id`](#resuming-a-session---session-id) for resuming chat sessions interactively.

##### AG-UI resume snapshot

Under `--format ag-ui`, resuming an existing conversation emits a **`MESSAGES_SNAPSHOT` of the restored conversation right after `RUN_STARTED`**, before the turn produces anything of its own. A host that reconnects to a thread can therefore render the prior history from the stream itself, with no side channel and no separate conversation-read command:

```bash
infer headless --format ag-ui --session-id abc-123-def "Continue the refactoring"
```

```json
{"type":"RUN_STARTED","threadId":"abc-123-def","runId":"9f4e1a0b-..."}
{"type":"MESSAGES_SNAPSHOT","messages":[
  {"id":"msg-1","role":"user","content":"Refactor the authentication module"},
  {"id":"msg-2","role":"assistant","content":"Reading the module first.","toolCalls":[{"id":"call-1","type":"function","function":{"name":"Read","arguments":"{\"file_path\":\"auth.go\"}"}}]},
  {"id":"msg-3","role":"tool","toolCallId":"call-1","content":"package auth\n..."}
]}
```

Each entry of the stored conversation maps to one snapshot message:

| Field        | On                 | Value                                                             |
| ------------ | ------------------ | ----------------------------------------------------------------- |
| `id`         | every message      | The stored message id                                             |
| `role`       | every message      | `user`, `assistant`, `system` or `tool`                           |
| `content`    | every message      | The message's text content                                        |
| `toolCalls`  | assistant messages | The tool calls that message issued, omitted when it issued none   |
| `toolCallId` | tool messages      | The id of the assistant tool call this result answers             |
| `error`      | tool messages      | The failure message, present only when that tool execution failed |

- Only a **restored** conversation produces a snapshot - a fresh session (an unknown `--session-id`, or none at all) starts with `RUN_STARTED` and no snapshot, so hosts should treat it as optional.
- The event is the same `MESSAGES_SNAPSHOT` the [daemon](#shared-event-stream) answers `new_session` / `resume_conversation` with, because a session worker is an `infer headless --format ag-ui` process.

#### Serve worker (`--serve`)

`infer headless --serve` is a **long-lived worker**: one process per thread instead of one process per prompt. It takes **no task argument** and implies `--format ag-ui`. It reads app frames from stdin and runs **one agent turn per `run_agent_input` frame**, writing each turn to stdout as one AG-UI run - `RUN_STARTED` with `threadId` set to the conversation id, then exactly one `RUN_FINISHED` or `RUN_ERROR`.

```bash
infer headless --serve --session-id abc-123-def
```

This is the shape the [daemon](#daemon) spawns its [session workers](#what-the-daemon-runs) in, so a host that owns the subprocess speaks the same vocabulary as a daemon client: app frames in with a lowercase `type`, AG-UI events out with an uppercase `type`, no envelope and no translation.

```json
{
  "type": "run_agent_input",
  "input": {
    "messages": [{ "id": "m1", "role": "user", "content": "Refactor the authentication module" }]
  }
}
```

```json
{"type":"RUN_STARTED","threadId":"abc-123-def","runId":"9f4e1a0b-..."}
{"type":"TEXT_MESSAGE_START","messageId":"msg-4","role":"assistant"}
{"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-4","delta":"Reading the module first."}
{"type":"TEXT_MESSAGE_END","messageId":"msg-4"}
{"type":"RUN_FINISHED","threadId":"abc-123-def","runId":"9f4e1a0b-...","result":{"...":"..."}}
```

**Stdin frames:**

| Frame                    | Behaviour                                                                                                                                                                                                                                                                                             |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_agent_input`        | Runs one turn from `input.messages` (the new messages only - the worker owns the history). Sent mid-turn it is **queued** and drained into the running turn; anything still queued when a turn ends starts the next turn. An `input.resume` answers a pending interrupt, and an empty `input` resumes |
| `interrupt`              | Cancels the running turn, which ends with `RUN_FINISHED` outcome [`cancelled`](#ag-ui-cancelled-runs)                                                                                                                                                                                                 |
| `browser_result`         | Answers a `browser_command` the worker wrote on stdout - see [browser tools without a port](#browser-tools-without-a-port)                                                                                                                                                                            |
| `approval_response`      | Unchanged: `tool_call_id`, `approved`, `scope` for a pending tool call                                                                                                                                                                                                                                |
| `user_question_response` | Unchanged: the collected `AskUserQuestion` answers, or a dismissal                                                                                                                                                                                                                                    |
| `computer_use_control`   | Unchanged: `action` is `pause` or `resume` - see [pause and resume control](#pause-and-resume-control-ipc)                                                                                                                                                                                            |

Only the **first** run of a resumed session opens with a [`MESSAGES_SNAPSHOT`](#ag-ui-resume-snapshot); later runs on the same worker start with `RUN_STARTED` alone, because the host already has the history.

##### Browser tools without a port

With [`browser_use.backend: extension`](/opentask/#cli-bridge-protocol) a serve worker **binds no port**. A browser tool writes a `browser_command` line on **stdout** and waits for the `browser_result` line with the same `id` on **stdin**, so the host relays both to the extension - exactly what the daemon does for its own workers. Only a daemon binds the extension port.

##### Shutdown

Closing stdin (**EOF**) lets the running turn and any queued `run_agent_input` frames finish, then shuts the worker down together with the gateway, MCP servers and containers it started. For a fast stop send `{"type":"interrupt"}` first, then close stdin: the running turn ends `cancelled` and the worker drains immediately instead of waiting the turn out.

## Daemon

`infer daemon` is the long-lived hub every external client connects to. One process owns the outside world: the AG-UI WebSocket binding that the [desktop app](/desktop/) and the [OpenTask browser extension](/opentask/) dial into, the [messaging channels](/cli-channels/), the [scheduler](/cli-scheduling/), and the heartbeat. Clients do not spawn `infer headless` themselves - they ask the daemon for a thread, and the daemon runs it.

```text
desktop app -----+
                 +--> AG-UI WebSocket binding ----+
extension -------+                                |
                                                  +--> infer daemon --> session worker per thread
Telegram channel ----------------------------------+                    (project dir + conversation)
                                                  |
scheduler / heartbeat ----------------------------+
                                                  |
                                                  +--> one log: ~/.infer/logs/daemon-<date>.log
```

> **Note:** The binding, the session workers and the client handshake described here are the daemon hub. Older CLI builds connect the extension directly to `infer chat` and spawn one `infer headless` per desktop prompt; see [Connecting the extension](/opentask/#connecting-to-the-daemon) for what changes on the client side.

### What the daemon runs

| Subsystem           | What it does                                                                                                                                                                |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Binding**         | Serves `ws://127.0.0.1:<port>/ws` (default `52789`) for the extension and the desktop app, behind an `Origin` check and a token. On its own `daemon.binding.enabled` switch |
| **Session workers** | One long-lived [`infer headless --serve`](#serve-worker---serve) process per thread, spawned in the thread's project directory, speaking AG-UI over stdio                   |
| **Channels**        | Telegram and other [messaging channels](/cli-channels/), each sender mapped to its own thread                                                                               |
| **Scheduler**       | Cron jobs from the [local scheduler backend](/cli-scheduling/), run as threads instead of one-off processes                                                                 |
| **Heartbeat**       | Periodic self-checks and the artifact poller that pulls conversations back from the [GitHub backend](/cli-scheduling/#github-backend)                                       |
| **Logging**         | Collects worker, one-shot job, channel and connection logs into [one daemon log](#the-daemon-log)                                                                           |

### Starting the daemon

```bash
infer daemon
```

The daemon boots with the binding alone - channels, the scheduler and the heartbeat are optional and enabled through configuration. The binding has its own switch in the `daemon.yaml` sidecar, so a client that never touches the browser (the desktop app, a channel) can reach the daemon without enabling `browser_use`:

```yaml
# ~/.infer/daemon.yaml
binding:
  enabled: true
  port: 52789 # optional; falls back to browser_use.extension.port
  token: <shared secret> # optional; falls back to browser_use.extension.token
```

The binding listens when `daemon.binding.enabled` is `true`, or - as before - when `browser_use.enabled` is `true` with `backend: extension`. Port and token resolve the same way in both cases: the `daemon.yaml` value wins, and `~/.infer/browser_use.yaml` stays the fallback.

```yaml
# ~/.infer/browser_use.yaml
enabled: true
backend: extension
extension:
  port: 52789
  token: <shared secret; infer init seeds one>
```

With neither token set the daemon refuses to boot rather than serving an unauthenticated socket - set `daemon.binding.token`, or `browser_use.extension.token` as the fallback. The **browser extension relay** is separate from the binding: it attaches only with `browser_use.enabled` and `backend: extension`. With the binding on through `daemon.yaml` alone, clients get threads but browser tools have nothing to drive.

Every field has an `INFER_DAEMON_`-prefixed environment override:

| Variable                       | Maps to                  |
| ------------------------------ | ------------------------ |
| `INFER_DAEMON_BINDING_ENABLED` | `daemon.binding.enabled` |
| `INFER_DAEMON_BINDING_PORT`    | `daemon.binding.port`    |
| `INFER_DAEMON_BINDING_TOKEN`   | `daemon.binding.token`   |

A standalone `infer chat` or `infer headless` with `backend: extension` reaches the browser as a daemon client (`client: "browser"` in the handshake), and starts `infer daemon` itself on the first browser call when nothing is listening on the port. Neither binds the port, so nothing has to hand it back.

The daemon needs the binding port to be free: if another process already holds it, the boot **fails** with the port named instead of retrying until it frees. Stop whatever holds it, or change the port.

### Threads

A **thread** is a project directory plus a conversation id, and it runs in exactly one session worker:

- A client opens a thread with `new_session` or `resume_conversation`, passing `project_dir` and the thread options (model, agent mode, system prompt and custom instruction overrides, sandbox directories, max turns). The daemon answers with a `MESSAGES_SNAPSHOT` of the restored history.
- `threadId` on the thread's runs is its conversation id, so a client can list and resume the same conversations the CLI resumes.
- Every agent turn is **one run**: `RUN_STARTED`, then exactly one `RUN_FINISHED` or `RUN_ERROR`. A stopped turn ends as `RUN_FINISHED` with outcome `cancelled`.
- Several clients may subscribe to one thread; each of them sees the same frames.
- Idle workers exit after a timeout, and a worker that crashes mid-turn has its open run closed with `RUN_ERROR`.

### Clients and the handshake

The client dials in and sends the first frame within 5 seconds:

```json
{
  "type": "browser_hello",
  "token": "<shared secret>",
  "client": "extension",
  "extension_version": "1.9.2",
  "protocol_version": 1
}
```

```json
{ "type": "browser_hello_ack", "protocol_version": 1 }
```

- `client` is `extension`, `desktop`, or `browser` for a CLI process that connects only to drive the browser; an absent or unknown value counts as `extension`. There is **one** extension connection - a new one replaces the previous, because MV3 service workers restart at will - and any number of `desktop` and `browser` connections.
- The handshake is lenient: any valid-token hello is accepted, a hello without a `protocol_version` is logged as a warning, and a client that sees a version it does not support shows an "update" state rather than refusing to connect.
- Only `chrome-extension://`, `moz-extension://`, `safari-web-extension://` or absent `Origin` headers are accepted.

### Shared event stream

Every transport carries the same vocabulary, with no envelope around it: AG-UI events go **out** with an uppercase `type`, app frames come **in** with a lowercase `type`. The frames on a session worker's stdio (`infer headless --format ag-ui`) and on the daemon socket are identical, so a client written against one works against the other.

**AG-UI events out:**

| Event                                                              | When                                                                                                                                                      |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RUN_STARTED`                                                      | A turn starts; `threadId` is the conversation id                                                                                                          |
| `MESSAGES_SNAPSHOT`                                                | Answer to `new_session` / `resume_conversation`; also emitted [right after `RUN_STARTED` on a resumed run](#ag-ui-resume-snapshot)                        |
| `TEXT_MESSAGE_START` / `TEXT_MESSAGE_CONTENT` / `TEXT_MESSAGE_END` | Assistant or user message, role on START                                                                                                                  |
| `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END`             | A tool call the assistant issued                                                                                                                          |
| `TOOL_CALL_RESULT`                                                 | The raw JSON execution result of a tool call                                                                                                              |
| `STATE_SNAPSHOT` / `STATE_DELTA`                                   | The run state object - `todos`, `usage`, `backgroundTasks` and [`screenRecording`](#ag-ui-computer-use-activity-and-recording-state)                      |
| `ACTIVITY_SNAPSHOT`                                                | Progress a client keeps as one entry per `messageId`: `agent_status`, `judge_verdict`, [`computer_use`](#ag-ui-computer-use-activity-and-recording-state) |
| `RUN_FINISHED`                                                     | The turn ended; outcome [`cancelled`](#ag-ui-cancelled-runs) when it was stopped, `result` carries the [session totals](#ag-ui-run-finished-result)       |
| `RUN_ERROR`                                                        | The turn failed, or its worker died                                                                                                                       |

**CUSTOM events out**, each with a `name` and a `value`:

| Name                                           | Value                                                                                      |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `approval_request`                             | `tool_name`, `tool_args`, `tool_call_id` - a tool call is waiting                          |
| `approval_resolved`                            | `tool_call_id` - somebody else answered it                                                 |
| `user_question_request`                        | `tool_call_id` and the `AskUserQuestion` form's `questions`                                |
| `agent_status`                                 | A local A2A agent starting: `name`, `state`, `message`, pull progress `done`/`total`       |
| `background_tasks`                             | `running` plus the `jobs` array (id, kind, label, description, detail, status)             |
| `queued_message`                               | A background job landed its note into the conversation                                     |
| `token_usage`                                  | The same cumulative stats as `RUN_FINISHED.result`, after each model request               |
| `judge_verdict`                                | Per [judge](/cli-judge-mode/) decision: tool, `decision`, `reason`, `model`, turn          |
| `computer_use_paused` / `computer_use_resumed` | `request_id` - answer to a `computer_use_control` frame                                    |
| `browser_extension_status`                     | `connected`, `extension_version`, `protocol_version` - on extension connect and disconnect |
| `browser_use_paused` / `browser_use_resumed`   | `request_id` - answer to a `browser_use_control` frame                                     |

**App frames in:**

| Frame                                                       | Purpose                                                                    |
| ----------------------------------------------------------- | -------------------------------------------------------------------------- |
| `new_session` / `resume_conversation`                       | Open a thread in a project directory                                       |
| `user_message`                                              | Send a message into the thread; queued when the agent is busy              |
| `interrupt`                                                 | Stop the streaming turn, which ends `cancelled`                            |
| `approval_response`                                         | `tool_call_id`, `approved`, `scope` - the decision for a pending tool call |
| `user_question_response`                                    | The collected answers, or a dismissal                                      |
| `computer_use_control`                                      | `action` is `pause` or `resume`, for computer use                          |
| `list_conversations` / `list_history`                       | Browse the project's stored conversations                                  |
| `list_skills` / `list_models` / `select_model` / `set_mode` | Inspect and change what the thread runs with                               |
| `tool_request` / `tool_result`                              | Run a tool directly, scoped to a project directory                         |

Unknown `type` and `name` values are ignored on both sides, so the vocabulary stays additive. The full per-event reference lives with the CLI source, in [`docs/ag-ui-output.md`](https://github.com/inference-gateway/cli/blob/main/docs/ag-ui-output.md).

### Approvals

Approvals have one contract on every transport. The daemon sends CUSTOM `approval_request` to every client of the thread, and the **first** `approval_response` wins - it goes to the worker, and the thread's other clients get CUSTOM `approval_resolved` with the same `tool_call_id` so they can clear their prompt. A decision made in the terminal resolves the panel's prompt the same way. A response for an unknown or already-answered `tool_call_id` is ignored.

### Browser use through the daemon

There is one real browser, so only the daemon binds the extension port. `browser_command` lines from the session workers are routed to the extension connection and each `browser_result` goes back to its worker by `id`. Commands from every source - session workers, the desktop app and `browser` clients - are serialized rather than interleaved on the same tab, and a command a client posts on the socket is answered only on that connection. Every non-extension client is told the state of that connection by the [`browser_extension_status`](/opentask/#browser-extension-status) frame - on connect, and on each attach or detach. With no extension connected, browser tools fail with `no browser extension connected on port <port>`; a command the extension does not finish in time fails with `timed out waiting for the browser extension to <action>`. The command and result shapes are documented in the [OpenTask bridge protocol](/opentask/#browser-commands-daemon-extension).

### The daemon log

One file holds the whole picture: `~/.infer/logs/daemon-<date>.log` (`logging.dir` moves the directory). Everything the daemon starts logs JSON to **stderr** and keeps no log file of its own while supervised - session workers and the one-shot job runs (scheduled fires, heartbeat ticks) alike - and the daemon collects that stderr into its own log, each line tagged with the `project_dir`, `conversation_id` and `worker_pid` it came from. There is no per-process `app-<date>.log` to correlate.

Also in the same file:

| Logged                                                     | Fields                                                           |
| ---------------------------------------------------------- | ---------------------------------------------------------------- |
| Client connects and disconnects                            | `client`, `extension_version`, `protocol_version`                |
| The browser extension relay's attach and detach            | `extension_version`, `protocol_version` from the hello           |
| Routing errors (unknown thread, dead worker, no extension) | `project_dir` and `conversation_id` of the thread they concerned |
| Channel, scheduler and heartbeat lines                     | `project_dir` and `conversation_id` when they act for a thread   |

Logs are not streamed to clients, so `tail` the file when debugging a client:

```bash
tail -f ~/.infer/logs/daemon-$(date +%Y-%m-%d).log
```

## Computer Use

GUI automation and visual understanding capabilities for interacting with applications and desktop environments.

### Display Server Support

Automatic display server detection - no configuration needed:

| Platform    | Supported Servers              | Notes                                  |
| ----------- | ------------------------------ | -------------------------------------- |
| **macOS**   | Quartz (native), X11 (XQuartz) | Quartz automatically detected and used |
| **Linux**   | X11, Wayland                   | Auto-detection handles both protocols  |
| **Windows** | Native                         | No configuration required              |

Display server type is automatically detected at runtime. No manual configuration required.

### Computer Use Tools

Computer use exposes two tools: **`Computer`**, an action-based desktop tool, and **`GetLatestFrame`**, registered whenever a frame source exists (screenshot streaming, or a directory source under `vision.sources`).

`Computer` takes an `action`:

| Action                                                    | Description                                                                                                             |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `accessibility`                                           | Preferred first observation. Returns compact `{role,label,state,bbox}` elements from the accessibility tree. Read-only. |
| `press`                                                   | Presses the first element whose `label` matches exactly, via its accessibility action - the cursor never moves.         |
| `screenshot`                                              | Captures the screen, or a native-resolution `region`. Use when the accessibility tree is empty or insufficient.         |
| `cursor`                                                  | Reports the current pointer position.                                                                                   |
| `move`, `click`, `double_click`, `triple_click`, `scroll` | Pointer control.                                                                                                        |
| `type`, `key`                                             | Type text or send key combinations (Ctrl+C, Cmd+V).                                                                     |

**Targets.** `accessibility` and `press` accept an optional `target`: `frontmost` (default), `dock`, `menubar`, `pid:<N>`, `app:<name>`, or a bare application name. Application identifiers are `pid:<N>` on every platform - the macOS bundle ID form is gone, as are the older `GetFocusedApp` and `ActivateApp` tools.

**Coordinate space.** Accessibility bounding boxes use the same frame coordinate space as screenshots and pointer actions, so an element's center can be passed straight to a `click`.

**Pressing beats clicking.** `press` is the reliable way to activate dock items, buttons, and menu titles: it drives the element's own accessibility action instead of aiming the pointer at a coordinate, and it takes no screenshot.

**macOS Accessibility permission.** The AX tools return elements only after `infer` is granted permission in **System Settings > Privacy & Security > Accessibility**. Without it - or on a helper crash, timeout, or unavailable tree - the tool returns screenshot fallback guidance to the agent rather than failing the run. The macOS bridge is pure Go (PureGo calling CoreFoundation, CoreGraphics, and AXUIElement) running in a short-lived helper process; there is no cgo, Swift, or Objective-C.

**Linux and Windows.** AT-SPI and UIA providers are not implemented yet: `accessibility` and `press` report `unsupported; use screenshot` there, while every other `Computer` action works normally.

**Clipboard.** Clipboard support is text-only; image clipboard was removed with the cgo-free rewrite.

### Screen Recording

Two tools record the screen to an MP4 file (H.264, `yuv420p` - it plays in browsers and QuickTime):

- **`RecordStart`** - begins a recording of the whole primary screen, a single window, or a region, and returns the output path and the captured rectangle. Recording continues in the background.
- **`RecordStop`** - finalizes the recording and returns the path, duration and file size.

Typical uses are an unattended audit trail of a computer-use run, and recording a tutorial or a bug reproduction while the agent drives the desktop.

> **Disabled by default.** While `computer_use.recording.enabled` is `false`, neither tool is registered, so they cost zero prompt tokens. Recording captures whatever is on your screen - that is why it is opt-in.

Recording lives under `recording` in `.infer/computer_use.yaml` (project) or `~/.infer/computer_use.yaml` (user). It works on its own - `computer_use.enabled` is not required.

```yaml
# .infer/computer_use.yaml
recording:
  enabled: true # register the RecordStart/RecordStop tools (default: false)
  max_duration: 120 # seconds; the recording stops and finalizes itself at this cap
  output_dir: '' # empty = recordings/ under the media root
  framerate: 24 # frames per second
```

Every key has an `INFER_COMPUTER_USE_RECORDING_`-prefixed environment variable that takes precedence over the YAML value.

| Config key                            | Environment variable                        | Type   | Default                                                  | Notes                                                                  |
| ------------------------------------- | ------------------------------------------- | ------ | -------------------------------------------------------- | ---------------------------------------------------------------------- |
| `computer_use.recording.enabled`      | `INFER_COMPUTER_USE_RECORDING_ENABLED`      | bool   | `false`                                                  | Feature flag - both tools are absent from the LLM payload when `false` |
| `computer_use.recording.max_duration` | `INFER_COMPUTER_USE_RECORDING_MAX_DURATION` | int    | `120`                                                    | Seconds; the recording finalizes itself at the cap. Must be positive   |
| `computer_use.recording.output_dir`   | `INFER_COMPUTER_USE_RECORDING_OUTPUT_DIR`   | string | `recordings/` under the [media root](#media-directories) | Where MP4s are written, as `<timestamp>.mp4`; created on first use     |
| `computer_use.recording.framerate`    | `INFER_COMPUTER_USE_RECORDING_FRAMERATE`    | int    | `24`                                                     | Capture frame rate. Must be positive                                   |

**Requirements.** The recorder shells out to **ffmpeg with libx264 and the platform's screen grabber**, found on `PATH` - for example `brew install ffmpeg` (macOS) or `apt install ffmpeg` (Debian/Ubuntu). A minimal ffmpeg build without the encoder or the grabber cannot record.

| Platform    | Grabber        | Extra requirements                                                                                                                       |
| ----------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **macOS**   | `avfoundation` | Your terminal app needs **Screen Recording** permission, plus **Accessibility** for `window` mode (System Settings > Privacy & Security) |
| **Linux**   | `x11grab`      | An X11 session. Wayland is not supported yet                                                                                             |
| **Windows** | `gdigrab`      | None                                                                                                                                     |

**Capture modes.** `RecordStart` takes an optional `mode`:

- `screen` (default) - the entire primary display.
- `window` - a single window, selected by `window`: `frontmost` (default), `app:<name>`, `pid:<number>`, or a bare application name. This is the same target syntax as the [`Computer` tool](#computer-use-tools).
- `region` - a rectangle, given as `region` with `x`, `y`, `width` and `height` in the frame coordinate space (the same space as `Computer` screenshots and accessibility bounding boxes).

```json
{ "mode": "screen" }
{ "mode": "window", "window": "app:Safari" }
{ "mode": "region", "region": { "x": 0, "y": 80, "width": 1280, "height": 720 } }
```

`window` mode captures the window's bounds **at the moment the recording starts**: anything drawn over that area is recorded too, and moving the window afterwards does not move the capture.

**Behaviour.** `RecordStart` returns the file path and the captured rectangle and leaves ffmpeg running in the background. `RecordStop` takes no arguments and returns the path, duration and size.

- **One recording at a time, machine wide.** While ffmpeg runs, the recording holds `~/.infer/run/screen-recording.lock`. A `RecordStart` from any other `infer` process - another chat, a Desktop app session, a channel run - fails with an error naming the owning pid, and the active recording is left alone. `RecordStop` with nothing recording is an error too.
- **Self-finalizing.** A recording stops and finalizes itself at `max_duration` (120s by default); `RecordStop` still returns that file. One that stops on its own - the cap, an ffmpeg exit, or a stop from `/tasks` - queues a note asking the agent to collect it with `RecordStop`.
- **Clean exit.** On normal exit, Ctrl+C or SIGTERM the CLI finalizes an active recording and leaves no ffmpeg process behind. Call `RecordStop` in the same session; channel and scheduled runs each start a fresh process.
- **Visibility.** The chat status bar shows a `REC` badge while a recording runs, and the recording is listed in [`/tasks`](#tasks-view) under Screen Recordings as a background job of kind `recording`.
- `infer tools execute` refuses both tools.

**Approval.** `RecordStart` **always requires approval**, except in auto-accept (`auto`) mode:

- In chat you get the usual approval prompt.
- In [headless mode](#headless-agent-stream-output) it follows [`approval_behaviour`](#approval-workflow): sent over IPC when the run has `--require-approval`, decided by the [LLM judge](/cli-judge-mode/) in `auto-with-judge` mode, otherwise blocked.

`RecordStop` follows [`computer_use.approval`](#computer-use-approval): under `never` (the default) and `destructive` it runs without a prompt - it counts as an observation - and only `always` asks.

**Headless and AG-UI hosts.** A running recording is a background job, so `infer headless` **waits for it** (up to `a2a.task.agent_mode_max_wait_seconds`, 300s by default) instead of exiting and cutting it short. How the stop request reaches the recording depends on the caller:

- **Desktop app and other stdin hosts** send a `user_message` line on stdin, which reaches `RecordStop` in the same process.
- **Channel, scheduled and heartbeat runs** do not forward follow-up messages into a running process, so there a recording runs until `max_duration` and the agent collects the file afterwards.

With `--format ag-ui` (the format the [desktop app](/desktop/) consumes):

| Event                                                                                  | Payload                                                                                                                                      |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `STATE_DELTA` on `screenRecording` - on `RecordStart`, `RecordStop`, or `max_duration` | `active`, plus `path`, `region` and `frameWidth`/`frameHeight` while it runs - see [state](#ag-ui-computer-use-activity-and-recording-state) |
| `STATE_DELTA` on `backgroundTasks`                                                     | The recording appears among `jobs` with kind `recording`                                                                                     |
| `approval_request`                                                                     | `RecordStart` when the run has `--require-approval`; without an approver it is blocked                                                       |

A recording still running when the run ends is finalized **after** the terminal event, so no `screenRecording` patch with `active: false` follows it - clear the indicator on `RUN_FINISHED` or `RUN_ERROR`.

### Screenshot Tool Features

**Streaming Mode:**

- Maintains circular buffer of recent screenshots
- Configurable buffer size (default: 60)
- Configurable capture interval (default: 3 seconds)
- Efficient memory management
- Fast access to recent captures

**Image Optimization:**

- Automatic resolution scaling to fit the target box (default: 1024x768), preserving the aspect ratio so coordinates map back to the screen
- JPEG compression with configurable quality (default: 85%)
- Reduces bandwidth and storage requirements

**Region Selection:**

- Full screen capture
- Custom region coordinates (x, y, width, height)
- Multiple monitor support

### Visualizing Agent Activity

The [desktop app](/desktop/) is the visualization layer for computer use: it shows the live screen monitor, the on-screen action overlay, and the approval prompts driven by [`computer_use.approval`](#computer-use-approval). Run the CLI from the desktop app to watch a computer-use run as it happens.

The CLI's own macOS floating window was removed. The `computer_use.floating_window` config section and the `INFER_COMPUTER_USE_FLOATING_WINDOW_*` environment variables no longer exist - existing config files that still carry those keys keep loading, the keys are simply ignored.

### Computer Use Configuration

Computer use has its own file, `.infer/computer_use.yaml`, seeded by `infer init`. It is off by default; missing keys fall back to the in-code defaults shown here.

```yaml
# .infer/computer_use.yaml
---
enabled: true
approval: never # never | destructive | always
screenshot:
  enabled: true
  target_width: 1024
  target_height: 768
  format: jpeg
  quality: 85
  streaming_enabled: true # also registers the GetLatestFrame tool
  capture_interval: 3
  buffer_size: 60
  temp_dir: '' # empty = screenshots/ under the media root
rate_limit:
  enabled: true
  max_actions_per_minute: 60
  window_seconds: 60
```

### Computer Use Approval

`computer_use.approval` decides which computer-use actions go through the approval gate before they run. It applies to both interactive chat and [`infer headless`](#headless-agent-stream-output).

| Value         | Behavior                                                                                                                |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `never`       | Default. Computer-use actions bypass the approval gate and run immediately.                                             |
| `destructive` | The observations `accessibility`, `screenshot`, and `cursor` bypass approval; `press` and the input actions require it. |
| `always`      | Every computer-use action requires approval.                                                                            |

```yaml
# .infer/computer_use.yaml
approval: destructive
```

```bash
export INFER_COMPUTER_USE_APPROVAL=always
```

- **Env override:** `INFER_COMPUTER_USE_APPROVAL` takes precedence over the YAML value.
- **Fail closed:** an unknown value is rejected at config load with a validation error, and if one ever reaches the approval policy it is treated as `always` rather than silently bypassing the gate.
- Under `destructive` or `always`, a headless run needs an approver reachable over IPC - otherwise the gated calls are blocked, same as any other approval-requiring tool. See [Headless secure-by-default](#headless-secure-by-default).

### Safety and Rate Limiting

**Rate Limiting:**

- Default: 60 actions per minute
- Prevents runaway automation
- Configurable threshold

**Safety Controls:**

- Approval prompts in Standard Mode
- Auto-approve in YOLO mode
- Activity logging for audit trails
- Command execution monitoring

**Best Practices:**

- Use Standard Mode for initial exploration
- Enable logging for debugging
- Set appropriate rate limits
- Monitor activity logs
- Test in safe environments first

### Example Use Cases

```bash
infer chat
> "Take a screenshot and analyze the error dialog"
> "Click the Submit button in the center of the screen"
> "Type 'Hello World' and press Enter"
> "Switch to the Terminal app and run ls command"
> "Find the Save button and click it"
```

## Frame Sources and Vision Annotation

Frame sources feed images to the agent, and a pluggable annotator turns each frame into text so that cheap or text-only models (DeepSeek, small local models) can still work from what is on screen or in front of a camera.

- The built-in `screen` source is computer-use screenshot streaming, registered whenever screenshot streaming is on.
- **Directory sources** watch a folder and serve the newest image file by modification time - whatever your camera or capture process writes there.
- `GetLatestFrame` reads the current frame from a source; `ImageDecode` handles arbitrary images.

The annotator produces a scene summary plus a numbered element list with bounding boxes: a vision model gets the image, a text-only model gets the text. Annotation is a side-call through the gateway, so any vision model the gateway serves works - including a fully local one through Ollama, which keeps annotation offline.

```yaml
# .infer/config.yaml
vision:
  annotator:
    enabled: true # default: false
    model: anthropic/claude-haiku-4-5-20251001 # any vision model your gateway serves
    max_tokens: 4096
    timeout: 120
  sources:
    camera-front:
      type: directory
      path: .infer/frames/front # wherever your camera process writes frames
      prompt: 'Describe the workbench and any visible part numbers.' # optional per-source override
      retention:
        max_files: 100
        max_age: 24h
```

With `vision.annotator.enabled: true`, `GetLatestFrame` defaults to annotated text output and `ImageDecode` adds a text description to the image it returns - no per-model configuration. `ImageDecode` itself is always available; vision-capable models receive the image directly (see [Vision-capable models and ImageDecode](#vision-capable-models-and-imagedecode)). `retention` prunes the source directory after reads.

Not to be confused with the gateway-side `gateway.vision_enabled` flag, which is unrelated.

## Tools & Capabilities

When tools are enabled, LLMs have access to a comprehensive suite across multiple categories.

### Tool Categories

| Category              | Tools                                                                              | Description                                                                                                                                                                                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **File System**       | Read, Write, Edit, MultiEdit, Delete, Tree, Grep                                   | File operations and search with safety controls                                                                                                                                                                                                              |
| **Command Execution** | Bash, BashOutput, KillShell, ListShells, Wait                                      | Allow-listed shell execution (including `gh` for GitHub), background shell control, and blocking wait for conditions                                                                                                                                         |
| **Web**               | WebSearch, WebFetch                                                                | Internet research and content fetching                                                                                                                                                                                                                       |
| **Workflow**          | TodoWrite, Schedule, RequestPlanApproval, AskUserQuestion, RequestApproval, Memory | Task tracking, cron jobs, plan-mode approval, clarifying questions, judge-rejection escalation, and persistent cross-session memory                                                                                                                          |
| **A2A Integration**   | A2A_QueryAgent, A2A_SubmitTask, A2A_QueryTask                                      | Delegate to external specialized agents - see [A2A](/a2a/)                                                                                                                                                                                                   |
| **Local Subagents**   | Agent                                                                              | Fan out short-lived local subagents in parallel - see [Local Subagents](#local-subagents-agent-tool)                                                                                                                                                         |
| **Computer Use**      | Computer, GetLatestFrame, RecordStart, RecordStop                                  | Accessibility-tree reads, presses, screenshots, and pointer/keyboard control - see the Computer Use section above; screen recording is opt-in via `computer_use.recording.enabled`, see [Screen Recording](#screen-recording)                                |
| **Image**             | ImageGeneration, ImageEdit, ImageVariation                                         | Generate, edit, and vary images using the configured image model - independent of the chat session model                                                                                                                                                     |
| **Audio**             | TextToSpeech, TextToMusic, TextToSFX                                               | Local speech synthesis and voice cloning - opt-in via `text_to_speech.enabled`, see [Text-to-Speech](/cli-text-to-speech/); music composition and sound-effect generation through the gateway - opt-in via `text_to_music.enabled` and `text_to_sfx.enabled` |
| **Video**             | TextToVideo, CreateAvatar                                                          | Prompt and lip-synced avatar renders through the gateway, plus avatar-library creation - opt-in via `text_to_video.enabled` and `text_to_video.create_avatar`, see [Text-to-Video and Avatars](/cli-text-to-video/)                                          |
| **MCP**               | `MCP_<server>_<tool>`                                                              | Dynamically registered tools from MCP servers - see [MCP](/mcp/)                                                                                                                                                                                             |
| **Custom**            | Any name you give them                                                             | Tools you add yourself with one YAML manifest per tool, run as a program with the arguments as JSON on stdin - see [Custom Tools](#custom-tools)                                                                                                             |

### File System Tools

#### Read

Read a file from the local filesystem with an optional line range. Handles text files and PDFs.

- **Parameters**: `file_path` (required, absolute or relative), `limit` (default 2000 lines), `offset` (default 1)
- **Approval**: not required (read-only)
- **Notes**: lines longer than 2000 characters are truncated; output is returned in `cat -n` format

A missing file does not return a bare `NOT_FOUND`. The error appends up to five candidate paths so the next call can correct a typo or a wrong directory instead of retrying the same path: siblings of the nearest existing directory ranked by name similarity, plus - when no sibling carries the missing base name - files with that base name found under the [allowed sandbox directory](#file-sandbox) containing it.

```text
NOT_FOUND: /home/user/project/internal/tools/reader.go

Did you mean one of:
  /home/user/project/internal/tools/read.go
  /home/user/project/internal/tools/read_test.go
  /home/user/project/internal/tools/registry.go
```

#### Write

Write content to a file on disk. Overwrites the existing file at the given path.

- **Parameters**: `file_path` (required, absolute), `content` (required)
- **Approval**: required by default
- **Notes**: if the file exists, the Read tool must have been used first; respects configured path exclusions (`.git/`, `*.env`, `.infer/`)

#### Edit

Perform an exact string replacement in a single file.

- **Parameters**: `file_path` (required), `old_string` (required - must match exactly and be unique unless `replace_all` is set), `new_string` (required - must differ from `old_string`), `replace_all` (default `false`)
- **Approval**: required by default
- **Notes**: the file must have been Read at least once in the conversation; indentation must be preserved exactly

#### MultiEdit

Apply a sequence of edits to a single file atomically - either all succeed or none are applied.

- **Parameters**: `file_path` (required), `edits` (required array; each item has `old_string`, `new_string`, optional `replace_all`)
- **Approval**: required by default
- **Notes**: edits are applied in order, each operating on the result of the previous one - plan them so earlier edits don't invalidate later matches

#### Delete

Delete a file or directory. Wildcards are supported when enabled.

- **Parameters**: `path` (required - supports patterns like `*.txt` or `temp/*`), `recursive` (default `false`), `force` (default `false`), `format` (`text` or `json`)
- **Approval**: required by default
- **Notes**: restricted to the current working directory for safety

#### Tree

Display a directory tree, similar to the Unix `tree` command.

- **Parameters**: `path` (default `.`), `max_depth` (1-10, default 3), `max_files` (1-1000, default 100), `respect_gitignore` (default `true`), `show_hidden` (default `false`), `format` (`text` or `json`)
- **Approval**: not required
- **Notes**: uses the system `tree` binary when available, otherwise falls back to a built-in implementation

#### Grep

Powerful regex search across files. Uses `ripgrep` when available, otherwise a built-in Go implementation.

- **Parameters**: `pattern` (required regex), `path` (default cwd), `glob` (e.g. `*.ts`, `**/*.tsx`), `type` (e.g. `go`, `py`, `rust`), `output_mode` (`content` | `files_with_matches` | `count`, default `files_with_matches`), `-i`, `-n`, `-A`, `-B`, `-C`, `multiline`, `head_limit`
- **Approval**: not required
- **Backend**: configurable via `tools.grep.backend` (`auto` | `ripgrep` | `go`)
- **Notes**: respects `.gitignore`; auto-excludes `.git`, `node_modules`, `.infer`, `vendor`, `dist`, `build`, `target`

### Command Execution

#### Bash

Execute a bash command that matches the active mode's **allowed-list**. Matching is **default-deny**: a command auto-runs only when it matches the allowed-list for the current [agent mode](#agent-modes). Anything unmatched falls through to an approval prompt in chat, or is rejected with an actionable hint in [headless mode](#headless-agent-stream-output). There is no separate deny list.

- **Parameters**: `command` (required), `format` (`text` or `json`)
- **Approval**: configurable via `tools.bash.require_approval`

##### Per-mode allowed-list

The allowed-list is configured **per [agent mode](#agent-modes)** under `tools.bash.mode.<mode>.allow` in [`~/.infer/tools.yaml`](#tool-configuration). The effective list for a mode is `mode.all.allow` (the every-mode baseline) **unioned** with that mode's own entries:

```yaml
# ~/.infer/tools.yaml
tools:
  bash:
    enabled: true
    require_approval: false
    mode:
      all: # baseline applied in every mode
        allow:
          - ls( .*)?
          - pwd( .*)?
          - git status( .*)?
          - git diff( .*)?
      plan: # read-only analysis - usually adds nothing
        allow: []
      standard: # default interactive mode
        allow:
          - npm (install|test|run).*
      auto: # Auto-Accept / YOLO mode
        allow:
          - .* # unrestricted sentinel
```

- **Default-deny.** Out of the box only `mode.auto` ships the `.*` sentinel; `mode.plan` and `mode.standard` add nothing on top of `mode.all`, so they reduce to the read-only baseline. GitHub _writes_ (`gh issue/pr create|edit|comment`), `git push`, and `git commit` are **not** in the defaults - they fall through to approval until you add them.
- **Full-command matching.** Each entry matches the **whole** command, so a bare token like `gh` allows only `gh` - never `gh issue list`. Opt into arguments explicitly with a pattern (`gh issue.*`, `npm (install|test|run).*`); the default entries use a `( .*)?` suffix to allow trailing arguments.
- **The `.*` sentinel** means _unrestricted_: any single command runs and the clean-command guard below is skipped. It is the default for `mode.auto` (chat's [Auto-Accept mode](#auto-accept-mode), toggled with Shift+Tab) and is an explicit opt-in - **never** a headless default.

##### Clean-command guard

For every mode except the `.*` sentinel, each command passes a **clean-command guard** before the allowed-list is consulted. The guard rejects, regardless of the list:

- **Command substitution** - `$(...)`, backticks, `<(...)`, `>(...)`.
- **Multi-command chains and pipelines** - a top-level `|`, `&&`, `||`, `;`, `&`, or newline. Operators inside quotes don't count, so `jq '.a | .b'` stays a single command. (This closes the old `echo x | xargs rm` prefix hole.)
- **File-write redirections** - `>` and `>>`. Benign stream redirects (`2>&1`, `>/dev/null`) are stripped first and remain allowed.
- **Dangerous `find` actions** - `-exec`, `-delete`, and the like. A bare `find` for read-only discovery is fine.
- **Environment-variable leaks** - a printing or publishing command (`echo`, `printf`, `gh issue|pr create|comment|edit`) may not expand `$VAR`. So `echo $AWS_SECRET_ACCESS_KEY` is blocked, while `ls $DIR` stays allowed. A single-quoted or escaped `$` is treated literally.

A rejected command returns an actionable hint naming what tripped the guard; the model is told to stop and ask, or use an allowed alternative, rather than retry the same call.

##### Append-only override (CI)

The `mode.all` baseline takes an **append-only override** so CI can add a few safe commands without rewriting config or shipping `.*`:

```bash
# Comma- or newline-separated; the env var wins over the flag
export INFER_TOOLS_BASH_ALLOW_APPEND="git commit,git push"

# Flag form
infer headless "Release the changelog" --tools-bash-allow-append "git commit,git push"
```

The extra commands merge onto `mode.all.allow`, so they auto-run in every mode. There is no replace override - the old `tools.bash.whitelist.commands` key, the `INFER_TOOLS_BASH_WHITELIST_COMMANDS[_APPEND]` env vars, and the `--tools-bash-whitelist-commands*` flags were removed.

#### BashOutput, KillShell, ListShells

Background-shell management. These tools are only registered when `tools.bash.background_shells.enabled: true`.

- **BashOutput** - `bash_id` (required), `filter` (optional regex). Returns only new output since the last read.
- **KillShell** - `shell_id` (required). Sends SIGTERM, then SIGKILL after 5 seconds if the shell doesn't exit.
- **ListShells** - no parameters. Lists all running and recently completed background shells with their IDs, state, and elapsed time.

#### Wait

Block inside a single tool execution until a condition is met (shells exit, file event, or check command succeeds), then return once with the outcome. Waiting costs zero chat completions - no LLM round-trip per iteration.

- **Approval**: not required (passive utility tool - no side effects)
- **Enabled by default**: yes (gated by `tools.wait.enabled`)
- **Common parameters**: `timeout_seconds` (required, number) - maximum time to wait in seconds, bounded by the config ceiling (`tools.wait.max_timeout_seconds`, default 600)

**Return value:** A structured result with `condition` (the condition type), `reason` (outcome: `condition_met`, `timeout`, `cancelled`, `check_failed`, `no_shells`, `error`, `not_allowed`), `elapsed_seconds` (time spent waiting), and condition-specific details (exit codes, last output, shell states) - included even on failure so the model can see why the wait ended.

**Cancellation:** Pressing Esc in chat or session cancel interrupts the wait immediately (reason: `cancelled`).

##### Condition: Shells (`condition=shells`)

Block until the given background shell ID(s) exit. When `shell_ids` is omitted, waits for all currently running background shells.

- **Parameters:** `shell_ids` (optional, array of strings) - specific shell IDs to wait for. Omit to wait for all pending background shells.
- **Returns:** Exit codes and tail output (last 4096 bytes) for each shell.

**Use cases:**

- Wait for a long-running build or test to finish
- Wait for multiple parallel background tasks to complete
- Coordinate sequential steps that depend on background work

##### Condition: File (`condition=file`)

Block until a file path is created, modified, or removed (uses fsnotify for efficient inotify/FSEvents-based watching).

- **Parameters:** `path` (required, string) - file path to watch. `event` (optional, string, enum: `create`, `modify`, `remove`, `any`) - file event to wait for. Default: `any`.
- **Behavior:** For `create`: checks if the file already exists first (returns immediately if so). Watches the parent directory for the target filename. Uses OS-native file system notifications (no polling).

**Use cases:**

- Wait for a download to complete
- Wait for a log file to be created
- Wait for a lock file to be removed
- Wait for a build artifact to appear

##### Condition: Command (`condition=command`)

Re-run a check command server-side at a fixed interval until it exits 0. The check command goes through the same bash allow-list as the Bash tool.

- **Parameters:** `command` (required, string) - check command to re-run until it exits 0. `pending_exit_codes` (optional, array of numbers) - non-zero exit codes that mean "still pending, keep polling". Any other non-zero exit ends the wait immediately with reason `check_failed`.
- **Behavior:** First run happens immediately (no initial delay). Subsequent runs at `command_poll_interval_ms` interval (default 2s). Each run has a 30-second per-execution timeout. Not available on Windows (requires bash).
- **Exit code classification:**
  - Exit 0: `condition_met` - success
  - Exit in `pending_exit_codes`: keep polling
  - Exit non-zero (not in pending): `check_failed` - ends immediately
  - No pending_exit_codes specified: keep polling on any non-zero exit

**Use cases:**

- Wait for a service to become healthy: `curl -sf localhost:8080/health`
- Wait for CI to complete: `gh pr checks` with `pending_exit_codes=[8]`
- Wait for a file to contain specific content: `grep -q 'ready' /var/log/app.log`
- Wait for a port to open: `nc -z localhost 3000`

##### Configuration

```yaml
# ~/.infer/tools.yaml
tools:
  wait:
    enabled: true # Enable/disable the Wait tool
    max_timeout_seconds: 600 # Maximum allowed timeout (ceiling)
    command_poll_interval_ms: 2000 # Poll interval for command condition (ms)
```

##### Examples

```text
# Wait for background build to finish
Wait(condition=shells, shell_ids=["build-1"], timeout_seconds=300)

# Wait for a file to be created
Wait(condition=file, path="/tmp/result.json", event="create", timeout_seconds=60)

# Wait for service health
Wait(condition=command, command="curl -sf http://localhost:8080/health", timeout_seconds=120)

# Wait for CI checks with pending exit codes
Wait(condition=command, command="gh pr checks 792 --repo inference-gateway/cli", pending_exit_codes=[8], timeout_seconds=600)

# Wait for all background shells
Wait(condition=shells, timeout_seconds=300)
```

### Web Tools

#### WebSearch

Search the web via DuckDuckGo or Google.

- **Parameters**: `query` (required), `engine` (`duckduckgo` | `google`, defaults to the configured engine), `limit` (1-50, defaults to configured `max_results`), `format` (`text` or `json`)

```yaml
# ~/.infer/tools.yaml
tools:
  web_search:
    enabled: true
    default_engine: duckduckgo
    max_results: 10
    engines: [duckduckgo, google]
    timeout: 10
```

#### WebFetch

Fetch content from an allowed URL. Optionally save the response to disk.

- **Parameters**: `url` (required), `format` (`text` or `json`), `download` (default `false` - when `true`, saves under [`.infer/artifacts/<session-id>/`](#artifacts-directory))
- **Notes**: only allowed domains can be fetched; responses are cached (default 15-minute TTL)

```yaml
# ~/.infer/tools.yaml
tools:
  web_fetch:
    enabled: true
    allowed_domains:
      - golang.org
      - github.com
      - agents.md
    safety:
      max_size: 8192
      timeout: 30
    cache:
      enabled: true
      ttl: 3600
```

### Image Tools

ImageGeneration, ImageEdit, and ImageVariation all write their PNG to the session artifacts directory - `.infer/artifacts/<session-id>/image-<timestamp>.png` - so the images produced by a conversation stay grouped together. See [Artifacts directory](#artifacts-directory).

#### ImageEdit Tool

Edit an existing image and save the result as a PNG under `.infer/artifacts/<session-id>/`. The chat model calls the tool when the user asks to edit an image; the tool reads the input image from a local file path and sends a plain one-off request to `/v1/images/edits` using the configured image model - no system prompt, no tools, independent of the model selected for the chat session.

**Parameters:**

- `image` (required): Local file path of the image to edit
- `prompt` (required): Text description of the desired edit
- `mask` (optional): Local file path to a PNG whose fully transparent areas (alpha = 0) mark the editable region; all other pixels are preserved exactly. Must be a PNG with the same dimensions as the input image. Non-PNG paths are rejected by tool validation. Omit to let the model localize the change from the prompt alone - useful for models that repaint areas the user did not ask to change, and required for dall-e-2 edits without transparency.
- `quality` (optional): `auto` (default), `low`, `medium`, `high`, or `standard`
- `size` (optional): `1024x1024` (default), `1536x1024`, or `1024x1536`

**Configuration:**

```yaml
# ~/.infer/tools.yaml
tools:
  image_edit:
    enabled: true
    model: openai/gpt-image-2
    require_approval: false
```

**Example with mask:**

```json
{
  "image": "photo.png",
  "prompt": "replace the sky with a sunset",
  "mask": "sky-mask.png"
}
```

#### ImageVariation Tool

Create a variation of an existing image and save the result as a PNG under `.infer/artifacts/<session-id>/`. The chat model calls the tool when the user asks for a variation; the tool reads the input image from a local file path and sends a plain one-off request to `/v1/images/edits` using the configured image model - no system prompt, no tools, independent of the model selected for the chat session.

**Parameters:**

- `image` (required): Local file path of the image to base the variation on
- `size` (optional): `1024x1024` (default), `1536x1024`, or `1024x1536`

**Configuration:**

```yaml
# ~/.infer/tools.yaml
tools:
  image_variation:
    enabled: true
    model: openai/gpt-image-2
    require_approval: false
```

#### Vision-capable models and ImageDecode

Vision-capable models (those with the `vision` label in the [model picker](#model-picker-labels)) see pasted or @-referenced images **natively** - the image data is sent directly to the model, which can inspect it without a separate tool call. For these models, the **ImageDecode tool is hidden from the advertised tool list** to avoid steering the model toward a text annotation when it can see the image directly.

The tool **remains executable** if called - a model that invokes it from conversation history or right after a model switch gets a working tool, not an error. Text-only models keep the tool and the "use ImageDecode to inspect it" note unchanged.

### Audio Tools

#### TextToSpeech Tool

Synthesize speech from text with a local TTS engine and save it as a WAV file. The chat model calls the tool when the user asks to say something aloud or to clone a voice; synthesis shells out to llama.cpp's `llama-tts` binary running Qwen3-TTS GGUF models, fully offline. **Disabled by default** - while `text_to_speech.enabled` is `false`, the tool definition is not sent to the LLM at all.

**Parameters:**

- `text` (required): The text to speak
- `voice_sample` (optional): Bare file name of a WAV of the target speaker (~10-30s of clean speech) to clone, resolved against the working directory first and then the [voice samples library](/cli-text-to-speech/#the-voice-samples-library) at `~/.infer/models/tts/samples/`; a name found in neither fails with an error listing both paths tried
- `output_path` (optional): Destination WAV; defaults to a timestamped file under `text_to_speech.output_dir` (`tts/` in the [media root](#media-directories))

**Configuration:**

```yaml
text_to_speech:
  enabled: true
```

See [Text-to-Speech](/cli-text-to-speech/) for prerequisites, the full configuration reference, model presets, and voice-cloning guidance.

#### TextToMusic Tool

Compose a music clip from a text prompt and save it as an MP3 file. The chat model calls the tool when the user asks for background music, a loop, or a jingle. Generation goes through the gateway's Music API (`POST /v1/audio/music`) using the configured `provider/model` - the CLI holds no provider key, the gateway does, so requests show up in gateway logs and traces. **Disabled by default** - while `text_to_music.enabled` is `false`, the tool definition is not sent to the LLM at all.

**Parameters:**

- `prompt` (required): Description of the music - genre, mood, instruments, tempo
- `seconds` (optional): Clip length in seconds; omitted lets the provider pick a length that fits the prompt
- `instrumental` (optional): `true` to guarantee the clip has no vocals
- `output_path` (optional): Bare file name (no directories, no absolute paths) for the generated MP3, written inside `text_to_music.output_dir`; defaults to a timestamped `music-*.mp3`

The clip is always MP3 - the format the gateway's music providers serve (ElevenLabs offers mp3, opus, and pcm, not wav). To place it elsewhere, compose first and copy the returned file.

**Configuration:**

```yaml
text_to_music:
  enabled: true
  # model: elevenlabs/music_v2_5 # gateway provider/model id
  # output_dir: ~/.infer/projects/<project-slug>/tmp/media/music
  require_approval: false # optional; unset = no approval, like the image tools
```

Every key also has an `INFER_TEXT_TO_MUSIC_`-prefixed environment variable that takes precedence over the config file:

| Config key                       | Environment variable                   | Type   | Default                                             | Notes                                                                                       |
| -------------------------------- | -------------------------------------- | ------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `text_to_music.enabled`          | `INFER_TEXT_TO_MUSIC_ENABLED`          | bool   | `false`                                             | Feature flag - must be `true` for the `TextToMusic` tool to reach the LLM                   |
| `text_to_music.model`            | `INFER_TEXT_TO_MUSIC_MODEL`            | string | `elevenlabs/music_v2_5`                             | Gateway `provider/model` id; a bare model name fails validation once the feature is enabled |
| `text_to_music.output_dir`       | `INFER_TEXT_TO_MUSIC_OUTPUT_DIR`       | string | `music/` under the [media root](#media-directories) | Where generated MP3s are written                                                            |
| `text_to_music.require_approval` | `INFER_TEXT_TO_MUSIC_REQUIRE_APPROVAL` | bool   | unset (no approval)                                 | Tri-state: unset keeps the tool's own default, an explicit value pins the policy either way |

**Gateway requirements:** the music endpoint is part of the gateway's Audio API, so the gateway must run with `AUDIO_ENABLED=true` and hold credentials for the provider behind `model` (an ElevenLabs API key for the default). The CLI-managed local gateway is started with `AUDIO_ENABLED=true` automatically when `text_to_music.enabled` is on, and an already-running instance without the Audio API is restarted. Point the CLI at an externally managed gateway and you set `AUDIO_ENABLED=true` and the provider key there yourself.

A gateway without the endpoint, or a provider that rejects the request, fails the tool call with a one-line error naming the configured model (`music generation with elevenlabs/music_v2_5 failed: ...`). The agent run still completes and no partial file is left behind.

#### TextToSFX Tool

Generate a short sound effect or ambience clip from a text prompt and save it as a WAV file. The chat model calls the tool when the user asks for a whoosh, a click, a riser or room tone - non-speech audio that `TextToSpeech` (it would read the words aloud) and `TextToMusic` (it composes songs) cannot cover. Generation goes through the gateway's [SFX API](/api-reference/#sound-effects) (`POST /v1/audio/sfx`) using the configured `provider/model` - the CLI holds no provider key, the gateway does, so requests show up in gateway logs and traces. **Disabled by default** - while `text_to_sfx.enabled` is `false`, the tool definition is not sent to the LLM at all.

**Parameters:**

- `prompt` (required): Description of the sound - the event or atmosphere and its character (a whoosh, a click, a riser, room tone, distant thunder)
- `seconds` (optional): Clip length in seconds, `0.5`-`30`; omitted lets the provider pick a length that fits the prompt
- `loop` (optional): `true` for a clip that loops seamlessly - useful for ambience beds
- `output_path` (optional): Bare file name (no directories, no absolute paths) for the generated WAV, written inside `text_to_sfx.output_dir`; defaults to a timestamped file

The same `output_path` rule as [TextToMusic](#texttomusic-tool) applies: the clip always lands in the configured output directory. To place it elsewhere, generate first and copy the returned file.

**Configuration:**

```yaml
text_to_sfx:
  enabled: true
  # model: elevenlabs/eleven_text_to_sound_v2 # gateway provider/model id
  # output_dir: ~/.infer/projects/<project-slug>/tmp/media/sfx
  require_approval: false # optional; unset = no approval, like the image tools
```

Every key also has an `INFER_TEXT_TO_SFX_`-prefixed environment variable that takes precedence over the config file:

| Config key                     | Environment variable                 | Type   | Default                                           | Notes                                                                                       |
| ------------------------------ | ------------------------------------ | ------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `text_to_sfx.enabled`          | `INFER_TEXT_TO_SFX_ENABLED`          | bool   | `false`                                           | Feature flag - must be `true` for the `TextToSFX` tool to reach the LLM                     |
| `text_to_sfx.model`            | `INFER_TEXT_TO_SFX_MODEL`            | string | `elevenlabs/eleven_text_to_sound_v2`              | Gateway `provider/model` id; a bare model name fails validation once the feature is enabled |
| `text_to_sfx.output_dir`       | `INFER_TEXT_TO_SFX_OUTPUT_DIR`       | string | `sfx/` under the [media root](#media-directories) | Where generated WAVs are written                                                            |
| `text_to_sfx.require_approval` | `INFER_TEXT_TO_SFX_REQUIRE_APPROVAL` | bool   | unset (no approval)                               | Tri-state: unset keeps the tool's own default, an explicit value pins the policy either way |

**Gateway requirements:** the SFX endpoint is part of the gateway's Audio API (gateway v0.54.0 or newer), so the gateway must run with `AUDIO_ENABLED=true` and hold credentials for the provider behind `model` (an ElevenLabs API key for the default). The CLI-managed local gateway is started with `AUDIO_ENABLED=true` automatically when `text_to_sfx.enabled` is on, and an already-running instance without the Audio API is restarted. Point the CLI at an externally managed gateway and you set `AUDIO_ENABLED=true` and the provider key there yourself.

A gateway without the endpoint, or a provider that rejects the request, fails the tool call with a one-line error naming the configured model (`sfx generation with elevenlabs/eleven_text_to_sound_v2 failed: ...`). The agent run still completes and no partial file is left behind.

### Video Tools

#### TextToVideo Tool

Render a short video clip and save it as an MP4. The chat model calls the tool when the user asks for a video clip or for an avatar to say something. Rendering goes through the gateway's Videos API (`POST /v1/videos`, polled with `GET /v1/videos/{id}` and downloaded from `GET /v1/videos/{id}/content`) using the configured `provider/model` - the CLI holds no provider key, the gateway does. **Disabled by default** - while `text_to_video.enabled` is `false`, the tool definition is not sent to the LLM at all, because avatar renders send the user's face and voice to a third-party provider.

Two modes:

- **Prompt render** - a text prompt, optionally with a portrait used as the first frame, rendered with `text_to_video.model`.
- **Avatar render (lip-sync)** - a portrait plus a `.wav` or `.mp3` clip, rendered with `text_to_video.avatar_model` so the face speaks the audio.

**Parameters:**

- `prompt` (required for a prompt render): Description of the clip - subject, action, camera, mood
- `avatar` (optional): Name of an avatar folder in the [avatar library](/cli-text-to-video/#the-avatar-library) at `~/.infer/avatars/`, or a local image file, used as the portrait. With `audio` it is the portrait to lip-sync (first image in sort order); without `audio` a library avatar is sent as [reference images](/cli-text-to-video/#reference-images-in-prompt-renders) instead, while a bare image file stays the first frame
- `audio` (optional): Local path to a `.wav` or `.mp3` clip to lip-sync; providing it selects the avatar render mode and requires a portrait
- `output_path` (optional): Bare file name (no directories, no absolute paths) for the generated MP4, written inside `text_to_video.output_dir`; defaults to a timestamped file

**Configuration:**

```yaml
text_to_video:
  enabled: true
  # model: elevenlabs/veo-3.1-fast-generate-001 # prompt renders
  # avatar_model: elevenlabs/creatify-aurora # lip-synced avatar renders
  # size: '' # "widthxheight" passthrough
  # output_dir: ~/.infer/projects/<project-slug>/tmp/media/video
  # timeout: 900
  # poll_interval: 5
  # create_avatar: false # register the CreateAvatar tool as well
  require_approval: false # optional; unset = no approval, like the image tools
```

**Gateway requirements:** the gateway must run with `VIDEOS_ENABLED=true` (gateway v0.54.0 or newer) and hold credentials for the provider behind the configured models. The CLI-managed local gateway is started with `VIDEOS_ENABLED=true` automatically while `text_to_video.enabled` is on; an externally managed gateway is your responsibility.

The portrait and the audio clip travel in one request, so together they must fit the gateway's 10 MiB request body limit, and `creatify-aurora` renders 480p or 720p keeping the portrait's aspect ratio.

See [Text-to-Video and Avatars](/cli-text-to-video/) for the full configuration reference, the `INFER_TEXT_TO_VIDEO_*` environment variables, the avatar library layout, and `infer avatars`.

#### CreateAvatar Tool

Build an avatar folder at `~/.infer/avatars/<name>/` from a photo - the agent-side twin of [`infer avatars create`](/cli-text-to-video/#managing-avatars). It stores the photo as the primary image and generates extra views of the same face through the gateway's image edit API using `tools.image_edit.model`, so a portrait the agent just generated, a selfie sent over a channel, or a photo in the project can become an avatar without leaving the chat.

**Opt-in twice.** The tool is registered only when both `text_to_video.enabled` and `text_to_video.create_avatar` (`INFER_TEXT_TO_VIDEO_CREATE_AVATAR`) are `true`; `create_avatar` defaults to `false`. It **requires approval by default** - unlike the other media tools - and an explicit `text_to_video.require_approval` overrides that either way.

**Parameters:**

- `name` (required): Avatar name, which becomes the folder name under `~/.infer/avatars/`
- `photo` (required): Bare file name of the source photo, looked up in the working directory and then in the [session artifacts directory](#artifacts-directory); absolute paths and `..` are rejected
- `angles` (optional): Which extra views to generate - defaults to both three-quarter angles, left/right profiles are available, and `[]` stores the photo only, with no image-edit call
- `quality` (optional): Image quality passed to the image edit API; defaults to `high`
- `size` (optional): Size of the generated views; defaults to `1024x1536`

It **never overwrites** an existing avatar - a name already in the library fails the call - and there is no delete counterpart, so the agent cannot remove an avatar. A failed view generation removes the half-built folder.

> **Privacy:** generating views sends the photo to the image-edit provider (OpenAI by default). Before anything is stored or uploaded, a JPEG is turned upright per its EXIF orientation and re-encoded without its metadata, so camera and GPS tags never reach the library or a provider. PNG and WebP pass through unchanged.

### GitHub Operations

There is **no built-in GitHub tool**. The agent performs all GitHub work - issues, pull requests, releases, repository metadata, and the raw API - through the [`gh` CLI](https://cli.github.com/) run via the [Bash](#bash) tool.

```bash
# Issues and pull requests
gh issue view 123
gh issue list --state open
gh pr create --title "fix: handle nil channel" --body "Closes #123"
gh pr diff 456

# Raw API (read-only / GET)
gh api repos/inference-gateway/cli/issues
gh api user --jq .login
```

**Requirements:** `gh` must be installed and authenticated. It uses the standard `gh` credential chain - run `gh auth login`, or set `GITHUB_TOKEN` (or `GH_TOKEN`). No separate token configuration exists anymore.

#### Default gh allowed-list

GitHub operations run through Bash, so they obey the [Bash allowed-list](#command-allow-listing). The default `mode.all` baseline auto-approves common **read-only** `gh` commands only:

| Auto-approved by default | Examples                                                                            |
| ------------------------ | ----------------------------------------------------------------------------------- |
| Read-only reads          | `gh issue list`, `gh pr view 5`, `gh pr diff`, `gh repo view`, `gh release view v1` |
| Auth status              | `gh auth status`                                                                    |
| Search                   | `gh search issues kind:bug`, `gh search code "func main"`                           |
| Read-only project boards | `gh project list`, `gh project view 3`, `gh project item-list 3`                    |

**GitHub writes and destructive operations are deliberately left off the defaults.** They are **not** auto-approved - they fall through to the standard approval prompt (in chat) or are blocked (in headless mode) until you add them to an allowed-list:

- **Issue / PR writes** - `gh issue create|edit|comment`, `gh pr create`.
- **Project writes** - `gh project item-add|item-edit`.
- **Destructive** - `gh pr merge`, `gh pr close`, `gh issue delete`, `gh repo delete`, `gh release create`, `gh run cancel`, `gh auth login`.
- **Raw `gh api`** - any call. The previous GET-wildcard auto-approval was dropped; a raw-API need is now opt-in per repo.

> **Behavior change.** Earlier defaults auto-approved `gh issue/pr` writes and read-only `gh api`. They now require approval - add the specific commands you trust to an allowed-list, or use the [append override](#append-only-override-ci).

The shipped `mode.all` baseline:

```yaml
# ~/.infer/tools.yaml
tools:
  bash:
    mode:
      all:
        allow:
          - gh (issue|pr|repo|release|run|workflow) (list|view|status|diff|checks)( .*)?
          - gh auth status( .*)?
          - gh search (issues|code|prs|repos|commits)( .*)?
          - gh project (list|view|item-list|field-list)( .*)?
```

#### Migration: the built-in GitHub tool was removed

> **Breaking change.** The built-in `Github` tool was removed in favor of the `gh` CLI. The `tools.github` config block and the `infer config tools github` commands no longer exist. Existing configs that still contain a `tools.github` section are **ignored** - unknown keys are dropped, so they do not error and need no manual cleanup. Replace any scripted use of the old tool with the matching `gh` command (for example `gh issue view`, `gh pr create`, `gh api`).

### Workflow Tools

#### TodoWrite

Create and update a structured task list for the current session. Use for complex multi-step work to track progress and surface intent to the user.

- **Parameters**: `todos` (required array; each item has `content`, `status` ∈ `pending` | `in_progress` | `completed`, and optional `id`)
- **Approval**: not required
- **Best practice**: keep at most one task in `in_progress` at a time; mark items `completed` immediately on finishing

#### Schedule

Create, list, get, update, or delete cron jobs that fire on a schedule. Jobs are persisted as YAML under `~/.infer/schedules/` and executed by the `infer daemon` (which reconciles its cron entries against storage every 2 seconds, so new or hand-edited jobs are picked up without a restart). When created from a channel session (e.g. Telegram), output is delivered back to that channel; otherwise the job is record-only - run history is persisted and viewable through the configured storage backend.

- **Parameters**: `operation` (required: `create` | `list` | `get` | `update` | `delete`), `job_id` (required for get/update/delete), `cron_expression` (5-field crontab or `@every <duration>`), `prompt`, `run_once` (default `false` - when `true`, the job is deleted after firing once), `name`, `description`, `model` (optional model override)
- **Approval**: required by default
- **Notes**: each fire creates a brand-new agent session - no context is carried between runs. Every fire persists a `RunRecord` (`session_id`, `job_id`, `status`, `error`, `started_at`, `finished_at`) through the configured storage backend; the newest 200 records are retained. `channel` and `recipient_id` on a job are optional delivery targets derived from the session, never passed by the LLM.

```text
"0 8 * * *"      every day at 08:00
"*/15 * * * *"   every 15 minutes
"0 9 * * 1-5"    weekdays at 09:00
"@every 1h"      every hour
```

> Jobs can also run in the cloud instead of the local daemon: set `scheduler.backend: github` to materialize each job as a GitHub Actions scheduled workflow. See [Scheduling](/cli-scheduling/).

#### AskUserQuestion

Pause and ask the user 1-4 multiple-choice clarifying questions as an interactive, keyboard-driven form. The agent reaches for this whenever a task is ambiguous - in Plan Mode it resolves the ambiguity **before** it calls [`RequestPlanApproval`](#requestplanapproval), so your answers feed straight back into the plan it then proposes; in the other interactive modes the answers come back mid-task. It is read-only with **no approval gate**.

- **Parameters**: `questions` (required array, **1-4** items). Each question has:
  - `header` (required) - short chip label shown above the question, **<= 12 characters**
  - `question` (required) - the full question text
  - `options` (required array, **2-4** items) - each option is `{ label, description }`
  - `multiSelect` (optional, default `false`) - allow more than one answer to be selected
- **Approval**: not required (read-only)
- **Availability**: every interactive mode - Plan, Standard, Auto-Accept and [auto-with-judge](/cli-judge-mode/) - when `tools.ask_user_question.enabled` is `true`. Headless runs have no interactive form and get the plain-text degradation below instead.

The form always appends an **"Other"** free-text choice to every question, so the user can answer outside the offered options. Suffix a label with **`(Recommended)`** to preselect that option when the question opens.

```json
{
  "questions": [
    {
      "header": "Datastore",
      "question": "Which datastore should the new service use?",
      "multiSelect": false,
      "options": [
        {
          "label": "PostgreSQL (Recommended)",
          "description": "Relational, strong consistency, already used by the gateway."
        },
        { "label": "MongoDB", "description": "Document store with a flexible schema." },
        { "label": "Redis", "description": "In-memory, best for ephemeral or cache data." }
      ]
    }
  ]
}
```

**Keyboard controls:**

| Key              | Action                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `Up` / `Down`    | Move between options. For single-select questions the radio selection follows the cursor. |
| `Space`          | Toggle the highlighted option (multi-select questions).                                   |
| `Enter`          | Confirm the current question and advance - or submit on the last question.                |
| `Esc` / `Ctrl+C` | Cancel the whole prompt.                                                                  |

**Headless graceful-degrade.** When no interactive user is reachable to answer - a CI run, a heartbeat, or a scheduled job - the tool does **not** block. It returns a "proceed with assumptions" result so the agent keeps moving and picks a reasonable default instead of hanging.

#### RequestPlanApproval

Submit a completed plan for user approval. Available only in Plan Mode.

- **Parameters**: `plan` (required - the complete, detailed plan text)
- **Behavior**: pauses execution and offers three choices (see [Approving a plan](#approving-a-plan)) - **Accept** (`Enter`/`y`) switches to [Auto-Accept mode](#auto-accept-mode) and executes with no per-action approval, **Approve Each Step** (`s`) executes in [Standard mode](#standard-mode) with approval on each action, and **Reject** (`n`) ends the session so you can reply with feedback.

#### RequestApproval

Ask the user to override an [LLM judge](/cli-judge-mode/) rejection so the rejected tool call can run once. The agent reaches for it after a judge rejection (in `auto-with-judge` mode or under `tools.safety.approval_behaviour: judge`) - the rejection result itself hints that the path exists.

- **Parameters**: `tool` (required - name of the rejected tool), `arguments` (required object - the exact arguments of the rejected call; `{}` for a call without arguments), `what` (required - what permission is needed, one sentence), `why` (required - why the action serves the user's request)
- **Behavior**: shows the rejected call in the regular approval box with the judge's reason and the agent's justification. **Approve** runs that exact call once with the judge bypassed; **Reject** or dismissal denies and the turn continues with the decision in context.
- **Eligibility**: only calls the judge actually rejected can be escalated, and each one only **once** - anything else returns `not_rejected` or `already_escalated`. The tool is advertised in every mode (a mode switch never invalidates the prompt cache), but outside judge mode nothing is ever rejected, so it has nothing to escalate.
- **Headless graceful-degrade**: with no interactive approver (CI, headless, channels without an approval form) it returns a distinguishable "no approver reachable" result instead of blocking.

See [Escalating a rejection](/cli-judge-mode/#escalating-a-rejection-requestapproval) for the full flow.

### Local Subagents (Agent tool)

The **Agent** tool lets the main agent - in chat or [headless mode](#headless-agent-stream-output) - spawn one or more **local subagents** that run work in parallel and fold their results back into the main conversation. A subagent is just an `infer headless` subprocess with its own isolated session, so it is cheap, isolated, and session-persisted. The tool is **enabled by default** and gated by the [`tools.agent.*` config block](#agent-tool-configuration).

This is the lightweight, **local** complement to the [A2A tools](/a2a/) (`A2A_SubmitTask` / `A2A_QueryTask` / `A2A_QueryAgent`), which target external A2A servers:

| Reach for...                          | When                                                                                                                                                                  |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent** (local subagents)           | Short-lived helpers for the task at hand - parallel exploration, fan-out edits, scoped research - with no server to run. Each is a local `infer headless` subprocess. |
| **A2A tools** (`A2A_SubmitTask`, ...) | Delegating to **external**, long-running, specialized A2A servers (calendar, docs, ...) discovered over the network. See [A2A](/a2a/).                                |

#### Tool parameters

The model calls the tool with either a batch of `tasks` or a single `description`:

- `tasks` - an array of subagent tasks run **in parallel**, each with:
  - `description` (required) - the task for that subagent
  - `label` (optional) - short label shown in progress output / tmux panes
  - `model` (optional) - per-subagent model override
  - `system_prompt` (optional) - gives that subagent a specialized role/persona
  - `agent` (optional) - name of a [Markdown subagent preset](#markdown-subagent-presets) that supplies the system prompt, model, and tool allowlist
- `description` (optional) - shorthand for a **single-task** call (an alternative to `tasks`)
- `system_prompt` (optional) - system prompt for the single-`description` form
- `agent` (optional) - preset name for the single-`description` form

Each subagent runs in its own isolated session id of the form `subagent-<parentSession>-<uuid>`. One call dispatches at most `max_parallel` subagents (default `10`). Tasks past the cap are dropped, not queued, and the tool result says how many.

#### Markdown subagent presets

Instead of spelling out a system prompt on every call, a subagent can be defined once as a **Markdown file with YAML frontmatter** and delegated to by name through the `agent` parameter. The format is the same one Claude Code (`.claude/agents/*.md`) and Gemini CLI (`.gemini/agents/*.md`) use, so an existing agent file from either tool loads unchanged once copied in. Every preset shows up as a `local` row in the [`/agents` view](#agents-view).

```markdown
---
name: code-reviewer
description: Reviews a diff for correctness bugs. Use after making code changes.
model: deepseek/deepseek-v4-pro
tools: Read, Grep, Tree
---

You are a senior reviewer. Read the changed files and report findings as a
numbered list ordered by severity.
```

The Markdown body is the subagent's system prompt. Frontmatter keys:

| Key               | Required | Meaning                                                                                             |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `name`            | yes      | Identifier passed as the `agent` argument. Lowercase letters, digits, `-`, `_`; up to 64 characters |
| `description`     | yes      | Shown to the main agent so it knows when to delegate                                                |
| `model`           | no       | `provider/model`, or `inherit` to use the parent turn's model                                       |
| `tools`           | no       | Tools the subagent may use - a YAML list or a comma-separated string. Omitted means inherit all     |
| `disallowedTools` | no       | Tools removed from the resolved list. Same format as `tools`                                        |

Any other key (`color`, `temperature`, `max_turns`, `mcpServers`, `permissionMode`, ...) is accepted and ignored, so files written for other orchestrators load as-is. These are presets for the Agent tool, entirely separate from `.infer/agents.yaml`, the [A2A](#a2a-integration) agent registry.

**Locations and precedence.** Definitions are looked up in this order, first match wins on a name collision:

1. **Project**: `.infer/agents/<name>.md` - commit it to share the agent with the repository
2. **User-global**: `~/.infer/agents/<name>.md` - stays personal

A project preset therefore overrides a personal one of the same name, exactly like [skills](/cli-skills/).

**Tool allowlist.** The resolved allowlist is enforced inside the spawned subagent in one place: a disallowed tool is neither offered to the model nor executable by naming it. Unknown tool names (for example Claude's `Glob`) log a warning and are dropped, `disallowedTools` entries are always honored, and a restriction that resolves to no known tool skips the file rather than silently falling back to all tools. The preset's capability follows from the allowlist - **read-only** when every allowed tool is read-only, otherwise **read-write** (mutations still go through approval). Listing `Agent` itself lets a preset spawn subagents, still bounded by `max_depth`.

**Model resolution.** The file's `model` wins over a per-task `model` argument. A value without a provider prefix - a Claude alias such as `sonnet`, or a bare model ID - logs a warning and falls back to `inherit`. When the file sets no model, the normal order applies: per-task `model`, then `tools.agent.model`, then the parent turn's model.

Files are scanned **once per session**. A file with broken frontmatter, a missing or invalid `name`/`description`, or an unusable `tools` list is skipped with a warning naming the file and the reason - an invalid preset never fails startup.

> **v1 limits.** `.claude/agents/` and `.gemini/agents/` are not read in place (copy or symlink the files into `.infer/agents/`), there is no hot reload, and per-agent `mcpServers`, `temperature`, `max_turns`, `permissionMode`, and tool wildcards such as `mcp_*` are not honored. MCP tools register after session start, so MCP tool names in a `tools` list are dropped as unknown.

#### Result modes: async and wait-all

- **Async (`wait: false`)** - the **shipped default**. The call returns immediately with the subagent ids, so later tool calls in the same turn run right away; when each subagent finishes a turn, its result is injected back into the main conversation (mirroring `A2A_SubmitTask` notify behavior) and a headless subagent then [stays alive](#headless-keep-alive-lifecycle) for follow-ups. In chat, running/completed status is surfaced in the sticky progress area.
- **Wait-all (`wait: true`)** - the call blocks until every spawned subagent reaches a terminal state, then returns the aggregated results in one tool result. A blocking subagent returns its **first turn** and is **not** kept alive.

#### Execution surfaces: headless and interactive (tmux)

The `mode` controls where subagents run. Either way the result aggregates back into the main context exactly the same - interactive is "headless plus a tmux pane attached to the live process":

- `headless` (the **shipped default**) - each subagent runs in the background as an [`infer headless --keep-alive`](#keeping-the-session-alive---keep-alive) subprocess whose stdin the parent holds open; results aggregate back into the main context.
- `interactive` - each subagent runs in a live **tmux** pane/window you can watch while it works.

tmux is an **optional runtime dependency**, required only for interactive mode (headless needs nothing extra). Interactive mode must be run from **inside tmux** (`$TMUX` set). Panes always open as a **vertical split**, and when you are not inside tmux (or tmux is not installed) the call **warns and runs headless** - there is nothing to configure either way.

In chat, a headless subagent is listed in the [background job list](#background-job-list) under the composer while it works, with its run stats counting up. Select its row and press `Enter` to read its conversation so far, refreshed every second.

#### Headless keep-alive lifecycle

A headless subagent is a conversation, not a one-shot: the delegated task is its first turn, and it stays alive afterwards so the main agent can talk to it without respawning and losing its context.

- **One completion note per finished turn.** Each turn that ends delivers a `[Subagent Completed: <label>]` note carrying that turn's final message and the run stats; a turn that ended in an error arrives as `[Subagent Failed: <label>]` with the error. The stats cover the **whole subagent session** - every turn it ran, not just the one that produced the note.
- **Follow-ups with `SendSubagentInput`.** Passing `text` sends the subagent a message - new information, a correction, a question about its result - which it runs as its **next turn in the same session**, with a new completion note when that turn ends. A message sent while the subagent is mid-turn is **queued** and runs next, so nothing is lost and no note is duplicated.
- **Idle auto-close.** A subagent that sits idle for `tools.agent.idle_timeout` seconds after a completed turn is closed with one `[Subagent Closed: <label>]` note carrying its last message. `0` disables the auto-close. There is **no `[Subagent Idle]` warning** for a headless subagent: every turn reports done, so the completion note itself is the cue that it awaits a follow-up.
- **`CloseSubagent`** stops a headless subagent at once, whether it is idle or running.
- **An idle subagent does not keep a headless parent alive.** A one-shot `infer headless` run that delegated work exits once its own turn is done.

`SendSubagentInput` works for **both** execution surfaces: `text` is the message in either mode, while `keys` and `submit: false` drive an interactive pane's TUI and **fail** for a headless subagent.

#### Done signal and idle auto-close (interactive panes)

An interactive pane is not a REPL you keep open. Each subagent reports completion and the parent closes the pane for you:

- **Done signal.** On its task turn - and on a failed terminal turn - the subagent writes `done: true` into the result file behind `INFER_SUBAGENT_RESULT_FILE`. The parent monitor sees it, closes the pane, and emits exactly one `[Subagent Completed: <label>]` note (carrying the error text when the turn failed).
- **Every completed turn with text counts as done**, including one that ends with a question. Write **self-contained task descriptions**: a subagent that stops to ask for more detail is treated as finished, not as waiting.
- **Idle auto-close.** A subagent that never reports done - a turn that ended without any text, a hung TUI, a pane running an older binary - is closed after `tools.agent.idle_timeout` seconds of inactivity. You get an early `[Subagent Idle: <label>]` warning, then `[Subagent Closed: <label>]` when the pane is closed.
- **The clock pauses for approvals** and is reset by `SendSubagentInput` typing, so a subagent waiting on your approval is never closed out from under you.
- **`CloseSubagent` is only for stopping a subagent early.** The main agent does not need it in the normal case - completed and idle panes close themselves.

#### Agent tool configuration

The new `tools.agent` block in [`~/.infer/tools.yaml`](#tool-configuration), with its shipped defaults (regenerated by `infer init`):

```yaml
# ~/.infer/tools.yaml
tools:
  agent:
    enabled: true
    require_approval: true # spawning work that can edit files is a mutating action
    mode: headless # headless | interactive (default when a call omits it)
    wait: false # return as soon as the subagents are dispatched; each reports back on its own
    max_parallel: 10 # cap on concurrent subagents per call
    max_depth: 1 # recursion guard; a subagent is itself an `infer headless`
    model: '' # default subagent model (inherits parent if blank)
    inherit_mock: true # when gateway.mock is on, spawn subagents against the embedded mock too
    idle_timeout: 300 # seconds a subagent may sit idle before the parent closes it (0 disables)
    completed_retention: 5 # finished subagent results kept for later retrieval
```

**Idle timeout (`idle_timeout`, default `300`).** Seconds a subagent may sit idle before the parent closes it with one `[Subagent Closed: <label>]` note; `0` disables the auto-close. A **headless** subagent is idle from a completed turn until the next `SendSubagentInput` (see [headless keep-alive lifecycle](#headless-keep-alive-lifecycle)); an **interactive** pane is idle when it shows no harvested result turn, no pane change and no pending approval, which only catches a pane that never reported done. Approval prompts pause the clock and `SendSubagentInput` resets it. See [Done signal and idle auto-close](#done-signal-and-idle-auto-close-interactive-panes).

Every key has an `INFER_TOOLS_AGENT_*` environment-variable override, consistent with the rest of the config:

| Setting               | Environment variable                    |
| --------------------- | --------------------------------------- |
| `enabled`             | `INFER_TOOLS_AGENT_ENABLED`             |
| `require_approval`    | `INFER_TOOLS_AGENT_REQUIRE_APPROVAL`    |
| `mode`                | `INFER_TOOLS_AGENT_MODE`                |
| `wait`                | `INFER_TOOLS_AGENT_WAIT`                |
| `max_parallel`        | `INFER_TOOLS_AGENT_MAX_PARALLEL`        |
| `max_depth`           | `INFER_TOOLS_AGENT_MAX_DEPTH`           |
| `model`               | `INFER_TOOLS_AGENT_MODEL`               |
| `inherit_mock`        | `INFER_TOOLS_AGENT_INHERIT_MOCK`        |
| `idle_timeout`        | `INFER_TOOLS_AGENT_IDLE_TIMEOUT`        |
| `completed_retention` | `INFER_TOOLS_AGENT_COMPLETED_RETENTION` |

```yaml
# ~/.infer/tools.yaml - toggle the tool, or switch the default execution
# surface to watchable tmux panes
tools:
  agent:
    enabled: true
    mode: interactive
```

**Mock inheritance (`inherit_mock`, default `true`).** When the parent CLI runs against the embedded mock gateway (`gateway.mock: true`), spawned subagents inherit mock mode: the CLI passes `INFER_GATEWAY_MOCK=true` to each subagent - both the headless environment and the interactive tmux-pane command - so they exercise the same mock instead of talking to the real gateway. Set `tools.agent.inherit_mock: false` (or `INFER_TOOLS_AGENT_INHERIT_MOCK=false`) to opt out and have subagents always target the configured gateway.

#### Approval and security

- Subagents run in standard **bash mode** (the restricted [allowed-list](#command-allow-listing)), exactly like every other headless run - an off-list or mutating action is blocked in CI/heartbeat (no approver reachable) or sent for IPC approval under a channel (for example Telegram). See [Headless secure-by-default](#headless-secure-by-default).
- The Agent tool is in the approval policy and **requires approval by default** (`require_approval: true`), with a per-tool override - consistent with `A2A_SubmitTask`. Spawning work that can edit files is treated as a mutating action.
- A **depth guard** (`max_depth`, default `1`) prevents subagent fork-bombs: a subagent cannot itself spawn further subagents at the default cap.
- While the parent is in [plan mode](#plan-mode), every subagent is **read-only**, whatever its preset or derived allowlist says.

#### Tracing

When telemetry is enabled, a **headless** subagent inherits the caller's trace context (`TRACEPARENT`), so its own `session` span nests under the caller's `execute_tool Agent` span - the whole fan-out reads as one cross-process trace in `infer traces`:

```text
session (standard, success)            152ms
|-- execute_tool Agent                  89ms
|   `-- session (readonly, success)     52ms
|       `-- chat openai/gpt-4o          13ms
```

Interactive (tmux-pane) subagents are **not** stitched into the caller's trace; use `mode: headless` when you need the subagent's spans in the same trace. See [Trace context propagation to subprocesses](#trace-context-propagation-to-subprocesses) for the full contract.

> **v1 scope.** Subagents do not nest (depth capped at 1), a subagent's tool-approval prompt is not routed back to the main chat TUI, only tmux is supported (no screen/zellij), and there is no CLI command to list or create Markdown presets (the [`/agents` view](#agents-view) lists them read-only).

### Security Features

- **Command allow-listing**: Default-deny, per-mode allowed-list for the Bash tool
- **Approval Prompts**: Safety confirmations for Write/Edit/Delete/Bash
- **Path Protection**: Sensitive paths denied by default (`.git/`, `*.env`, `*.key`, `.infer/`)
- **File sandbox**: [`~/.infer/sandbox.yaml`](#file-sandbox) bounds which paths the file tools may read and write
- **Protected policy files**: [`~/.infer/tools.yaml`](#tool-configuration) and [`~/.infer/sandbox.yaml`](#file-sandbox) are userspace-only and the agent's file tools refuse to write them
- **Domain allow-listing**: Control web fetch access
- **Diff Preview**: Colored, syntax-aware diff before file modifications
- **Project Tools Always Ask**: [Custom tools](#custom-tools) supplied by a repository need approval on every call, whatever their manifest says, except in `auto` mode
- **Write-Protected Tool Directories**: Write, Edit, MultiEdit and Delete refuse any path inside a custom-tool directory (`~/.infer/tools/`, `tools.custom_dir`, `.infer/tools/`, `.agents/tools/`), including through symlinks - this cannot be switched off

### Tool Configuration

The whole tools policy lives in a **userspace-only policy file**, `~/.infer/tools.yaml` - not in `config.yaml`. The keys for every tool sit at the top of the file and each tool's section sits under `tools:`. `infer config get` and the `INFER_TOOLS_*` overrides name both kinds `tools.<key>`, for example `tools.safety.require_approval` and `tools.bash.enabled`:

```yaml
# ~/.infer/tools.yaml
enabled: true # all tool execution for LLMs
safety:
  require_approval: true # approval before any tool runs
  approval_behaviour: judge # how an approval is delivered
custom_dir: /opt/my-app/tools # user custom tools from another directory
tools:
  bash:
    enabled: true
    require_approval: true # per-tool override of safety.require_approval
    mode:
      standard:
        allow:
          - make test
```

`infer init` seeds the file from the defaults, and `--overwrite` regenerates it. Like [`sandbox.yaml`](#file-sandbox), it is **userspace-only and agent-protected**:

- Only `~/.infer/tools.yaml` is read. A project `.infer/tools.yaml` and a `tools:` block in any `config.yaml` have **no effect**, so a checked-out repository cannot change tool approval.
- The Write, Edit, MultiEdit and Delete tools **refuse** the file, so the agent cannot approve itself by writing one file.
- `infer config set tools.*` is **rejected** with an error naming `tools.yaml` - edit the file instead. `infer config get tools` (and `infer config get tools.bash`) still prints the effective value.
- The `INFER_TOOLS_*` environment overrides are unchanged, and a set-but-empty value wins (`INFER_TOOLS_WEB_FETCH_ALLOWED_DOMAINS=` empties the list).

```bash
# Edit the policy
$EDITOR ~/.infer/tools.yaml

# Or override a single setting for one run
INFER_TOOLS_ENABLED=false infer headless "Summarize the README"

# Inspect the effective tools config
infer config get tools
```

> The file sandbox is **not** a tools config key either. It lives in its own policy file, `~/.infer/sandbox.yaml` - see [File sandbox](#file-sandbox).

### Running Tools Directly

Run any enabled tool outside a chat session, or check whether a bash command would pass the allowed-list, with the top-level `infer tools` command.

```bash
# Execute a tool by name with JSON arguments (tool names are case-insensitive)
infer tools execute Read '{"file_path":"README.md"}'
infer tools execute grep '{"pattern":"func main","path":"."}'

# Validate whether a bash command is allowed (without running it)
infer tools validate "git status"
```

`infer tools execute <tool> [json-args]` resolves tool names case-insensitively in the CLI - the agent itself still uses the exact PascalCase names. `infer tools validate <command>` reports whether a bash command would be permitted by the configured allowed-list, without executing it.

> `infer tools execute` and `infer tools validate` moved from `config tools exec`/`config tools validate` to the top-level `infer tools` command.

## Custom Tools

**Custom tools** let you add tools written in any language to the CLI. Drop one YAML manifest per tool into `~/.infer/tools/`, or into a project's `.infer/tools/` or `.agents/tools/`, and the CLI offers the tool to the model next to the built-in ones. A call runs the manifest's `command` with the call's arguments as JSON on stdin, and whatever the command prints on stdout is the result. There is no SDK to import and no server to run.

A custom tool behaves like a built-in tool: the model sees it under its own name, you can run it yourself with `!!Name(arg="v")` in chat or `infer tools execute Name '{...}'`, and it follows the same agent modes and approval flow.

> For a runnable version, see [`examples/tools`](https://github.com/inference-gateway/cli/tree/main/examples/tools) in the CLI repository - a user tool and a project tool driven by a scripted mock model, so it needs no API key.

### Custom Tools Quick Start

A tool that counts the words in a file, written as a shell script.

`~/.infer/tools/WordCount.yaml`:

```yaml
name: WordCount
description: Count the words in a text file.
command:
  - ./word-count.sh
parameters:
  type: object
  properties:
    path:
      type: string
      description: Path of the file to count
  required:
    - path
modes:
  - standard
  - auto
  - auto-with-judge
  - plan
  - readonly
require_approval: false
```

`~/.infer/tools/word-count.sh` (make it executable with `chmod +x`):

```sh
#!/bin/sh
path=$(jq -r .path)
wc -w < "$path"
```

Try it without the model:

```bash
infer tools execute WordCount '{"path":"README.md"}'
```

### User Tools and Project Tools

The CLI loads custom tools from three directories and merges them:

| Directory                                 | Kind                                         | Approval                                  |
| ----------------------------------------- | -------------------------------------------- | ----------------------------------------- |
| `~/.infer/tools/` (or `tools.custom_dir`) | User tools, which you installed              | As the manifest's `require_approval` says |
| `.infer/tools/` in the working directory  | Project tools, which the repository supplies | Always, except in `auto` mode             |
| `.agents/tools/` in the working directory | Project tools, which the repository supplies | Always, except in `auto` mode             |

When two directories define a tool with the same name, the project tool wins over the user tool, and `.infer/tools/` wins over `.agents/tools/`.

A project tool comes with whatever repository you cloned, so the CLI never lets it run silently. Every call needs approval, even when its manifest says `require_approval: false` and even in `readonly` mode, which runs every other tool it offers without asking. Only `auto` mode, which runs every call unapproved, runs a project tool without asking. `!!Name(...)` and `infer tools execute` count as your approval, as for any tool.

### Custom Tool Manifest Reference

A custom tool manifest uses the same format as the manifests of the CLI's built-in tools, plus three fields that only custom tools have: `command`, `timeout` and `enabled`. Unknown fields are rejected, so a misspelled key fails loudly instead of silently falling back to a default.

| Field              | Required | Default                               | Meaning                                                                                                                                                        |
| ------------------ | -------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | yes      |                                       | Tool name the model sees. Must match the file name (`WordCount.yaml`), start with a letter, and use only letters, digits and underscores, up to 64 characters. |
| `description`      | yes      |                                       | What the tool does and when to use it. The model reads this to decide when to call the tool.                                                                   |
| `command`          | yes      |                                       | Program and fixed arguments, as a list. It runs without a shell, see below.                                                                                    |
| `parameters`       | yes      |                                       | JSON Schema of type `object` for the call's arguments, sent to the model unchanged.                                                                            |
| `modes`            | no       | `standard`, `auto`, `auto-with-judge` | Agent modes that offer the tool, see [Custom Tool Modes and Approval](#custom-tool-modes-and-approval).                                                        |
| `require_approval` | no       | `tools.safety.require_approval`       | Whether a call needs approval before it runs.                                                                                                                  |
| `timeout`          | no       | `30`                                  | Seconds before the call is killed.                                                                                                                             |
| `enabled`          | no       | `true`                                | `false` keeps the manifest on disk without loading the tool.                                                                                                   |

`command[0]` is resolved like this:

- A bare name such as `infer-desktop-tools` is looked up on `PATH`.
- A path containing a slash such as `./word-count.sh` or `bin/tool` resolves against the manifest's directory, so a tool can ship next to its manifest.
- An absolute path is used as is.

### How a Custom Tool Call Runs

1. The CLI checks the arguments against `parameters`: every `required` property must be present and each property must have its declared type. A call that fails the check never starts the process.
2. It starts `command` without a shell, in the session's working directory, with the CLI's environment.
3. It writes the arguments to stdin as one JSON object, for example `{"path":"README.md"}`, and closes stdin.
4. **Exit code 0**: stdout is the tool result, as text. **Non-zero exit code**: the call fails, and stderr (or stdout when stderr is empty) goes back to the model as the error.
5. The process is killed when `timeout` expires or the turn is cancelled. On Linux and macOS the whole process group is killed, so the children a script started die too. On Windows only the direct child is killed.

Like every tool result, the output the model sees is capped at `tools.max_result_bytes`.

### Custom Tool Modes and Approval

Custom tools follow the same policy as built-in tools:

- **`modes`** lists the agent modes that offer the tool. Without it the tool is offered in `standard`, `auto` and `auto-with-judge`, and hidden in `plan` and `readonly`, like an MCP tool. A tool that only reads can list every mode, as the `WordCount` example in [Custom Tools Quick Start](#custom-tools-quick-start) does. A call outside the tool's modes is refused.
- **`require_approval`** decides whether a user tool's call needs approval. Without it the tool follows the global `tools.safety.require_approval` (default `true`). A project tool always needs approval, see [User Tools and Project Tools](#user-tools-and-project-tools). How the approval is asked for follows `tools.safety.approval_behaviour` (`prompt`, `ipc`, `judge` or `block`) in both chat and headless mode.

> **Listing `readonly` declares the tool safe.** Read-only mode runs the tools it offers without asking for approval, so only list `readonly` (and `plan`) for tools that do not change anything.

Approval applies to calls the model makes. `!!Name(...)` in chat and `infer tools execute` are started by you and count as approved, as they do for built-in tools. `infer tools execute --format json` still reports `approval_required` for callers that handle approval themselves.

`tools.enabled: false` turns custom tools off together with the other local tools. Markdown subagents (`.infer/agents/*.md`) can list custom tools in their `tools:` field.

### Custom Tool Names

Custom tools get no prefix, so they look like built-in tools to the model. To keep that unambiguous, the CLI skips a manifest whose name:

- matches the name of any built-in tool, even one your configuration switches off, compared case-insensitively (`read` is rejected because of `Read`), or
- starts with `MCP_`, which is reserved for [MCP](/mcp/) tools.

A custom tool never replaces a built-in or MCP tool, and no built-in or MCP tool replaces a custom tool. Between custom tools, a project tool replaces a user tool of the same name.

### Example: One Binary for Many Tools (Rust)

A compiled program can back several tools through subcommands, one manifest per tool.

`~/.infer/tools/TakeScreenshot.yaml`:

```yaml
name: TakeScreenshot
description: Capture a screenshot of a desktop app window and return the PNG path.
command:
  - infer-desktop-tools
  - screenshot
parameters:
  type: object
  properties:
    window:
      type: string
      description: Title of the window to capture
  required:
    - window
timeout: 60
```

`src/main.rs` (with `serde` and `serde_json` as dependencies):

```rust
use serde::Deserialize;
use std::io::Read;

#[derive(Deserialize)]
struct ScreenshotArgs {
    window: String,
}

fn screenshot(args: ScreenshotArgs) -> Result<String, String> {
    let path = format!("/tmp/{}.png", args.window.replace(' ', "_"));
    // Capture the window here.
    Ok(path)
}

fn main() {
    let mut input = String::new();
    std::io::stdin().read_to_string(&mut input).expect("reading stdin");

    let result = match std::env::args().nth(1).as_deref() {
        Some("screenshot") => serde_json::from_str(&input)
            .map_err(|e| format!("invalid arguments: {e}"))
            .and_then(screenshot),
        other => Err(format!("unknown subcommand {other:?}")),
    };

    match result {
        Ok(output) => println!("{output}"),
        Err(message) => {
            eprintln!("{message}");
            std::process::exit(1);
        }
    }
}
```

Install the binary on `PATH` (or reference it by a path relative to the manifest), and every manifest pointing at it becomes a tool.

### Custom Tools vs MCP

[MCP servers](/mcp/) also add tools in any language. Custom tools are the lighter option when you control the tool:

- No server to start or health-check. Nothing runs until a call is made, which keeps each `infer headless` start cheap.
- No prefix: the tool is `TakeScreenshot`, not `MCP_<server>_TakeScreenshot`.
- Per-tool `modes` and `require_approval`. MCP tools are hidden in plan mode and use the global approval setting.

`~/.infer/tools/` is yours. It is unrelated to `~/.infer/bin/tools/`, which `infer binaries` owns and fills with the prebuilt helper programs the CLI itself uses (ffmpeg, whisper-cli, llama-tts).

### Custom Tool Security

A custom tool runs with **your** permissions and can do anything you can. The [file sandbox](#file-sandbox) (`~/.infer/sandbox.yaml`) only restricts the CLI's built-in file tools, not the programs custom tools start. Only install manifests and programs you trust, keep `require_approval` on for tools that change things, and list `plan`/`readonly` in `modes` only for tools that do not.

- **Project tools always ask.** A cloned repository can offer tools, but none of them runs without your approval outside `auto` mode.
- **The CLI never edits the tool directories.** The Write, Edit, MultiEdit and Delete tools refuse any path inside `~/.infer/tools/`, `tools.custom_dir`, `.infer/tools/` or `.agents/tools/`, also through a symlink or another spelling of the path, so the model cannot write itself a tool that skips approval. This cannot be switched off. The Bash tool is not covered: in `auto` mode it runs any command.
- **A project cannot change the approval policy.** `custom_dir`, the Bash allow-list and the approval settings come from your own [`~/.infer/tools.yaml`](#tool-configuration); a project `.infer/config.yaml` or `.infer/tools.yaml` cannot touch them.

### Loading Custom Tools From Another Directory

Set `custom_dir` in [`~/.infer/tools.yaml`](#tool-configuration), or the `INFER_TOOLS_CUSTOM_DIR` environment variable, to load your user tools from another directory instead of `~/.infer/tools/`. The project directories still load:

```yaml
# ~/.infer/tools.yaml
custom_dir: /opt/my-app/tools
```

```bash
INFER_TOOLS_CUSTOM_DIR=/opt/my-app/tools infer headless "Take a screenshot of the editor"
```

An app that embeds the CLI can use this to offer its own tools without adding them to the user's terminal CLI.

### Custom Tools Troubleshooting

- **The tool does not show up.** The CLI skips an invalid manifest with a warning in its logs (`~/.infer/logs/`) and starts anyway. The warning names the file and the reason, such as an unknown field, a name that does not match the file name, or a taken name.
- **Test a tool without the model.** `infer tools execute Name '{"arg":"value"}'` runs it directly and prints the result or the error.
- **The call fails with "executable file not found".** A bare command name must be on the `PATH` the CLI runs with. Use a path relative to the manifest, or an absolute path, instead.

## Configuration

Two-layer configuration system with precedence from highest to lowest:

### Configuration Precedence

| Priority    | Source                | Example                                  |
| ----------- | --------------------- | ---------------------------------------- |
| 1 (Highest) | Environment Variables | `INFER_GATEWAY_URL`, `INFER_AGENT_MODEL` |
| 2           | Command Line Flags    | `--model`, `-v, --verbose`               |
| 3           | Project Config        | `.infer/config.yaml`                     |
| 4           | User Config           | `~/.infer/config.yaml`                   |
| 5 (Lowest)  | Built-in Defaults     | Internal defaults                        |

### Configuration Files

`infer init` seeds the userspace baseline in `~/.infer/` (`config.yaml`, `tools.yaml`, `sandbox.yaml`, `mcp.yaml`, `prompts.yaml`, `agents.yaml`, `shortcuts/`, `skills/` and so on) and writes nothing into the project. Project-level overrides are created on demand with `infer config set --project <key> <value>`, or with `--project` on `infer mcp` / `infer agents`. Configuration is split across purpose-specific YAML files rather than one giant file:

| File               | Scope        | Purpose                                                                                                                                                | Where it is documented                                      |
| ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| `config.yaml`      | Project/user | Main config - agent, gateway, storage, pricing, and everything `config set` touches. A `tools:` block here is ignored.                                 | [Configuration](#configuration-commands)                    |
| `prompts.yaml`     | Project/user | System prompts (`prompts.agent.system_prompt`), per-mode adjustments, and tool descriptions (`prompts.tools.<Tool>.description`) - edited, not `set`.  | [Configuration Commands](#configuration-commands)           |
| `mcp.yaml`         | Project/user | MCP server definitions and connection settings.                                                                                                        | [MCP Integration](#mcp-integration)                         |
| `keybindings.yaml` | Project/user | Keybindings for the TUI and diff viewer (category `diff_viewer`).                                                                                      | [Diff viewer and git staging](#diff-viewer-and-git-staging) |
| `hooks.yaml`       | Project/user | User-defined shell commands run at agent-loop hook points (feature-flagged off by default).                                                            | [Command Hooks](/cli-hooks/)                                |
| `reminders.yaml`   | Project/user | System reminders injected into the conversation on a schedule.                                                                                         | [System Reminders](#system-reminders)                       |
| `tools.yaml`       | User only    | Tools policy - enablement, approval, per-mode bash allowed-lists, each tool under `tools:`. A project copy is ignored.                                 | [Tool Configuration](#tool-configuration)                   |
| `sandbox.yaml`     | User only    | File sandbox policy - `filesystem.allowed` and `filesystem.denied`. A project copy is ignored.                                                         | [File sandbox](#file-sandbox)                               |
| `judge.yaml`       | Project/user | LLM judge that decides approval-requiring tool calls (model, timeout, prompts, `on_error`).                                                            | [Judge Mode](/cli-judge-mode/)                              |
| `daemon.yaml`      | Project/user | `infer daemon` itself - the AG-UI binding's own switch, port and token (`binding.enabled`, `binding.port`, `binding.token`).                           | [Starting the daemon](#starting-the-daemon)                 |
| `memory.yaml`      | Project/user | Persistent, cross-session agent memory - fact-files plus the `MEMORY.md` index.                                                                        | [Persistent Memory](#persistent-memory)                     |
| `shortcuts/*.yaml` | Project      | Custom slash shortcuts - simple commands, subcommands, and AI-powered snippets.                                                                        | [Custom Shortcuts](#custom-shortcuts)                       |
| `skills/`          | Project/user | Agent Skills folders (`name/SKILL.md`) discovered and injected on demand.                                                                              | [Agent Skills](#agent-skills)                               |
| `tools/`           | Project/user | Custom tool manifests (`Name.yaml`), one per tool, also read from `.agents/tools/`.                                                                    | [Custom Tools](#custom-tools)                               |
| `schedules/`       | User         | Persisted cron jobs created by the Schedule tool, run by the daemon.                                                                                   | [Schedule](#schedule)                                       |
| `artifacts/`       | Project/user | Agent deliverables, grouped per session.                                                                                                               | [Artifacts directory](#artifacts-directory)                 |
| `logs/`            | User         | CLI and gateway log files (`~/.infer/logs`, overridable via `logging.dir`).                                                                            | [Key Configuration Areas](#key-configuration-areas)         |
| `bin/`             | User         | Downloaded binaries - the gateway server, plus optional helpers like `ffmpeg`.                                                                         | [Key Configuration Areas](#key-configuration-areas)         |
| `insights/`        | User         | Saved `infer insights` reports. Written with secrets redacted, and kept by `/reset`.                                                                   | [Insights Shortcut](#insights-shortcut)                     |
| `avatars/`         | User         | Avatar portrait folders (`avatars/<name>/*.png`) used by `TextToVideo` lip-sync renders. Kept by `/reset`.                                             | [Text-to-Video](/cli-text-to-video/#the-avatar-library)     |
| `auth.yaml`        | User         | Fallback provider API keys, used when a key is not in the environment or the project `.env`.                                                           | [Provider API keys](#provider-api-keys)                     |
| `tmp/`             | User         | Scratch space, including the `tmp/media` root for generated speech, music, video, recordings, screenshots and retained attachments. Wiped by `/reset`. | [Media directories](#media-directories)                     |

> **No migration.** `logs/` and `bin/` are userspace-only: they live under `~/.infer/` and are
> shared by every project. Older versions wrote them into the project's `.infer/` directory; those
> directories are orphaned by design and safe to delete. The `.infer/.gitignore` seeded by
> `infer init` no longer lists `bin/` or `logs/*.log`.

### Provider API keys

Provider API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GROQ_API_KEY`, ...) are resolved **per key, first hit wins**:

| Priority    | Source               | Notes                                          |
| ----------- | -------------------- | ---------------------------------------------- |
| 1 (Highest) | System environment   | Exported in your shell, CI secrets, and so on. |
| 2           | Project `.env`       | `.env` in the project directory.               |
| 3 (Lowest)  | `~/.infer/auth.yaml` | Userspace fallback, shared by every project.   |

Because resolution is per key, sources mix: `OPENAI_API_KEY` can come from the environment while `ANTHROPIC_API_KEY` comes from `auth.yaml` in the same run. The fallback applies when the CLI starts the gateway in **both container and binary modes**, and to [A2A](#a2a-integration) agent containers.

`auth.yaml` is a flat YAML map of environment-variable names to values:

```yaml
ANTHROPIC_API_KEY: sk-ant-...
OPENAI_API_KEY: sk-...
DEEPSEEK_API_KEY: sk-...
```

Create it once and keep it private:

```bash
mkdir -p ~/.infer
$EDITOR ~/.infer/auth.yaml
chmod 600 ~/.infer/auth.yaml
```

- **Permissions**: `0600` is recommended. Broader permissions still work but log a warning.
- **Sandboxed**: `auth.yaml` is on the `filesystem.denied` list of the [file sandbox](#file-sandbox) - agent tools cannot read or edit it.
- **Graceful degradation**: a missing or unreadable file changes nothing; a malformed file is ignored with a logged warning. Key resolution never fails because of `auth.yaml`.
- **Legacy `auth.json`**: the old JSON file is still read as a fallback when `auth.yaml` is absent, so existing credentials keep working. Move your keys into `auth.yaml` - JSON is valid YAML, so the contents can be pasted as-is.

### Artifacts directory

Files the agent produces for you land in `.infer/artifacts/<session-id>/`, under the project config dir when there is one and the userspace config dir (`~/.infer/artifacts/`) otherwise. Each conversation gets its own subdirectory, so a session's output stays grouped and is easy to find, keep, or delete as a unit.

What lands there:

- Images from the [ImageGeneration, ImageEdit, and ImageVariation tools](#image-tools) - `image-<timestamp>.png`.
- [WebFetch](#webfetch) downloads and binary fetches.
- Auto-downloaded [A2A task artifacts](#a2a-integration).

`.infer/artifacts` is **not** the same as `.infer/tmp`:

| Directory          | Contents                                                                                                                                    | Lifetime                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `.infer/artifacts` | Intended agent deliverables, grouped by session                                                                                             | Yours to keep - nothing prunes it for you |
| `.infer/tmp`       | Internal scratch - chunk staging, skill downloads, pastes, and the [media root](#media-directories) holding screenshots and generated media | Disposable working data                   |

Session IDs are sanitized before use, so a directory can never escape the artifacts root. The [file sandbox](#file-sandbox) carves the artifacts directory out as writable, so tools can save there even when it sits outside the allowed list.

### Media directories

Every generated and retained media file lives under one **media root**, with a subdirectory per kind. The root follows the open project:

- **In a project** - `~/.infer/projects/<project-slug>/tmp/media/`. The desktop app runs a selected project's sessions there, so its media lands in that project's root too.
- **No project open** - `~/.infer/tmp/media/`, used when the working directory is `$HOME` or the desktop's `~/.infer/workspace`.

| Subdirectory   | Contents                                             | Config default of                   |
| -------------- | ---------------------------------------------------- | ----------------------------------- |
| `tts/`         | Generated speech WAVs                                | `text_to_speech.output_dir`         |
| `music/`       | Generated music MP3s                                 | `text_to_music.output_dir`          |
| `sfx/`         | Generated sound-effect WAVs                          | `text_to_sfx.output_dir`            |
| `video/`       | Rendered MP4 clips                                   | `text_to_video.output_dir`          |
| `recordings/`  | [`RecordStart`](#screen-recording) screen recordings | `computer_use.recording.output_dir` |
| `screenshots/` | Browser and computer-use screenshots                 | `computer_use.screenshot.temp_dir`  |
| `voice/`       | Retained inbound voice recordings                    | `speech_to_text.recordings_dir`     |
| `attachments/` | Retained inbound Telegram photos and videos          | `channels.telegram.media.dir`       |

The media root is agent-readable and writable by design - retained recordings and attachments are assets the agent consumes, and generated speech is output it can reference. The rest of `~/.infer/` is covered by the `.infer/` denial in the [file sandbox](#file-sandbox), which asks before every read and write. [`/reset`](#reset-shortcut) empties both tmp trees through their `tmp` parents; the owning subsystems recreate the subdirectories on next use. Directories you explicitly point outside `~/.infer` are left alone.

> **Existing installs.** Older releases placed these directories directly under `~/.infer/` or `~/.infer/tmp/` (`tts/`, `voice/`, `media/`, ...). Nothing migrates automatically - they hold only disposable output, so delete them, or `mv` their contents into the media root to keep the retained files. Explicit `output_dir` / `recordings_dir` / `temp_dir` / `media.dir` overrides are unaffected.

### Key Configuration Areas

**Gateway Settings:**

- Gateway URL and API key
- Timeout and retry configuration (see [Client retry and stream reconnection](#client-retry-and-stream-reconnection) below)
- OCI image for auto-running gateway
- Model filtering: `gateway.include_models` (allowlist) and `gateway.exclude_models` (blocklist). Both default to `[]`. `gateway.exclude_models` is opt-in - the [model picker](#model-picker-labels) already hides non-chat-capable models via the gateway-reported modalities, so use it only to hide specific models the gateway reports (large or costly chat models, for example); there is no shipped default blocklist. Set exclusions are passed to the gateway as the `DISALLOWED_MODELS` environment variable.

The downloaded gateway binary lands at `~/.infer/bin/inference-gateway` - one shared copy per machine, reused by every project (the staleness check still re-downloads when the pinned version changes).

**Logging Configuration:**

Logging settings control log output, file location, and automatic log archiving:

```yaml
logging:
  debug: false
  dir: '' # Override log directory (defaults to ~/.infer/logs)
  stdout: false # Also write logs to stdout/stderr in addition to the log file
  archive:
    enabled: true # Automatically archive oversized log files (default: true)
    max_size_mb: 1024 # Threshold in MB; files exceeding this are gzip-compressed and truncated (default: 1024 = 1 GB)
```

- **logging.debug**: Enable debug logging for verbose output (`INFER_LOGGING_DEBUG`). There is no `--debug` flag - the only verbosity flag is the global `-v, --verbose`.
- **logging.dir**: Override the log directory. Defaults to `~/.infer/logs` (`INFER_LOGGING_DIR`) - CLI and gateway logs are machine-scoped and never written to the project directory.
- **logging.stdout**: Also write logs to stdout/stderr in addition to the log file (default: `false`)
- **logging.archive.enabled**: Enable automatic log archiving (default: `true`). When enabled, log files exceeding the size threshold are gzip-compressed to a timestamped `.gz` archive and the original file is truncated so logging continues at the same path. The check runs at process startup. Set via `INFER_LOGGING_ARCHIVE_ENABLED`.
- **logging.archive.max_size_mb**: Maximum log file size in MB before archiving is triggered (default: `1024`, i.e. 1 GB). A value of `0` or less disables archiving. Set via `INFER_LOGGING_ARCHIVE_MAX_SIZE_MB`.

**Agent Configuration:**

- Default model for operations
- System prompt (`prompts.agent.system_prompt`) and per-mode adjustments (`mode_adjustment_plan` / `mode_adjustment_auto`, delivered by the [mode-change reminder](#how-mode-instructions-are-delivered))
- System reminders interval
- Max turns and tokens
- Parallel tool execution (default: 5 concurrent)
- Project instructions: `agent.agents_md.*` injects the root `AGENTS.md` and points at nested ones (see [How AGENTS.md reaches the model](#how-agents-md-reaches-the-model))

The built-in system prompt includes a `Current date:` line (date-only, no time) so provider-side prompt-prefix caching stays effective across turns. When the agent needs the current time, it runs the `date` command via Bash.

**Tool Settings:**

Tool settings live outside `config.yaml`, in [`~/.infer/tools.yaml`](#tool-configuration), which keeps the keys for every tool at the top and each tool's section under `tools`:

- Enable/disable individual tools
- Approval requirements per tool (whether) and delivery via `safety.approval_behaviour` (how)
- Per-mode bash allowed-lists (`tools.bash.mode.<mode>.allow`)
- The file sandbox has its own policy file too, [`~/.infer/sandbox.yaml`](#file-sandbox)

**Storage Backends:**

- JSONL (default) - append-only files for portable, inspectable history
- PostgreSQL - shared database for teams
- Redis - high-performance caching
- SQLite - local file storage
- Cloudflare D1 - external SQLite-compatible store over HTTP (for ephemeral CI runners)
- In-memory - temporary sessions

**Message Queue:**

- `queue.type` picks the queue backend (`memory` default, `sqlite`, `postgres`, `redis`), `queue.name` scopes it and `queue.poll_interval` sets the cross-process wake-up cadence - see [Message Queue](#message-queue)

**Conversation Features:**

- Automatic history with search
- AI-generated titles
- Token optimization and compaction
- Export/import capabilities

### Client Retry and Stream Reconnection

The CLI automatically reconnects when a stream stalls or drops, using the `client.retry.*` settings for exponential backoff and attempt limits. A stall is detected when no progress is made - no response while connecting, no SSE chunk while streaming - for longer than `client.stall_threshold_sec`.

```yaml
# .infer/config.yaml
client:
  stall_threshold_sec: 30 # seconds without progress before reconnecting (0 disables)
  retry:
    enabled: true
    max_attempts: 5 # maximum number of retry attempts (default: 5)
    retryable_status_codes: [408, 429, 500, 502, 503, 504] # transient errors only
    initial_backoff_sec: 5
    max_backoff_sec: 60
    backoff_multiplier: 2
```

**Settings:**

- **client.stall_threshold_sec**: Seconds without progress - no response while connecting, no SSE chunk while streaming - before the CLI drops the connection and reconnects (default: `30`, `0` disables). Reconnects reuse `client.retry.*` for attempts and exponential backoff. Keep this above your provider's worst first-token latency, since a stall retry restarts the response from scratch. Set via `INFER_CLIENT_STALL_THRESHOLD_SEC`.
- **client.retry.enabled**: Enable automatic retries for failed requests (default: `true`).
- **client.retry.max_attempts**: Maximum number of retry attempts (default: `5`). Set via `INFER_CLIENT_RETRY_MAX_ATTEMPTS`.
- **client.retry.retryable_status_codes**: HTTP status codes that trigger retries (default: `[408, 429, 500, 502, 503, 504]`); non-transient errors such as 401 fail fast with their real message. Set via `INFER_CLIENT_RETRY_RETRYABLE_STATUS_CODES`.
- **client.retry.initial_backoff_sec**: Initial delay between retries in seconds (default: `5`).
- **client.retry.max_backoff_sec**: Maximum delay between retries in seconds (default: `60`).
- **client.retry.backoff_multiplier**: Backoff multiplier for exponential delay (default: `2`).

**Reconnecting indicator:** In the chat TUI, the status bar shows a red `Reconnecting...` indicator when a stall is detected, then `Reconnecting (N/M)` per attempt (where `N` is the current attempt and `M` is `max_attempts`). Input is blocked until the stream recovers or all attempts are exhausted. See [Status indicator row](#status-indicator-row).

### System Reminders

System reminders are YAML-configured prompts injected into the conversation on a schedule or in response to tool outcomes. They are defined in `reminders.yaml` (project or user scope) and can also be supplied inline or from an arbitrary path.

#### Reminders YAML Schema

```yaml
# .infer/reminders.yaml (or ~/.infer/reminders.yaml)
enabled: true
reminders:
  - name: memory-consult
    hook: pre_tool
    trigger: always
    text: 'Consult the Memory tool before making changes.'
  - name: fail-nudge
    hook: post_tool
    trigger: on_failure
    text: 'A failed call means the change did not happen. Re-try or ask the user.'
```

| Field       | Type    | Description                                                                                                                                                                        |
| ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`   | boolean | Master switch. Default `true`. Can also be toggled via `INFER_REMINDERS_ENABLED`.                                                                                                  |
| `name`      | string  | Unique identifier for the reminder. Used for deduplication and logging.                                                                                                            |
| `hook`      | string  | When the reminder fires. One of `pre_tool` (before each tool call) or `post_tool` (after each tool call completes).                                                                |
| `trigger`   | string  | Condition under which the reminder fires. See [Trigger catalog](#trigger-catalog) below.                                                                                           |
| `text`      | string  | The reminder text injected into the conversation. Supports `os.ExpandEnv` environment variable interpolation (`$VAR` or `${VAR}`).                                                 |
| `threshold` | integer | `on_repeated_failure` only (required, > 0). Number of consecutive failures of the same call before the reminder fires.                                                             |
| `guidance`  | map     | `on_mode_change` only. Maps a mode key (`standard`, `plan`, `auto`) to the text substituted for the `{guidance}` placeholder in `text`. Omitted keys keep their built-in defaults. |

#### Trigger catalog

| Trigger               | Hook requirement | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `always`              | Any              | Fire on every hook invocation.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `on_failure`          | `post_tool`      | Fire only when the tool call that just ran failed (returned an error). Requires `hook: post_tool`; validation rejects other hooks.                                                                                                                                                                                                                                                                                                                                    |
| `on_mode_change`      | Any              | Fire when the [agent mode](#agent-modes) changes (Shift+Tab). Used by the built-in `mode-change-reminder`, which is the **sole carrier** of mode-specific instructions - see [How mode instructions are delivered](#how-mode-instructions-are-delivered).                                                                                                                                                                                                             |
| `on_repeated_failure` | `post_tool`      | Fire when the same tool call has failed `threshold` times in a row (built-in default `3`). Matching is on **normalized** arguments, not the raw string: `offset`, `limit`, key order and whitespace are ignored, so retries that only change pagination or re-serialize the same arguments still count toward the threshold. `Read` matches on the `file_path` alone. A success with the same key resets the counter. Requires `hook: post_tool` and `threshold` > 0. |

The built-in `repeated-failure` reminder uses this trigger and is appended to the failing tool result:

```text
<system-reminder>
{tool_name} failed {count} times with the same arguments. Stop retrying - verify your assumptions (list or search first) and take a different approach.
</system-reminder>
```

`{tool_name}` and `{count}` are substituted from the tracked failure; both placeholders work in your own `on_repeated_failure` reminder text.

#### Configuration sources and precedence

Reminders are resolved with the following precedence (highest first):

| Priority    | Source                   | Description                                                                                                                                                                              |
| ----------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 (Highest) | `INFER_REMINDERS_CONFIG` | Inline YAML string. When set, it **replaces** all file-loaded reminders.                                                                                                                 |
| 2           | `--reminders-file PATH`  | Load reminders from an arbitrary file path. Available on `infer headless` and `infer chat`.                                                                                              |
| 3           | Project config           | `./.infer/reminders.yaml`                                                                                                                                                                |
| 4           | User config              | `~/.infer/reminders.yaml`                                                                                                                                                                |
| 5 (Lowest)  | Built-in defaults        | The CLI ships a built-in `memory-consult` reminder that nudges the agent to consult the Memory tool, and a `repeated-failure` reminder that fires on the third failure of the same call. |

`INFER_REMINDERS_ENABLED` toggles the master switch on top of all sources — set it to `false` to disable all reminders regardless of the resolved config.

> **Disabling reminders drops mode instructions.** The mode-change reminder is the only carrier of per-mode instructions, so with `enabled: false` (or `INFER_REMINDERS_ENABLED=false`) the Plan and Auto-Accept guidance - including the destructive-action policy - is never delivered. Mode tool restrictions are unaffected.

#### `INFER_REMINDERS_CONFIG`

Set this environment variable to supply the full reminders YAML inline, without writing a `reminders.yaml` file. This is especially useful for CI/CD and embedded consumers (e.g. `infer-action`) that cannot write to `~/.infer/`.

```bash
export INFER_REMINDERS_CONFIG='enabled: true
reminders:
  - name: fail-nudge
    hook: post_tool
    trigger: on_failure
    text: "A failed call means the change did not happen"
'
```

When `INFER_REMINDERS_CONFIG` is set, it **replaces** the file-loaded config entirely — it is not merged. To disable it and fall back to file-based config, unset the variable.

#### `--reminders-file`

The `--reminders-file PATH` flag is available on `infer headless` and `infer chat`. It loads reminders from an arbitrary YAML file path, bypassing the default file resolution.

```bash
infer headless "Refactor the module" --reminders-file /path/to/custom-reminders.yaml
infer chat --reminders-file ./ci-reminders.yaml
```

#### Example: CI with inline reminders

```bash
INFER_REMINDERS_CONFIG='enabled: true
reminders:
  - name: fail-nudge
    hook: post_tool
    trigger: on_failure
    text: "A failed call means the change did not happen"
' INFER_REMINDERS_ENABLED=true infer headless "..."
```

### Essential Environment Variables

```bash
export INFER_GATEWAY_URL="http://localhost:8080"
export INFER_GATEWAY_API_KEY="your-api-key"
export INFER_AGENT_MODEL="deepseek/deepseek-v4-flash"
export INFER_LOGGING_DEBUG="true"
export INFER_LOGGING_ARCHIVE_ENABLED="true"
export INFER_LOGGING_ARCHIVE_MAX_SIZE_MB="1024"
export INFER_CLIENT_STALL_THRESHOLD_SEC="30"  # seconds without stream progress before reconnecting (0 disables)
export GITHUB_TOKEN="your-github-token"  # used by the gh CLI credential chain for GitHub operations

# Message queue backend (see Message Queue): memory (default), sqlite, postgres or redis
export INFER_QUEUE_TYPE="redis"
export INFER_QUEUE_NAME="my-shared-queue"  # empty scopes the queue to this process's session id
export INFER_QUEUE_POLL_INTERVAL="2s"

# Append a few commands onto the bash allowed-list baseline (comma- or newline-separated)
export INFER_TOOLS_BASH_ALLOW_APPEND="git commit,git push"

# How a needed approval is delivered: prompt | ipc | judge | block
export INFER_TOOLS_SAFETY_APPROVAL_BEHAVIOUR="prompt"

# Load user custom tools from another directory instead of ~/.infer/tools
export INFER_TOOLS_CUSTOM_DIR="/opt/my-app/tools"

# Inline reminders YAML (replaces file-loaded reminders)
export INFER_REMINDERS_CONFIG='enabled: true
reminders:
  - name: fail-nudge
    hook: post_tool
    trigger: on_failure
    text: "A failed call means the change did not happen"
'

# Master switch for reminders (default: true)
export INFER_REMINDERS_ENABLED=true

# Per-mode adjustment instructions, delivered by the mode-change reminder
# (supersede the deprecated INFER_PROMPTS_AGENT_SYSTEM_PROMPT_PLAN / _AUTO)
export INFER_PROMPTS_AGENT_MODE_ADJUSTMENT_PLAN="Investigate first; do not propose edits."
export INFER_PROMPTS_AGENT_MODE_ADJUSTMENT_AUTO="Confirm before any irreversible operation."

# Opt-in next-step suggestions (see Next-Step Suggestions)
export INFER_CHAT_SUGGESTIONS_ENABLED="true"
export INFER_CHAT_SUGGESTIONS_MODEL="deepseek/deepseek-v4-flash"  # empty falls back to the chat model
export INFER_CHAT_SUGGESTIONS_CONTEXT_MESSAGES="4"
export INFER_CHAT_SUGGESTIONS_MAX_TOKENS="512"
export INFER_CHAT_SUGGESTIONS_TIMEOUT="10"
export INFER_PROMPTS_CHAT_SUGGESTIONS_SYSTEM_PROMPT="Suggest one short next step."
```

### Configuration Commands

Configuration uses a generic key/value interface. `infer config get` reads the effective value of any key; `infer config set` writes one to the userspace baseline (`~/.infer/config.yaml`) by default, or to the project config (`./.infer/config.yaml`) when you pass `--project`. Keys are dotted paths into the config (for example `agent.model`, `gateway.url`). `tools.*` keys are **read-only** here - they live in [`~/.infer/tools.yaml`](#tool-configuration), so `config get tools.bash` works but `config set tools.*` is rejected.

```bash
# Initialize configuration
infer config init

# Print the whole effective config (defaults + ~/.infer + .infer + INFER_* env)
infer config get

# Print a single key
infer config get agent.model

# Print as JSON instead of YAML
infer config get --format json

# Set a value - parsed to the field's type (bool, integer, number, or string),
# then validated by loading the config back before the write is kept
infer config set agent.model deepseek/deepseek-v4-flash
infer config set agent.max_turns 50
infer config set agent.verbose_tools true

# List-valued keys take a comma-separated value (the whole list is replaced)
infer config set gateway.exclude_models "openai/gpt-4o,groq/llama-3"

# tools.* is rejected - the tools policy lives in ~/.infer/tools.yaml
# (config get tools still prints the effective values)
infer config get tools.bash

# config set writes the userspace baseline (~/.infer/config.yaml) by default
infer config set agent.model deepseek/deepseek-v4-flash

# Target the project config (./.infer/config.yaml) instead - it overrides the baseline key-by-key
infer config set agent.model deepseek/deepseek-v4-flash --project

# Recreate config.yaml from defaults
infer config init --overwrite
```

`config set` **validates before it keeps the write.** After writing, it loads the config back; if the loader rejects the result - say `agent.reasoning_effort=bogus` - the previous file is restored and the command fails, so a bad value can never leave you with a config that stops `infer` from starting:

```bash
$ infer config set agent.reasoning_effort bogus
agent.reasoning_effort = bogus was not saved: invalid agent.reasoning_effort "bogus": must be one of minimal, low, medium, high, xhigh, max
```

> System prompts are **not** set via `config set` - they live in `prompts.yaml` (for example `prompts.agent.system_prompt`, and the per-mode `prompts.agent.mode_adjustment_plan` / `mode_adjustment_auto`) and are edited there. The same file holds the **tool descriptions** sent to the model under `prompts.tools.<Tool>.description` - for example `prompts.tools.RequestApproval.description`, which ships with a built-in default explaining when a judge rejection may be escalated. Any key you leave out keeps its built-in text.

#### Command Mapping

The per-setting subcommands were removed in favor of `config get`/`config set` and the top-level `infer tools` command:

| Old command                            | New command                                                           |
| -------------------------------------- | --------------------------------------------------------------------- |
| `config agent set-model X`             | `config set agent.model X`                                            |
| `config agent set-max-turns N`         | `config set agent.max_turns N`                                        |
| `config agent verbose-tools enable`    | `config set agent.verbose_tools true`                                 |
| `config agent skills enable`           | `config set agent.skills.enabled true`                                |
| `config tools enable`                  | Set `enabled: true` in [`~/.infer/tools.yaml`](#tool-configuration)   |
| `config tools bash enable`             | Set `tools.bash.enabled` in `~/.infer/tools.yaml`                     |
| `config tools safety enable`           | Set `safety.require_approval` in `~/.infer/tools.yaml`                |
| `config tools safety set bash enabled` | Set `tools.bash.require_approval` in `~/.infer/tools.yaml`            |
| `config tools sandbox add DIR`         | Edit `filesystem.allowed` in [`~/.infer/sandbox.yaml`](#file-sandbox) |
| `config tools grep set-backend rg`     | Set `tools.grep.backend` in `~/.infer/tools.yaml`                     |
| `config tools web-fetch add-domain D`  | Add to `tools.web_fetch.allowed_domains` in `~/.infer/tools.yaml`     |
| `config export set-model X`            | `config set export.summary_model X`                                   |
| `config show`                          | `config get`                                                          |
| `config tools exec <tool>`             | `tools execute <tool>`                                                |
| `config tools validate <cmd>`          | `tools validate <cmd>`                                                |

See the [full configuration reference](https://github.com/inference-gateway/cli/blob/main/docs/configuration-reference.md) for detailed options.

### Reloading configuration in chat

`/reload` re-reads the [config files](#configuration-files) and the `INFER_*` environment in a running `infer chat`, so editing a setting no longer means restarting the session:

```bash
infer config set gateway.timeout 300
# then, in infer chat:
/reload
# status line: Reloaded gateway.timeout
```

**Hot keys** - these change the running session immediately:

| Key                      | Effect on reload                                                |
| ------------------------ | --------------------------------------------------------------- |
| `gateway.timeout`        | The next request uses the new timeout                           |
| `agent.model`            | Switches the active model, like [`/model`](#built-in-commands)  |
| `agent.max_turns`        | Applies from the next turn                                      |
| `agent.max_tokens`       | Applies from the next turn                                      |
| `agent.reasoning_effort` | Applies from the next turn, and the status bar follows          |
| `chat.status_bar.*`      | The whole section - indicators hide or show on the next repaint |

**Everything else needs a restart.** Any other changed key is named in the status line as "restart to apply" rather than silently ignored - `Reloaded agent.model · restart to apply gateway.url`. `gateway.url` and `gateway.api_key` are restart keys, and [tool policy](#tool-configuration), the [file sandbox](#file-sandbox) and approval policy never change mid-session, by design: a running agent keeps the permissions it started with.

Two cases leave the session exactly as it was, with the error shown instead:

- **The new config fails validation.** The previous config stays active.
- **The agent is busy.** `/reload` reports `agent is busy, run /reload after this turn` rather than swapping config under a running turn.

`/reload` is only available in `infer chat` - [headless](#headless-mode) and [scheduled](#schedule) runs load their config once at startup.

## Telemetry

The CLI records OpenTelemetry signals (metrics and traces) for every session. Telemetry is **on by default** and is turned off with `telemetry.enabled: false` (`INFER_TELEMETRY_ENABLED=false`) - no files are written, nothing is exported, and no trace context is passed to child processes. Data is written to local files under `~/.infer/telemetry/` and can optionally be exported to an OTLP/HTTP collector.

### Local files

Both signals write per-session JSONL files to `~/.infer/telemetry/`:

| Signal  | File pattern                                     | Description                                                                |
| ------- | ------------------------------------------------ | -------------------------------------------------------------------------- |
| Metrics | `~/.infer/telemetry/\<session-id\>.jsonl`        | Token usage, tool outcomes, session duration, and cost (delta temporality) |
| Traces  | `~/.infer/telemetry/\<session-id\>-traces.jsonl` | One root span per session, child spans for each LLM turn and tool call     |

The `\<session-id\>` is the same UUID that appears in the CLI's session output and conversation storage. Local files use the OTLP/semconv JSON format as-is - no custom encoding.

### Metrics

The CLI records the following metrics using the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/):

- **gen_ai.client.token.usage** - input and output token counts per LLM request
- **gen_ai.execute_tool.duration** - tool execution duration in seconds
- **infer.agent.runs** - total agent session count
- **infer.agent.run.duration** - session duration in seconds
- **infer.client.cost** - computed dollar cost per session

Metrics use **delta temporality** (required by the gateway ingest, and what makes the local files trivially summable by `infer stats`).

### Traces

The CLI emits one **trace per session** with the following span hierarchy:

- **session** (root span) - carries `infer.execution.mode`, `infer.agent.mode`, `infer.run.outcome`, and `gen_ai.conversation.id`
- **chat \<model\>** (CLIENT kind) - one per LLM request, with `gen_ai.request.model`, `gen_ai.provider.name`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`
- **execute_tool \<name\>** (INTERNAL kind) - one per tool call, with `gen_ai.tool.name`, `gen_ai.tool.type`, `infer.tool.outcome`

No prompt or response content is recorded in spans. Failed spans carry `error.type` and Error status per the OpenTelemetry recording-errors conventions.

Spans emitted by subprocesses - Bash tool commands, [skill](/cli-skills/) scripts, and headless subagents - are ingested and nested under their originating `execute_tool` span, so a single trace can span multiple processes. See [Trace context propagation to subprocesses](#trace-context-propagation-to-subprocesses).

### OTLP/HTTP export

Both signals can be exported to an OpenTelemetry Collector or any OTLP/HTTP-compatible backend by setting the standard OpenTelemetry environment variables:

```bash
# Base endpoint (each signal appends its own path: /v1/metrics, /v1/traces)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

# Optional: per-signal endpoint overrides (takes precedence over the base)
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://otel-collector:4318/v1/metrics
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4318/v1/traces

# Headers (e.g. for authentication)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20my-token"

# Service identity (merged into the resource attributes on every signal)
export OTEL_SERVICE_NAME=infer-cli
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,actor=ci-bot"
```

When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, the CLI exports both signals to that endpoint. Per-signal env vars (`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) override the base for that signal. Headers and timeouts follow the standard OTel exporter env-var spec. The CLI builds no OTel log provider, so `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` has no effect.

Local file export is **always active** regardless of OTLP configuration - remote export is additive, not a replacement.

### Local OTLP receiver (`telemetry.receiver_address`)

By default, the CLI runs an ephemeral loopback OTLP/HTTP receiver (`127.0.0.1:0`) that accepts spans from subprocesses (Bash tool commands, headless subagents) and persists them into the per-session trace file. This receiver is **loopback-only** and auto-allocated, so it is invisible to external processes.

When you need an external OpenTelemetry Collector (or any OTLP producer) to feed spans back into the CLI's local trace store - for example to see a remote A2A agent's spans in `infer traces` - set `telemetry.receiver_address` to a fixed address:

```yaml
# .infer/config.yaml
telemetry:
  receiver_address: 0.0.0.0:4318
```

```bash
# Environment variable
export INFER_TELEMETRY_RECEIVER_ADDRESS=0.0.0.0:4318
```

When set, the receiver binds to that address at startup (instead of a random loopback port) and accepts OTLP/HTTP `POST /v1/traces` (protobuf) from any reachable producer. Received spans are filtered to the session's trace ID and appended to the local trace file, where they appear in `infer traces` nested under the originating `execute_tool` span.

**Defensive limits:** 4 MiB per request body, 5000 spans per session. The receiver always responds 200 - receiver failures never fail the tool.

### Example: OpenTelemetry Collector

To receive both signals from the CLI, configure an OpenTelemetry Collector with OTLP/HTTP receivers:

```yaml
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  debug:
    verbosity: detailed
  otlp/jaeger:
    endpoint: jaeger-collector:4317
    tls:
      insecure: true

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [debug]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/jaeger, debug]

processors:
  batch:
    send_batch_size: 1024
    timeout: 5s
```

Then run the CLI with the endpoint set:

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
infer headless "Analyze the codebase"
```

### Trace context propagation to subprocesses

When telemetry is enabled (`telemetry.enabled: true`, the default), the CLI propagates its active trace context into the processes it spawns, so spans emitted by tools and subagents stitch into the **same trace** as the CLI session. Propagation is built entirely on open standards - [W3C Trace Context](https://www.w3.org/TR/trace-context/) and [W3C Baggage](https://www.w3.org/TR/baggage/) on the way out, plain [OTLP](https://opentelemetry.io/docs/specs/otlp/) spans on the way back - so **any OpenTelemetry-instrumented tool participates with zero custom code**. When telemetry is disabled, none of these variables are set.

#### Environment variables set for child processes

The [Bash tool](#command-execution) (and therefore [skill](/cli-skills/) scripts) and headless [subagents](#local-subagents-agent-tool) receive:

| Variable                     | Standard                                                  | Contents                                                                                     |
| ---------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `TRACEPARENT` / `TRACESTATE` | [W3C Trace Context](https://www.w3.org/TR/trace-context/) | The current trace, parented on the active `execute_tool` span, so child spans nest under it. |
| `BAGGAGE`                    | [W3C Baggage](https://www.w3.org/TR/baggage/)             | `session.id` and `gen_ai.tool.call.id`, for correlating child spans back to the call.        |

The two baggage member names are configurable: `telemetry.attr_session_id_key` and `telemetry.attr_tool_call_id_key` override `session.id` and `gen_ai.tool.call.id` respectively.

#### Where child spans are sent (OTLP sink selection)

The CLI selects the span sink automatically so children report to the same place the CLI does:

- **An OTLP endpoint is configured** (`telemetry.otlp.endpoint`, or the standard `OTEL_EXPORTER_OTLP_ENDPOINT`) - the endpoint and its headers are passed through to the child environment as `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS`, so child spans land in the same remote backend and stitch into the trace there.
- **No endpoint configured** (the default) - the CLI runs an **ephemeral localhost OTLP/HTTP receiver** for the session and points children at it. Received spans are persisted into the local per-session [trace store](#viewing-traces) and appear in `infer traces` / `/traces`, nested under the tool span that spawned them.

Either way you get one coherent trace - local by default, in your backend when you have one.

#### Example: any OTel-instrumented command

Because propagation is standard OTLP, an off-the-shelf tool such as [`otel-cli`](https://github.com/equinix-labs/otel-cli) emits a correctly parented child span with no wiring. Run it inside a Bash tool call:

```sh
otel-cli exec --name "go test" -- go test ./...
```

The resulting `go test` span shows up as a child of `execute_tool Bash` in `infer traces`:

```text
session (standard, success)                12.4s
`-- execute_tool Bash                        9.8s
    `-- go test                              9.6s
```

The same holds for a program instrumented with an OpenTelemetry SDK: as long as it reads the standard `OTEL_EXPORTER_OTLP_ENDPOINT` and `TRACEPARENT` variables - which every conformant SDK does - its spans nest under the `execute_tool` span automatically, with no CLI-specific integration.

#### Subagents: one cross-process trace

`infer headless` honors an inherited `TRACEPARENT`, so a headless subagent's own `session` span nests under the caller's `execute_tool Agent` span - a single trace that spans both processes:

```text
session (standard, success)            152ms
|-- execute_tool Agent                  89ms
|   `-- session (readonly, success)     52ms
|       `-- chat openai/gpt-4o          13ms
```

#### Remote A2A agents

Outbound [A2A](/a2a/) requests carry `traceparent`, `tracestate`, and `baggage` HTTP headers, so a remote agent can continue the trace. This is **context-out only**: remote spans stitch into your trace through a **shared OTLP collector** that both sides export to - they are not written back into the local per-session trace store. Point both the CLI and the remote agent at the same `telemetry.otlp.endpoint` to see the full cross-service trace.

#### A2A traces example

The [`examples/a2a-traces`](https://github.com/inference-gateway/cli/tree/main/examples/a2a-traces) directory in the CLI repository demonstrates end-to-end distributed telemetry between the CLI and a remote A2A agent (mock-agent), with an OpenTelemetry Collector in the middle. It exercises both telemetry models:

- **Push (OTLP)**: the CLI exports its traces and metrics to the collector; the mock-agent exports its traces to the collector.
- **Pull (Prometheus)**: the collector scrapes the mock-agent's `:9090/metrics` endpoint.

The CLI injects W3C trace context into every outgoing A2A request, so the mock-agent's spans share the CLI's trace ID and parent under the CLI's `execute_tool` span. The collector fans all traces back to the CLI's local OTLP receiver (via `INFER_TELEMETRY_RECEIVER_ADDRESS: 0.0.0.0:4318`), so `infer traces` shows the **full distributed trace**, including the mock-agent's spans:

```text
session (standard, success)                 152ms
|-- chat deepseek/deepseek-v4-flash             5ms
|-- execute_tool A2A_SubmitTask              89ms
|   `-- a2a.request [mock-agent]             52ms
`-- chat deepseek/deepseek-v4-flash            12ms
```

Ingested foreign spans are labeled `name [service]` from the producer's `service.name` resource attribute - for example `a2a.request [mock-agent]`.

To run the example:

```bash
cd examples/a2a-traces
cp .env.example .env   # set at least one provider API key
docker compose up -d --build
docker compose attach cli
# In the CLI, ask: "Ask the mock-agent to summarize the current project."
# Detach with ctrl-p ctrl-q, then:
docker compose exec cli infer traces
```

See the [example README](https://github.com/inference-gateway/cli/tree/main/examples/a2a-traces) for full configuration notes and troubleshooting.

#### Limitations

- **Interactive (tmux-pane) subagents are not stitched** into the caller's trace - only headless subagents inherit the context. Use `mode: headless` when you need a subagent's spans in the same trace.
- **Detached background shells that outlive the CLI lose late spans** - once the CLI (and its ephemeral receiver) exits, spans emitted afterward have nowhere local to land. Configure a persistent `telemetry.otlp.endpoint` for long-running detached work.

### Viewing telemetry data

- **Local files** - the JSONL files under `~/.infer/telemetry/` are plain text and can be inspected with any JSON tool:

  ```bash
  # List telemetry files
  ls ~/.infer/telemetry/

  # View metrics for a session
  cat ~/.infer/telemetry/\<session-id\>.jsonl | jq .

  # View traces for a session
  cat ~/.infer/telemetry/\<session-id\>-traces.jsonl | jq .
  ```

- **`infer stats`** - aggregates metrics from local files into a summary of tool outcomes, token usage, and sessions. Trace files are excluded from the aggregate. The per-tool **Avg** column renders microseconds (for example `432us`) when the mean duration is below 1ms and milliseconds otherwise, so fast tools no longer collapse to `0ms`. In `infer stats --format json` the matching `avg_ms` field can be fractional (for example `0.432`) rather than an integer. The same applies to `infer insights` and the [`/stats`](#telemetry-shortcuts) shortcut.
- **`infer traces`** - renders the span tree of a session from its local trace file. See [Viewing traces](#viewing-traces).
- **`infer insights`** - analyzes past sessions for repeatable workflows and recurring tool failures. The verbatim error and log samples it collects are **redacted before the model call** - PEM private-key blocks, GitHub token shapes, and the values of provider-secret env vars (plain and JSON-escaped) are replaced with `[redacted]`, in the digest and in the saved report alike. See [Insights Shortcut](#insights-shortcut).
- **Remote backend** - when OTLP export is configured, data appears in your collector's configured backend (Jaeger for traces, your metrics store).

### Viewing traces

`infer traces` renders the span tree of a session - the session root span, its LLM turns, and the tool calls nested under each turn - with a duration next to every span. It reads the local per-session trace file (`~/.infer/telemetry/\<session-id\>-traces.jsonl`) directly, so it works **fully offline** with no OTLP collector required.

```bash
# Render the most recent session's span tree
infer traces

# Render a specific session by ID
infer traces abc-123-def

# List the sessions that have trace files
infer traces --list

# Emit the tree as structured JSON
infer traces --format json
```

With no session ID, `infer traces` picks the **most recent** session. The default output is an indented span tree:

```text
session (standard, success)                38.8s
|-- chat ollama_cloud/deepseek-v4-flash     3.4s
|-- execute_tool Read                      162us
`-- chat ollama_cloud/deepseek-v4-flash     8.1s
```

Spans that finished with an error status (or carry an `error.type` attribute) are flagged inline with an `[error: ...]` marker showing the error type - for example `[error: context_deadline_exceeded]`.

Spans ingested from subprocesses appear in the same tree, nested under the `execute_tool` span that spawned them - Bash tool commands (including `otel-cli` and OpenTelemetry-SDK-instrumented programs) and headless subagents. See [Trace context propagation to subprocesses](#trace-context-propagation-to-subprocesses) for how the context is passed and where child spans are collected.

Spans ingested from external producers (for example a remote A2A agent or an OpenTelemetry Collector) are labeled with the producer's `service.name` resource attribute: `name [service]`. For example, a span named `a2a.request` from a service called `mock-agent` renders as `a2a.request [mock-agent]` in the tree. This makes it easy to identify which service produced each span in a distributed trace.

`--format json` emits the same tree as structured output - each node carries the span name, start time, duration in fractional milliseconds, attributes, and an array of child spans - ready to pipe into `jq` or a custom viewer:

```json
{
  "name": "session",
  "start_time": "2026-07-14T09:12:03.145Z",
  "duration_ms": 38800.0,
  "attributes": {
    "infer.execution.mode": "standard",
    "infer.run.outcome": "success"
  },
  "children": [
    {
      "name": "chat ollama_cloud/deepseek-v4-flash",
      "start_time": "2026-07-14T09:12:03.150Z",
      "duration_ms": 3400.0,
      "attributes": { "gen_ai.request.model": "deepseek-v4-flash" },
      "children": []
    }
  ]
}
```

The same view is available inside a chat session with the [`/traces`](#telemetry-shortcuts) shortcut.

## Shortcuts

The CLI provides built-in commands, YAML shortcuts, and Agent Skills - all reachable by typing `/` in chat.

### Autocomplete kinds

Typing `/` opens the autocomplete list, and every row carries a **kind label** telling you what it is and where it comes from (the same labels the [desktop composer](/desktop/) uses):

| Label          | What it is                                                                         | Where it lives                                                                  |
| -------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `command`      | Built-in shortcut compiled into the CLI - views and wizards it implements itself   | The binary - see [Built-in Commands](#built-in-commands)                        |
| `shortcut`     | YAML shortcut, including the ones `infer init` seeds                               | `.infer/shortcuts/*.yaml` - see [YAML Shortcuts](#yaml-shortcuts)               |
| `skill`        | Installed [Agent Skill](/cli-skills/) - `/<name>` activates it for the turn        | `./.infer/skills/` or `~/.infer/skills/`                                        |
| `remote skill` | Catalog skill not installed yet - `/<name>` downloads it first (confirmed in chat) | The [skills catalog](/cli-skills/#the-skills-catalog-and-agentskillsrepository) |

A `command` always wins over a YAML `shortcut` of the same name, so a stale shortcut file can never shadow a built-in view. See [Shortcut precedence](#custom-shortcuts).

### Built-in Commands

These show as `command` in autocomplete:

| Shortcut              | Description                                                                                          | Example                             |
| --------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `/model [name] [msg]` | Switch the active model, or run one message with another model                                       | `/model deepseek/deepseek-v4-flash` |
| `/init`               | Fill the input with the AGENTS.md project-analysis prompt                                            | `/init`                             |
| `/install-opentask`   | Ask the agent to install or update the [`infer-action` workflow](#github-action-setup) and open a PR | `/install-opentask`                 |
| `/agents`             | View every configured agent - local Markdown presets and remote A2A agents - with their state        | `/agents`                           |
| `/tasks`              | View background work (A2A tasks, shells, subagents) with live status and captured output             | `/tasks`                            |
| `/tools`              | View a filterable list of tools available in the current agent mode, including MCP tools             | `/tools`                            |
| `/stats`              | Summarize the session's token usage, tool outcomes, and cost (mirrors `infer stats`)                 | `/stats`                            |
| `/traces [id]`        | Render a session's trace span tree offline (mirrors `infer traces`)                                  | `/traces`, `/traces abc-123-def`    |
| `/voice [seconds]`    | Record the mic and transcribe to the input field (requires [speech-to-text](/cli-speech-to-text/))   | `/voice`, `/voice 8`                |
| `/reload`             | Re-read config files and `INFER_*` env, applying the [hot keys](#reloading-configuration-in-chat)    | `/reload`                           |

### YAML Shortcuts

`infer init` seeds these into `~/.infer/shortcuts/`, so they show as `shortcut` in autocomplete. They are ordinary [custom shortcuts](#custom-shortcuts) - editable, removable, and replaceable with your own:

| Shortcut            | Description                                                                                                                                                              | Example                                   |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| `/git <cmd>`        | Git operations                                                                                                                                                           | `/git status`, `/git commit`, `/git push` |
| `/scm <cmd>`        | GitHub operations                                                                                                                                                        | `/scm issues`, `/scm issue 123`           |
| `/mcp <cmd>`        | Manage MCP servers                                                                                                                                                       | `/mcp list`, `/mcp add`                   |
| `/skills <cmd>`     | Manage Agent Skills                                                                                                                                                      | `/skills list`, `/skills install <url>`   |
| `/shells`           | List running and recent background shells                                                                                                                                | `/shells`                                 |
| `/export`           | Export the current conversation to Markdown                                                                                                                              | `/export`                                 |
| `/env`              | Generate a `.env.example` with the provider API keys                                                                                                                     | `/env`                                    |
| `/insights [since]` | Analyze past sessions for repeatable workflows and recurring tool failures (secrets [redacted](#insights-shortcut) before the model call and before the report is saved) | `/insights`, `/insights 7d`               |
| `/reset [arg]`      | Wipe all local runtime state on this machine and start a fresh session                                                                                                   | `/reset`, `/reset confirm`                |

### Git Shortcuts

```bash
# Execute git commands
/git status
/git branch

# AI-generated commit message
/git commit

# Push to remote
/git push origin main
```

### SCM (GitHub) Shortcuts

```bash
# List GitHub issues
# Runs: gh issue list --json ... --limit 20
/scm issues

# View issue details
# Runs: gh issue view 123 --json ...
/scm issue 123
```

The seeded `scm.yaml` defines only these two subcommands. For pull-request work, ask the agent directly - `gh pr create` is a write, so it falls through to [approval](#default-gh-allowed-list) - or add your own subcommand to the shortcut file.

### Telemetry Shortcuts

`/stats` and `/traces` surface the CLI's local [telemetry](#telemetry) from inside a chat session, mirroring the `infer stats` and `infer traces` commands.

- `/stats` summarizes the session's token usage, tool outcomes, and cost. Its markdown and vertical views use the same duration formatting as `infer stats`: the **Avg** column shows microseconds (for example `432us`) below 1ms and milliseconds otherwise.
- `/traces [session-id]` renders the span tree of a session - the session root, its LLM turns, and the tool calls under each turn - with per-span durations. With no argument it shows the most recent session.

```text
session (standard, success)                38.8s
|-- chat ollama_cloud/deepseek-v4-flash     3.4s
|-- execute_tool Read                      162us
`-- chat ollama_cloud/deepseek-v4-flash     8.1s
```

Both read the local files under `~/.infer/telemetry/`, so they work fully offline. See [Viewing traces](#viewing-traces) for the `infer traces` command, its `--list` and `--format json` flags, and how error spans are marked.

### Insights Shortcut

`/insights [since]` (and the equivalent `infer insights`) analyzes past sessions for repeatable workflows worth turning into a [skill](#agent-skills) and for recurring tool failures. The optional `since` argument limits the window (for example `/insights 7d`). It reads local sessions and telemetry, builds a digest, sends that digest to the configured model, and writes the report to `~/.infer/insights/`.

**Secrets are redacted locally before any network call.** The digest is masked before it reaches the analysis model, and the saved report is masked before it is written to disk. Redaction covers:

- PEM private-key blocks (always on).
- GitHub token shapes: `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`, and `github_pat_`.
- The values of provider-secret environment variables set in the environment, both plain and JSON-escaped (so a key quoted inside a captured JSON payload is masked too).

Each match is replaced with `[redacted]`. Because the masking runs before the model call and before the file write, pointing insights at collected sessions does not ship verbatim API keys or private keys to the provider, and the report you keep or share carries the same guarantee. Redaction targets known secret shapes and configured provider-secret values - it is not a substitute for keeping unrelated sensitive data out of session transcripts.

If conversation storage is disabled or no model is configured, the analysis is skipped with a notice.

### Reset Shortcut

`/reset` wipes the CLI's **local runtime state on the whole machine** - not just the current project - and starts a fresh session. It is a two-step shortcut: a bare `/reset` only previews, and `/reset confirm` performs the wipe.

```bash
# Preview what would be deleted (deletes nothing)
/reset

# Analyze the sessions first, then preview
/reset insights

# Actually delete everything listed in the preview
/reset confirm
```

Both steps end with a disk-space total: the preview ends with `Total reclaimable space: <size>`, and `/reset confirm` ends with `Total reclaimed space: <size>` after the wipe. The confirm total counts only targets that were actually removed, so anything the wipe failed to delete is excluded. Sizes are formatted like `docker system prune` - decimal units and 4 significant digits (for example `1.653GB`, `4.096kB`). The same totals appear when running `infer reset` and `infer reset confirm` directly.

`/reset confirm` only deletes after a preview was shown in the same session (within the last 5 minutes). A cold `/reset confirm` prints the preview instead, so a tab-completed confirm cannot wipe anything by accident.

**Deleted**, for every project under `~/.infer/projects/`: conversations, plans, scratch dirs, artifacts, history, backups, exports, logs, telemetry, schedules, pid/lock files, and both tmp trees including their [media roots](#media-directories) (generated speech, music, video, screen recordings, screenshots, retained voice recordings and attachments). With the SQLite backend the conversation database and its WAL sidecars go too.

**Preserved**: configuration (`config.yaml`, custom shortcuts, skills, `projects.yaml`), the [avatar library](/cli-text-to-video/#the-avatar-library) under `~/.infer/avatars/`, and saved [insights reports](#insights-shortcut) under `~/.infer/insights/` (written redacted). Directories you pointed outside `~/.infer` (for example a `text_to_speech.output_dir` of `/data/tts`) are left alone.

**Remote conversation stores are skipped.** If [`storage.type`](#conversation-management) is `postgres`, `redis`, or `d1`, `/reset` clears local state only and prints a notice that the remote store was left untouched - it is not an error.

`/reset insights` runs the [`/insights`](#insights-shortcut) analysis (repeatable workflows worth turning into a skill, recurring tool failures) before the preview, so you can capture what past sessions were worth learning from before deleting them. The report is written to `~/.infer/insights/` - with secrets redacted, as for any insights run - and survives the reset. If conversation storage is disabled or no model is configured, the analysis is skipped with a notice and the preview is still shown.

### Voice Shortcut

The `/voice` shortcut records audio from your microphone, transcribes it locally with [whisper.cpp](https://github.com/ggml-org/whisper.cpp), and places the text into the input field - ready to review and send. It is **disabled by default** and only appears when `speech_to_text.enabled` is `true`.

```bash
# Record until you go quiet (or the max cap), then transcribe
/voice

# Record for at most 8 seconds
/voice 8
```

Recording stops automatically a couple of seconds after you stop speaking (`speech_to_text.silence_timeout`), at the `max_recording_seconds` cap, or at the per-call override. See [Speech-to-Text](/cli-speech-to-text/) for prerequisites, configuration, and model selection.

### GitHub Action Setup

`/install-opentask [owner/repo] [extra context...]` asks the agent to install or update the [`infer-action` GitHub Action](/github-action/) workflow in a repository and open a pull request with it. It is not a wizard - the shortcut submits a task into the conversation, so the run streams like any other turn and every write goes through normal tool approval.

> For a full reference of `infer-action` inputs, outputs, and workflow recipes (PR review, scheduled summaries, release notes), see the [GitHub Action documentation](/github-action/).

With no argument it targets the repository of the current checkout; pass `owner/repo` to target another one. Anything after the repository is handed to the agent as workflow configuration, for example a model or a timeout to use.

```bash
infer chat
> /install-opentask
> /install-opentask my-org/my-service model: deepseek/deepseek-v4-flash
```

**What the agent does:**

1. Reads the `opentask` catalog skill, which carries the canonical `infer-action` workflow and its example workflows - it works from the skill rather than fetching docs over the network.
2. Adds a git worktree under `/tmp` when the target is the current checkout, or shallow-clones the target repository, so your working branch is never touched.
3. Checks out the fixed branch `infer/install-github-action`, on top of the remote branch if one already exists.
4. Creates or updates `.github/workflows/tasks.yml`, following both the skill's canonical workflow and the repository's existing CI conventions.
5. Summarizes the diff, then commits, pushes, and opens or updates the pull request - asking for your approval on the push and on the PR.

Re-running the shortcut updates that same branch and pull request instead of opening a duplicate.

**Prerequisites:** the [GitHub CLI](https://cli.github.com) installed and authenticated (`gh auth login`), with write access to the target repository.

**Repository secrets:** the generated workflow expects these in the target repository, or in its organization:

- `INFER_APP_ID` - GitHub App ID, when authenticating as a GitHub App instead of with the default `GITHUB_TOKEN`
- `INFER_APP_PRIVATE_KEY` - the App's private key (`.pem` contents)
- Provider API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, and so on)

For organization repositories the CLI checks whether the `INFER_APP_*` org secrets already exist, so an App registered once can be reused across repositories. See [Secrets and least-privilege](/github-action/#secrets-and-least-privilege) for why an App token beats `GITHUB_TOKEN`.

**Usage in issues:** once the workflow is merged, mention `@infer` in any issue or issue comment to activate the agent:

```text
@infer Please analyze this bug and suggest a fix
```

For more information on the `infer-action` GitHub Action, see the [GitHub Action documentation](/github-action/) or the [upstream repository](https://github.com/inference-gateway/infer-action).

### Custom Shortcuts

Create YAML files in `.infer/shortcuts/` directory. Shortcuts support three types:

#### 1. Simple Commands

Execute a single command:

```yaml
# .infer/shortcuts/simple.yaml
shortcuts:
  - name: hello
    description: 'Say hello'
    command: echo
    args:
      - 'Hello from Inference Gateway!'
```

#### 2. Shortcuts with Subcommands

Group related commands under a parent shortcut:

```yaml
# .infer/shortcuts/dev.yaml
shortcuts:
  - name: dev
    description: 'Development operations'
    command: bash
    subcommands:
      - name: test
        description: 'Run all tests'
        command: bash
        args:
          - -c
          - 'go test ./...'

      - name: build
        description: 'Build the project'
        command: bash
        args:
          - -c
          - 'go build -o app .'
```

A subcommand that declares its own `command:` runs that command with its `args` verbatim - `/dev test` runs `bash -c 'go test ./...'`. A subcommand without its own `command:` reuses the parent's `command` and gets its `name` (then its `args`) appended to the parent's `args`, so spell out the full invocation in every subcommand.

Usage: `/dev test`, `/dev build`

#### 3. AI-Powered Snippets

Use LLM to generate dynamic content based on command output. The `snippet.prompt` can reference JSON fields from command output using `{fieldName}` placeholders, and `snippet.template` uses `{llm}` for the AI-generated response:

```yaml
# .infer/shortcuts/ai-commit.yaml
shortcuts:
  - name: ai-commit
    description: 'AI-generated commit message'
    command: bash
    args:
      - -c
      - |
        diff=$(git diff --cached)
        jq -n --arg diff "$diff" '{"diff": $diff}'
    snippet:
      prompt: "Generate commit message for:\n{diff}"
      template: '!git commit -m "{llm}"'
```

The command must output JSON. Fields are accessible in the prompt template via `{fieldName}` syntax. The LLM response is accessible via `{llm}` in the template.

#### Name collisions with built-ins

A [built-in command](#built-in-commands) always wins over a custom YAML shortcut of the same name - the custom one is skipped with a warning naming the file, so a stale shortcut file can never shadow a built-in view such as [`/agents`](#agents-view). Rename the custom shortcut to reach it again.

## Advanced Features

### Cost Tracking

Real-time token usage and cost calculation displayed in the status bar.

**Features:**

- Per-model pricing calculation
- Cumulative session costs
- Input and output token tracking
- Status bar indicator
- Custom pricing support

**View Costs:**

```bash
# Costs displayed in status bar during chat
infer chat
# Status bar shows model and current cost

# Inspect a saved conversation's entries (per-entry metadata, including model)
infer conversations show <session-id>

# Same, as one JSON object per line for piping into jq
infer conversations show <session-id> --format json | jq .
```

#### Pricing Configuration

Pricing lives under the `pricing` key in `.infer/config.yaml`. The `custom_prices` map overrides or adds entries to the built-in per-model pricing table, keyed by model name.

```yaml
# .infer/config.yaml
pricing:
  enabled: true
  currency: 'USD'
  custom_prices:
    'ollama_cloud/deepseek-v4-pro':
      input_price_per_mtoken: 0.0
      output_price_per_mtoken: 0.0
      requires_pro: true
```

| Field                     | Type    | Description                                                                   |
| ------------------------- | ------- | ----------------------------------------------------------------------------- |
| `input_price_per_mtoken`  | number  | Cost per 1M prompt (input) tokens, in `currency`.                             |
| `output_price_per_mtoken` | number  | Cost per 1M completion (output) tokens, in `currency`.                        |
| `requires_pro`            | boolean | Marks the model as gated behind a paid Pro subscription. Defaults to `false`. |

Subscription-gated models are billed at **zero session cost** regardless of the rates on the entry. Use non-zero rates with `requires_pro: true` to keep an informational rate in the picker label while a flat-fee subscription covers the actual billing:

```yaml
pricing:
  enabled: true
  custom_prices:
    ollama_cloud/glm-5.3-flash:
      input_price_per_mtoken: 0.15
      output_price_per_mtoken: 0.50
      requires_pro: true # informational rate only, billed as flat-fee subscription
```

> **Override caveat:** a `custom_prices` entry **fully replaces** the default for that model - it is not merged field by field. Omitting `requires_pro` in a custom override therefore resets it to `false`, even when the model is flagged Pro by default. Set `requires_pro: true` explicitly when overriding the pricing of a Pro model.

#### Model Categories (Free / Pay-as-you-go / Subscription)

The model picker's [pricing tab row](#filter-tabs) - `[1] All`, `[2] Free`, `[3] Pay-as-you-go`, `[4] Subscription` - groups models into three disjoint categories:

| Category      | Meaning                                                         |
| ------------- | --------------------------------------------------------------- |
| Free          | No per-token cost **and** not subscription-gated.               |
| Pay-as-you-go | Billed per token.                                               |
| Subscription  | Gated behind a paid subscription rather than per-token billing. |

Subscription is an axis **orthogonal to price**: an Ollama Cloud model is not metered per token but is not free, so it is labelled `pro subscription` rather than `free`. A subscription model may still carry a per-token rate - the gateway keeps the provider's pay-as-you-go rate for reference - in which case the picker shows the rate with a `subscription` suffix. The marker appears both in the picker rows and in `/model` autocomplete descriptions:

```
ollama_cloud/deepseek-v4-pro   (1M, pro subscription)
ollama_cloud/glm-5.3-flash     (1M, $0.15/$0.50 per MTok, subscription)
deepseek/deepseek-v4-flash     (1M, $1.74/$3.48 per MTok)
```

**Subscription models cost zero per session.** The session cost line and the status-bar cost report `$0.00` for any subscription-gated model, even when the picker label shows a rate - the rate is informational and the flat-fee subscription covers usage. This applies whether the model is flagged by the gateway (`pricing.subscription: true`) or by a `custom_prices` entry with `requires_pro: true`, as in the [example above](#pricing-configuration).

The classification comes from the **gateway's pricing metadata** - the `pricing.subscription` flag reported per model - so it tracks the gateway catalog with no CLI-side list to maintain. A `custom_prices` entry still wins: set `requires_pro: true` to gate a model the gateway does not flag, or `false` to un-gate one (remembering the [override caveat](#pricing-configuration) that an entry fully replaces the default).

> The gateway flag replaced the previous hardcoded list of Pro models. Subscription models with per-token rates bill at zero cost while keeping their published rates.

### Model Thinking Visualization

Collapsible thinking blocks for models that support thinking (Claude, o1, etc.).

**Features:**

- Collapsible blocks with first sentence preview
- **Ctrl+K** keyboard shortcut to toggle
- Theme-aware styling
- Performance optimization (long thinking blocks collapsed by default)

**Usage:**

```bash
infer chat
# Ask complex question requiring reasoning
> "Design a scalable microservices architecture for e-commerce"
# Model's thinking process displayed in collapsible blocks
# Press Ctrl+K to expand/collapse thinking
```

### Conversation Management

**Storage Backends:**

- **JSONL** (default): append-only files under `~/.infer/projects/<project-slug>/conversations/`
- **SQLite**: one shared database at `~/.infer/conversations.db`
- **PostgreSQL**: Shared team database
- **Redis**: High-performance caching
- **Cloudflare D1**: External SQLite over Cloudflare's HTTP query API
- **In-memory**: Temporary sessions

The [message queue](#message-queue) is configured separately through `queue.*` and reuses these same `storage.<type>` connection settings when it runs on a durable backend.

**Features:**

- Automatic conversation history
- AI-generated titles (batch: 10 messages)
- Token optimization with compaction
- Backend-agnostic inspection via the storage layer (works the same across `jsonl`, `sqlite`,
  `postgres`, `redis`, `d1`, and `memory`)

**Where conversations live:**

Conversations are stored in your home directory, grouped per project - nothing
conversation-related is written to the project directory:

- **jsonl**: `~/.infer/projects/<project-slug>/conversations/<id>.jsonl`, where
  `<project-slug>` is the absolute project path with the separators replaced
  (`/home/alice/repo` becomes `-home-alice-repo`).
- **sqlite**: one shared database at `~/.infer/conversations.db`, with each row carrying a
  `project` column.
- **postgres**, **redis**, **d1**: one shared store, grouped by the same `project` field in the
  conversation metadata.

Every session records the project it ran in (its absolute working directory), and listings scope
to the current project by default: the `/conversations` TUI picker shows only this project's
conversations, and so does `infer conversations list` - pass `--all-projects` to list every
project's conversations.

An explicit `storage.jsonl.path` or `storage.sqlite.path` always overrides these defaults, and
such a store only ever lists itself.

> **No migration.** Stores written by older versions under the project's `.infer/conversations`
> or `.infer/conversations.db` are orphaned by design - the CLI no longer reads or writes them.
> Delete them manually when you no longer need them. The generated `.infer/.gitignore` no longer
> ignores `conversations` / `conversations.db*`.

**Subcommands:**

- `list`: List saved conversations with metadata (id, title, message/request counts, tokens,
  cost). Scoped to the current project; `--all-projects` lists every project's conversations.
- `show <session-id>`: Print a single conversation's entries in chronological order (role,
  timestamp, content, and `tool_call_id` for tool results).
- `delete <session-id>`: Remove a conversation from the storage backend. Runs
  non-interactively with no confirmation prompt. Unknown or missing session id exits
  non-zero with an error from the storage layer.

**`delete` notes:**

- Runs non-interactively - no confirmation prompt, so scripts and the desktop app can
  shell out to it.
- Unknown or missing session id exits non-zero with a clear error from the storage layer
  (e.g. `conversation not found: <id>`).
- Session id resolution follows the same rules as `show` (see below).

**`show` flags:**

- `--include-hidden`: Include entries persisted as hidden - system reminders, plan-approval
  prompts, drained background-task results, and the synthetic verify message injected by
  `infer headless`. Off by default.
- `--format text|json`: `text` (default) is human-readable; `json` emits one JSON object per
  line (NDJSON), matching the `infer headless` stdout shape for piping into `jq` or log scrapers.

**Session id resolution:**

`<session-id>` is resolved the same way as [`infer headless --session-id`](#resuming-a-session-session-id) and
[`infer chat --session-id`](#resuming-a-session---session-id): a literal UUID is used
as-is, while any other value is treated as a session group key and resolved to that group's
current session id (registering the group if it is new). This means you can show a conversation
by group name such as `channel-telegram-12345`.

**Commands:**

```bash
# List this project's conversations to find a session id
infer conversations list

# List conversations from every project
infer conversations list --all-projects

# Show a conversation's entries (hidden entries omitted by default)
infer conversations show 12345678-1234-1234-1234-123456789abc

# Show by session group name (for example a channel group key)
infer conversations show channel-telegram-12345

# Include hidden entries such as system reminders
infer conversations show <session-id> --include-hidden

# One JSON object per line for piping into jq
infer conversations show <session-id> --format json | jq .

# Delete a conversation by literal UUID
infer conversations delete 12345678-1234-1234-1234-123456789abc

# Delete by session group key (for example a channel group key)
infer conversations delete channel-telegram-12345
```

#### Cloudflare D1 backend

[Cloudflare D1](https://developers.cloudflare.com/d1/) is an external, SQLite-compatible store the CLI writes to over D1's HTTP query API. It is built for **ephemeral CI runners** (for example a headless [`infer headless`](#headless-agent-stream-output) run on GitHub Actions): unlike `sqlite`, `jsonl`, and `memory` - which live on the runner's disk and are wiped on recycle - D1 persists off-runner and stays readable by the gateway through its native binding. Unlike `postgres` and `redis`, it needs no wire-protocol connection, just HTTPS.

Set `storage.type: d1` and configure the `storage.d1` block:

```yaml
storage:
  enabled: true
  type: d1
  d1:
    account_id: '<cloudflare-account-id>'
    database_id: '<d1-database-id>'
    api_token: '<api-token-with-d1-edit>' # inject via INFER_STORAGE_D1_API_TOKEN
    base_url: 'https://api.cloudflare.com/client/v4' # optional
```

**Environment variables:**

| Variable                       | Description                                                                |
| ------------------------------ | -------------------------------------------------------------------------- |
| `INFER_STORAGE_D1_ACCOUNT_ID`  | Cloudflare account id that owns the D1 database.                           |
| `INFER_STORAGE_D1_DATABASE_ID` | Target D1 database id.                                                     |
| `INFER_STORAGE_D1_API_TOKEN`   | API token with D1 edit permission. Secret - inject, never commit.          |
| `INFER_STORAGE_D1_BASE_URL`    | Optional API base URL. Defaults to `https://api.cloudflare.com/client/v4`. |

**Notes:**

- **No manual migration.** Like `jsonl`, `redis`, and `memory`, D1 creates its schema automatically on first connect - there is no separate migration step to run.
- **Schema parity.** The D1 driver runs the SQLite migrations verbatim over HTTP, so the `conversations` and `session_groups` tables stay byte-for-byte compatible with the SQLite backend - either side can initialise the database.
- **UTC timestamps.** Timestamps are stored as UTC RFC3339 so `ORDER BY updated_at DESC` sorts stably across runners in any timezone and external reads stay unambiguous.
- **Secret handling.** `api_token` follows the existing plaintext-config + env-override convention (like the Postgres password) and is never logged - inject it via `INFER_STORAGE_D1_API_TOKEN`.

### Message Queue

The message queue holds messages waiting for the agent to pick up on its next availability - text typed while a turn is running, background-job completion notes, and work pushed in by other processes. Its backend is configurable, independently of [conversation storage](#conversation-management):

| Backend            | Survives a restart | Shareable across processes | Connection settings |
| ------------------ | ------------------ | -------------------------- | ------------------- |
| `memory` (default) | no                 | no                         | -                   |
| `sqlite`           | yes                | yes                        | `storage.sqlite`    |
| `postgres`         | yes                | yes                        | `storage.postgres`  |
| `redis`            | yes                | yes                        | `storage.redis`     |

```yaml
# .infer/config.yaml
queue:
  type: redis # memory (default), sqlite, postgres or redis
  name: '' # queue scope, empty means this process's session id
  poll_interval: 2s # cross-process wake-up cadence, durable backends only
```

- **queue.type** (`INFER_QUEUE_TYPE`): backend for the queue, default `memory`. It is deliberately separate from `storage.type` - the storage default `jsonl` is not a queue backend, and following `storage.type` would silently make the default queue durable. `jsonl` and `d1` are rejected by config validation. Non-memory backends reuse the matching `storage.<type>` connection settings, so a queue never grows a second host/port/password block.
- **queue.name** (`INFER_QUEUE_NAME`): the queue scope, resolved once at startup. Empty means this process's session id, so two local sessions never take each other's typed messages - but a new session is a new scope, so nothing carries over a restart. Set the same explicit name on every process that should consume the work, and on every external producer.
- **queue.poll_interval** (`INFER_QUEUE_POLL_INTERVAL`): how often a durable backend is polled for entries written by someone else, default `2s`. An idle agent is woken within that interval, so producers never talk to infer directly.

**Semantics:**

- FIFO per scope, oldest message first.
- A drain takes every message out in one atomic step, so two processes draining at the same time never receive the same message.
- Delivery is at-most-once, as with the process-local queue: a drained message lost to a crash before it reaches the conversation is gone. Ack and redelivery are out of scope.
- An unreachable backend fails startup with an error naming the backend - it never silently falls back to `memory`.
- `chat.status_bar.indicators.queue` gates the [status-bar indicator](#status-indicator-row). The memory queue hides it while empty, a durable backend is always visible and names the backend (`redis`, or `redis 3 queued` while work waits), rendered in the error color while the backend is unreachable.

#### Feeding the queue from outside infer

External producers enqueue by writing one JSON record to the configured backend:

| Field        | Type              | Notes                                                                                                  |
| ------------ | ----------------- | ------------------------------------------------------------------------------------------------------ |
| `role`       | string            | SDK role of the message, `"user"` for user work                                                        |
| `content`    | JSON              | the SDK message content - a plain text message is a JSON string                                        |
| `source`     | string            | one of `composer`, `stdin`, `a2a`, `shell`, `subagent`, `job`; use `a2a` for work another agent pushes |
| `request_id` | string            | free-form producer-supplied id for tracing and ordering, empty allowed                                 |
| `queued_at`  | RFC3339 timestamp | when the producer created the entry                                                                    |

**Redis** keeps one list per queue scope at `infer:queue:<name>`, oldest entry at the head:

```bash
redis-cli RPUSH infer:queue:my-shared-queue '{
  "role": "user",
  "content": "run the nightly regression checks",
  "source": "a2a",
  "request_id": "nightly-2026-10-12",
  "queued_at": "2026-10-12T20:00:00Z"
}'
```

`RPUSH` appends to the tail and infer consumes from the head, so producers never prepend. `LRANGE infer:queue:<name> 0 -1` reads the queue without consuming it.

**SQLite and PostgreSQL** share the `message_queue` table (`queue_name`, `role`, `content`, `source`, `request_id`, `queued_at`, plus an `id` sequence key that defines the FIFO order and must not be set by hand). The consumer drains it with a single `DELETE ... RETURNING` statement, which on PostgreSQL locks rows with `FOR UPDATE SKIP LOCKED`:

```sql
INSERT INTO message_queue (queue_name, role, content, source, request_id, queued_at)
VALUES (
  'my-shared-queue',
  'user',
  '"run the nightly regression checks"',
  'a2a',
  'nightly-2026-10-12',
  NOW()
);
```

### Persistent Memory

The **Memory** tool gives the agent durable, **cross-session** memory: facts it learns in one session survive into the next. Each fact is a single Markdown **fact-file** (with YAML frontmatter) stored under a configurable directory - `~/.infer/memory` by default - and catalogued by a `MEMORY.md` index. That index is injected into context at the **start of every session**, so the agent always knows what it has recorded; it then reads or writes individual facts on demand. A default [system reminder](#system-reminders) (`memory-consult`) nudges it to consult and keep memory current. Memory is **enabled by default**.

#### Per-project fact organization

Facts are organized by project to keep memory relevant and scoped:

- **Project facts** live in per-project subdirectories: `<project-slug>/<slug>.md` (e.g. `inference-gateway-cli/build-commands.md`).
- **Global facts** stay at the memory directory root (e.g. `user-preferences.md`).
- **Legacy flat files** (pre-existing fact-files at the root) keep working as global facts - no migration needed.

The project is detected automatically:

1. Git remote origin is resolved to `org/repo` (e.g. `inference-gateway/cli`).
2. If no git remote is found, the current working directory basename is used.
3. If neither is available, the fact is stored as global.

#### Fact frontmatter

Each fact-file includes YAML frontmatter that records its metadata:

```yaml
---
name: build-commands
description: how to build the CLI
metadata:
  type: project
  project: inference-gateway/cli
  session: channel-telegram-12345
---
```

| Field              | Description                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| `name`             | Short slug identifying the fact (e.g. `build-commands`).                 |
| `description`      | One-line summary shown in the `MEMORY.md` index.                         |
| `metadata.type`    | Fact type: `user`, `feedback`, `project`, or `reference`.                |
| `metadata.project` | Human-readable `org/repo` that owns this fact. Omitted for global facts. |
| `metadata.session` | The session ID that last wrote the fact (e.g. `channel-telegram-12345`). |

#### Index filtering

The `MEMORY.md` index injected at session start is **filtered** to show only:

- Entries for the **current project** (facts under the detected project slug).
- **Global entries** (facts at the memory directory root).

A single summary line at the bottom names other projects that have facts but are not shown. The full unfiltered index (all projects) is always available by calling `Memory read` with no name.

> **Not the same as `storage.type: memory`.** This is the agent's knowledge memory - durable facts on disk under `~/.infer/memory`. The `memory` [conversation storage backend](#conversation-management) is unrelated: an in-RAM transcript store that is wiped when the process exits.

#### The Memory tool

`Memory` is a [Workflow tool](#tool-categories) whose `operation` parameter selects one of three actions:

| Operation | Parameters                                                                    | Effect                                                                        |
| --------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `read`    | `name` (optional)                                                             | With no `name`, returns the `MEMORY.md` index; with a `name`, that fact-file. |
| `write`   | `name`, `description`, `type`, `content` (all required), `project` (optional) | Creates or updates a fact-file and its index entry.                           |
| `delete`  | `name` (required)                                                             | Removes a fact-file and its index entry.                                      |

`name` is a short slug (for example `build-commands`) for global facts, or `project/slug` (for example `inference-gateway-cli/build-commands`) for project facts - exactly as shown in the `MEMORY.md` index. `description` is the one-line summary shown in the `MEMORY.md` index, `content` is the Markdown fact body, and `type` is one of `user`, `feedback`, `project`, or `reference`.

The optional `project` argument on `write` controls where the fact is filed:

| `project` value | Behavior                                                                                                   |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| _(omitted)_     | Defaults by type: `user` facts are global; `feedback`/`project`/`reference` go under the detected project. |
| `global`        | Forces the fact to be stored at the memory directory root (a global fact).                                 |
| `org/repo`      | Files the fact under another project's subdirectory (e.g. `inference-gateway/cli`).                        |

#### Configuration (`memory.yaml`)

Runtime knobs live in `memory.yaml` (seeded by `infer init`; the in-code defaults apply when the file is absent):

```yaml
# .infer/memory.yaml (or ~/.infer/memory.yaml)
enabled: true
dir: '' # "" => ~/.infer/memory
max_chars: 2000 # cap on the MEMORY.md index injected into context (truncates at line boundary)
max_entry_chars: 2000 # per-fact write cap (0 = default)
```

| Key               | Default           | Environment variable           | Description                                                                                          |
| ----------------- | ----------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `enabled`         | `true`            | `INFER_MEMORY_ENABLED`         | Master switch - registers the `Memory` tool and the index injection.                                 |
| `dir`             | `~/.infer/memory` | `INFER_MEMORY_DIR`             | Directory holding the fact-files and `MEMORY.md`. `""` = default.                                    |
| `max_chars`       | `2000`            | `INFER_MEMORY_MAX_CHARS`       | Upper bound on the `MEMORY.md` index injected at session start. Truncation respects line boundaries. |
| `max_entry_chars` | `2000`            | `INFER_MEMORY_MAX_ENTRY_CHARS` | Per-fact character cap on `write` content. `0` means use the default.                                |

The memory directory is local by default. To back it with a **git remote** - pull on run start, commit and push on change - configure a [Sync backend](#sync-backend).

#### Sync backend

By default the memory directory lives on a single machine (`backend.type: local`, a pure no-op). Point the backend at a **git remote** to share one memory across machines, CI runners, channels, and scheduled runs: the CLI **pulls on run start** and **commits + pushes on change**.

```yaml
# .infer/memory.yaml (or ~/.infer/memory.yaml)
enabled: true
dir: '' # "" => ~/.infer/memory
max_chars: 4000
backend:
  type: local # local (default) | git
  git:
    repo: 'git@github.com:my-org/agent-memory.git'
    branch: main
    commit_message: 'chore(memory): sync'
    timeout: 60 # seconds per git op
    sync:
      on_start: pull # pull (default) | off
      on_finish: push # push (default) | off
```

`type: local` is the default and a pure no-op - existing users see no change.

| Key                          | Default               | Environment variable                      | Notes                                           |
| ---------------------------- | --------------------- | ----------------------------------------- | ----------------------------------------------- |
| `backend.type`               | `local`               | `INFER_MEMORY_BACKEND_TYPE`               | `local` (no-op) or `git`.                       |
| `backend.git.repo`           | `''`                  | `INFER_MEMORY_BACKEND_GIT_REPO`           | Remote URL. Required when `type: git`.          |
| `backend.git.branch`         | `main`                | `INFER_MEMORY_BACKEND_GIT_BRANCH`         | Branch to track.                                |
| `backend.git.commit_message` | `chore(memory): sync` | `INFER_MEMORY_BACKEND_GIT_COMMIT_MESSAGE` | Deterministic, non-LLM commit message.          |
| `backend.git.timeout`        | `60`                  | `INFER_MEMORY_BACKEND_GIT_TIMEOUT`        | Seconds per git op (prevents credential hangs). |
| `backend.git.sync.on_start`  | `pull`                | `INFER_MEMORY_BACKEND_GIT_SYNC_ON_START`  | `pull` or `off`.                                |
| `backend.git.sync.on_finish` | `push`                | `INFER_MEMORY_BACKEND_GIT_SYNC_ON_FINISH` | `push` or `off`.                                |

**Validation:** when memory is enabled and `type: git`, `repo` is required; `on_start` must be `pull` or `off`, and `on_finish` must be `push` or `off`.

##### How it syncs

- **On run start (SyncIn).** Clones the repo when the memory dir is missing, otherwise fast-forward / rebase pulls. An `ls-remote` probe decides clone vs. init-in-place - an empty remote, or a pre-existing local memory dir, is initialized in place instead of cloned.
- **On change (SyncOut).** Commits and pushes **only when `git status --porcelain` reports changes**, through a bounded **push -> pull-rebase -> retry** loop. A per-host `flock` serializes concurrent runs (channels / scheduler / heartbeat) so they do not clobber each other.
- **Where the push happens.** In **chat**, the `Memory` tool pushes on each write / delete - not a post-session hook, which would commit-storm once per message. In [headless mode](#headless-agent-stream-output), it pulls on start and pushes once at run finish. Either way it works across channel, scheduler, and heartbeat subprocess runs.
- **Best-effort, never fatal.** A failed clone / pull / push is logged and the run continues - sync never aborts the agent run.

##### Authentication

Sync uses the **ambient git credential chain** - ssh-agent, a git credential helper, or `GIT_*` environment variables. The backend injects no ssh key or env override of its own, so pick whichever your environment already uses:

- **SSH (preferred)** - a `git@github.com:...` remote plus a loaded ssh-agent key.
- **`gh auth`** - the GitHub CLI credential helper for `https://` remotes.
- **Token in URL** - works, but the CLI **logs a warning**, because credentials embedded in the remote URL persist in `.git/config`. Prefer SSH.

The per-op `timeout` (default `60` seconds) keeps an interactive credential prompt from hanging a run.

#### Disabling memory

Turn it off in `memory.yaml`:

```yaml
# .infer/memory.yaml (or ~/.infer/memory.yaml)
enabled: false
```

or via the environment, without touching config:

```bash
export INFER_MEMORY_ENABLED=false
```

When disabled, the `Memory` tool is not registered, no `MEMORY.md` index is injected, and the `memory-consult` reminder is pruned automatically.

### MCP Integration

Connect to Model Context Protocol servers for extended capabilities. MCP provides stateless tool execution for external services like databases, file systems, and APIs.

**Setup:**

Seed the userspace baseline, which includes `~/.infer/mcp.yaml`:

```bash
infer init
```

Configure MCP servers in `~/.infer/mcp.yaml` (or add `--project` to the `infer mcp` commands below to write a project-level `.infer/mcp.yaml` instead):

```yaml
enabled: true
connection_timeout: 30
discovery_timeout: 30
liveness_probe_enabled: true
liveness_probe_interval: 10

servers:
  # Auto-start MCP server in container (recommended)
  - name: 'demo-server'
    enabled: true
    run: true
    oci: 'mcp-demo-server:latest'
    description: 'Demo MCP server'

  # Connect to external MCP server - the endpoint is spelled out field by field,
  # there is no `url` key (an entry without them resolves to http://localhost/mcp)
  - name: 'filesystem'
    scheme: 'http'
    host: 'localhost'
    port: 3000
    path: '/sse'
    enabled: true
    description: 'File system operations'
    exclude_tools:
      - 'delete_file'
```

`infer mcp add <name> <url>` splits a URL into those fields for you, so you rarely need to write them by hand.

**CLI Commands:**

```bash
# Add auto-start MCP server
infer mcp add my-server --run --oci=my-mcp:latest

# Add an external MCP server by URL (split into scheme/host/port/path)
infer mcp add filesystem http://localhost:3000/sse

# List MCP servers, or show connection status
infer mcp list
infer mcp status

# Enable or disable a server
infer mcp enable my-server
infer mcp disable my-server

# Start or stop an auto-start (OCI) server
infer mcp start my-server
infer mcp stop my-server

# Update a server definition, or remove it
infer mcp update my-server --oci=my-mcp:2.0.0
infer mcp remove my-server
```

`infer mcp enable-global` / `disable-global` toggle MCP support as a whole rather than a single server.

**Using MCP Tools:**

MCP tools appear as `MCP_<server>_<tool>` in chat. Example:

```bash
infer chat
> "Use the MCP_demo-server_get_time tool to get current time"
```

See [MCP documentation](/mcp/) for detailed integration guide and server development.

### Agent Skills

Reusable, model-readable instruction folders that the agent loads on demand. The CLI uses the same on-disk format as Gemini CLI and OpenAI Codex CLI, so a skill authored for any of those tools drops into `.infer/skills/` unchanged. Skills are discovered from three locations, in precedence order: project `.infer/skills/`, the `.agents/skills/` open standard (a shared cross-tool convention), then user-global `~/.infer/skills/`. Skills are **enabled by default** - discovered skills are injected into the system prompt out of the box. Only the lightweight metadata (name + description) is added; each `SKILL.md` body is read on demand. Turn them off with `agent.skills.enabled: false`, or skip individual skills with `disabled_skills`.

```yaml
# .infer/config.yaml
agent:
  skills:
    enabled: true # default
    max_chars: 4000 # cap on the rendered AVAILABLE SKILLS block (0 disables the cap)
    disabled_skills: [] # optional list of skill names to skip
```

```bash
# Discover, install, and remove skills (also available in chat as /skills ...)
infer skills list
infer skills install acme/internal-comms --user   # or a bare name, or a github tree URL
infer skills uninstall internal-comms
```

Once enabled, invoke a skill explicitly with `/<name>` (for example `/pdf-helper`) or by asking the agent to "use the `<name>` skill"; the CLI deterministically activates it by injecting the skill's metadata and pointing the agent at its `SKILL.md`. Installed skills under `~/.infer/skills` and `./.infer/skills` stay readable by the Read tool through a sandbox carve-out, so they load even when the agent runs outside the project directory (for example in CI).

See the full **[Agent Skills guide](/cli-skills/)** for the on-disk layout, the `SKILL.md` frontmatter contract, install flags, activation triggers, and the sandbox carve-out. To publish a skill in the shared index, see the [Skills Catalog](/skills/).

### `/tools` view

The `/tools` shortcut opens a **read-only, filterable list** of the tools available to the agent in the current [agent mode](#agent-modes). Each row shows the tool name plus a word-wrapped description (up to two lines, with an ellipsis on overflow).

- **Filtering:** type `/` to start filtering; matching terms are underlined in the results.
- **Status line:** shows `N tools` at the bottom.
- **Live refresh:** the list refreshes on every entry, so agent-mode changes and asynchronously registered MCP tools are reflected immediately.
- **Mode-aware:** [Plan mode](#plan-mode) hides mutating tools (Write, Edit, Delete, Bash), showing only read-only tools.
- **MCP tools:** dynamically registered MCP tools appear as `MCP_<server>_<tool>` once their server is connected.

```bash
infer chat
> /tools
```

### `/agents` view

The `/agents` shortcut opens the **Agents view** - the single, filterable list of every agent the chat can delegate to, local and remote alike. There is no separate A2A-only view: each row carries a **type chip** that says where it comes from.

| Chip    | Row                                                                                                                                                  | State column                | Detail line                                               |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------- |
| `local` | A [Markdown subagent preset](#markdown-subagent-presets) (`.infer/agents/*.md`) that the [Agent tool](#local-subagents-agent-tool) spawns in-process | `read-only` or `read-write` | Tool allowlist, model (or `inherit`), and the source file |
| `a2a`   | A remote [A2A agent](#a2a-integration) from `agents.yaml`                                                                                            | Its readiness state         | The agent URL, or the failure/progress detail             |

Rows are sorted by name, and typing `/` filters on the chip as well as the name - `local` narrows the list to presets, `a2a` to remote agents.

The a2a rows stay **live for the session lifetime** when [liveness probes](#a2a-liveness-probes) are enabled:

- An agent still pulling its image shows pull progress (`<done>/<total> layers`).
- An agent that was down at startup turns green automatically when it becomes reachable.
- An agent that goes down mid-session shows the failure detail inline.
- A recovered agent shows a **"Recovered"** status.

The status bar `A2A: X/Y` indicator reflects the same live state and opens this view - `X` counts down on failures and counts back up on recovery.

```bash
infer chat
> /agents  # View local presets and remote A2A agents
```

### `/tasks` view

The `/tasks` shortcut opens the **background-work panel** - a live list of everything running or recently finished outside the current chat turn. Rows are grouped into one table per kind: **A2A tasks**, **background shells**, and **subagents**. Each row shows a status (`Running`, `Completed`, or `Failed`) and an **Elapsed** column that updates live about once per second while any work is still in flight (the ticker stops once everything is terminal).

```bash
infer chat
> /tasks
```

Selecting a row opens a **detail panel** with that task's metadata - `ID`, `Detail` (the command for a shell, or the task description for a subagent), `Status`, `Started`, and `Elapsed`. A2A rows additionally show their task history and the agent's **Final Result**; background-shell and subagent rows render an **Output** section instead.

#### Output detail section

Selecting a **background shell** row shows the shell's captured **stdout/stderr**:

- **While the shell is running**, the output streams **live**, refreshed about once per second along with the Elapsed column.
- **Once the shell finishes**, the panel shows the **full captured output**, bounded by the shell's output ring buffer.

Selecting a **subagent** row shows:

- Its **run stats** - tool calls succeeded and failed, input and output tokens. They count up while a headless subagent runs.
- Its **transcript** - the task, each assistant turn with the tools it called, and every tool result (a long result is cut at 2 KB). It refreshes every second while anything is running. An interactive subagent's pane runs under the subagent's session ID, so its conversation loads the same way.
- Its **final answer** instead, when the conversation cannot be loaded (`storage.enabled: false`).

The [background job list](#background-job-list) under the composer is the live view of what is running. `/tasks` is where finished jobs stay for review.

Rendering is bounded so a chatty shell cannot overflow the panel: the Output section shows **at most the last 10KB** of output. When the captured output is larger, it is prefixed with `(truncated, showing last 10KB)` and only the trailing 10KB is displayed.

> The Output section brings background shells and subagents to parity with the A2A "Final Result" panel. Rows for jobs that expose no output (an A2A task keeps its own Final Result panel) show no Output section.

### A2A Integration

Delegate specialized tasks to Agent-to-Agent compatible agents. The A2A client speaks **A2A v1.0.1**, matching agents built on ADK v0.30.0 or later, while still reading the pre-v1.0.1 task state spellings - see [protocol version and task states](/a2a/#protocol-version-and-task-states).

**Setup:**

```bash
# Initialize agents configuration
infer agents init

# Add remote agent
infer agents add calendar-agent http://calendar.example.com

# Add local agent with Docker
infer agents add my-agent http://localhost:8081 --oci ghcr.io/myorg/agent:latest --run

# Add any catalog agent by name only (URL and image derived from its catalog entry)
infer agents add grafana-agent

# Add a built-in agent by name only (browser-agent ships one tag per browser engine)
infer agents add browser-agent --tag lightpanda

# Pin a built-in agent to a released version
infer agents add browser-agent --tag chromium-0.8.0

# List agents
infer agents list

# View agent details
infer agents show calendar-agent

# Update an agent's image tag
infer agents update browser-agent --tag firefox
```

Bare names resolve any agent published in the [A2A Registry](/registry/) catalog. The five agents with built-in defaults (`browser-agent`, `mock-agent`, `google-calendar-agent`, `documentation-agent`, `n8n-agent`) take precedence and work offline; every other name is looked up in the catalog, with the URL and OCI image derived from its published metadata. A name in neither place needs an explicit URL - see [built-in agents vs other catalog agents](/a2a/#built-in-agents-vs-other-catalog-agents).

**Usage:**

```bash
infer chat
> "Schedule a meeting tomorrow at 2 PM using the calendar agent"
> /agents  # View connected agents
```

See [A2A documentation](/a2a/) for creating custom agents, or use the [ADL CLI](/adl-cli/) to scaffold new A2A agents from YAML definitions.

#### Agent Credentials

An agent that protects its `/a2a` endpoint gets an `auth` block in its `agents.yaml` entry - a static bearer token or an OIDC client-credentials grant, with the secret read from an environment variable named in the block. See [authenticating to A2A agents](/a2a/#authenticating-to-a2a-agents) for the fields.

**Which requests carry them:** every request the CLI makes to that agent. The agent card fetch, task submission, background task polling, task cancellation, and the liveness probe behind `infer agents status` all send the `Authorization: Bearer` header.

**Where they go:** credentials are matched by the scheme, host and port of the agent's configured `url` and are sent only to that origin. Another origin, a redirect target, and another service on the same host do not receive them.

**What the model sees on failure:** a missing environment variable, a failed token request, or a `401`/`403` from the agent is reported to the model as one line, without the response body:

```text
Authentication failed for A2A agent "billing": 401 Unauthorized
```

A background task whose polling is rejected ends as failed. `infer agents show` prints the mode and the variable name, so a missing variable is visible without exposing a secret.

#### A2A Liveness Probes

When A2A agents are configured, the CLI periodically re-probes them for the lifetime of the session instead of checking them only once at startup. This means an agent that was down at startup turns green automatically when it becomes reachable, and an agent that goes down mid-session is reflected in the `A2A: X/Y` indicator and the a2a rows of the [`/agents` view](#agents-view).

**How probes work:**

- **External agents** (URLs in `a2a.agents`) are probed via their agent card (`/.well-known/agent-card.json`).
- **Local Docker agents** are probed via `GET <url>/health`.
- Status updates are emitted only on state changes (no noisy per-probe output).
- Probes shut down cleanly when the session ends.

**Configuration:**

```yaml
# .infer/config.yaml
a2a:
  enabled: true
  agents:
    - http://localhost:8081
  liveness_probe_enabled: true # default: true
  liveness_probe_interval: 30 # seconds, default: 30
```

| Setting                   | Default | Environment variable                | Description                                                       |
| ------------------------- | ------- | ----------------------------------- | ----------------------------------------------------------------- |
| `liveness_probe_enabled`  | `true`  | `INFER_A2A_LIVENESS_PROBE_ENABLED`  | Enable recurring liveness probes. Set `false` for one-shot checks |
| `liveness_probe_interval` | `30`    | `INFER_A2A_LIVENESS_PROBE_INTERVAL` | Interval in seconds between probes                                |

Setting `liveness_probe_enabled: false` restores the old behavior where agents are checked only once at startup.

### Parallel Tool Execution

Execute up to 5 tools concurrently for improved performance.

**Configuration:**

```yaml
agent:
  max_concurrent_tools: 5 # Default: 5
```

**Benefits:**

- Faster multi-file operations
- Concurrent web fetches
- Parallel code searches
- Reduced total execution time

## Workflows

### Bug Investigation and Fix

```bash
infer chat
# Shift+Tab to Plan Mode
> "Analyze bug in issue #123 and create fix plan"

# Shift+Tab to Standard Mode
> "Implement the fix according to the plan"

# Test and commit
> "Run test suite to verify"
> "/git commit"
```

### Feature Development

```bash
infer chat
> "Read CONTRIBUTING.md and understand project structure"

# Shift+Tab to Plan Mode
> "Design implementation for user profile feature with avatar upload"

# Shift+Tab twice to Auto-Accept Mode
> "Implement the user profile feature according to the plan"

# Shift+Tab to Standard Mode
> "Review changes and run all tests"
```

### Code Review and Refactoring

```bash
infer chat
# Plan Mode for analysis
> "Review authentication module for security issues and code quality"

# Standard Mode for implementation
> "Refactor based on recommendations, prioritize security issues"
```

### GitHub Issue Resolution

```bash
infer headless "Fix the bug described in GitHub issue #456"

# Agent autonomously:
# 1. Fetches issue details
# 2. Analyzes relevant code
# 3. Implements fix
# 4. Runs tests
# 5. Creates commit referencing issue
```

## Best Practices

### For Beginners

- Start with Plan Mode for unfamiliar code
- Always work in git repositories
- Review diff visualizations before approving
- Begin with simple tasks

### For Power Users

- Use Auto-Accept for trusted, repetitive tasks
- Create custom shortcuts for frequent commands
- Combine with scripts for automation
- Leverage A2A for specialized workflows

### Performance Tips

- Be specific with file paths and function names
- Use Grep to narrow down relevant files first
- Break large tasks into smaller subtasks
- Provide context with references

### Safety

- Review diffs before approving modifications
- Run tests after significant changes
- Have backups before extensive Auto-Accept usage
- Allow-list only trusted commands
- Add sensitive paths to `filesystem.denied` in [`~/.infer/sandbox.yaml`](#file-sandbox)

## Security

### Command allow-listing

The Bash tool is **default-deny**: a command auto-runs only when it matches the [per-mode allowed-list](#per-mode-allowed-list) for the active [agent mode](#agent-modes). The effective list is `mode.all.allow` (the every-mode baseline) unioned with the active mode's own entries:

```yaml
# ~/.infer/tools.yaml
tools:
  bash:
    mode:
      all:
        allow:
          - ls( .*)?
          - pwd( .*)?
          - tree( .*)?
          - git status( .*)?
          - git diff( .*)?
          - npm (install|test|run).*
      auto:
        allow:
          - .* # unrestricted - Auto-Accept mode only
```

Read-only `gh` operations are in the baseline so the agent can inspect GitHub out of the box; **writes** (`gh issue/pr create|edit|comment`) and **destructive** operations (for example `gh pr merge`, `gh repo delete`) are not - they fall through to approval. See [Default gh allowed-list](#default-gh-allowed-list) for the full list.

Entries match the **whole** command, and a [clean-command guard](#clean-command-guard) rejects command substitution, multi-command chains/pipelines, file-write redirects, dangerous `find` actions, and environment-variable leaks before matching. The only thing that lifts the guard is the `.*` sentinel (Auto-Accept mode).

### File sandbox

Which paths the file tools may read and write is decided by a **userspace policy file**, `~/.infer/sandbox.yaml` - not by `config.yaml`. It holds one section per resource, today `filesystem` with two lists:

```yaml
filesystem:
  allowed: # the sandbox. Outside it the user is asked. First match wins.
    - .
    - /tmp
    - path: vendor/
      access: read # read | write (default write). A write here asks.
  denied: # always wins over allowed, a blocking entry over one that asks
    - path: .infer/
      on_violation: approval # block | approval (default block)
    - .git/
    - '*.env'
```

`infer init` seeds the file with the defaults.

#### Entry forms

Each entry is either a path string or a map:

| List      | Map key        | Values                        | Meaning                                          |
| --------- | -------------- | ----------------------------- | ------------------------------------------------ |
| `allowed` | `access`       | `read`, `write` (default)     | A write into a `read` entry asks the user        |
| `denied`  | `on_violation` | `block` (default), `approval` | `block` fails outright, `approval` asks the user |

Paths are either **anchored** (`/abs`, `~/x`, `.`, `./x` - matched at that location) or **patterns** matched at any depth (`dir/`, `*.glob`, `name`).

#### Defaults

- `allowed`: `.` and `/tmp`.
- `denied`: `.infer/` (with `on_violation: approval`), `.git/`, `*.env`, `.environment`, `auth.yaml`, `*.key`, `*.pem`, `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`.

The config dirs (`.infer/` and `~/.infer/`) therefore **ask before every read and write**, since their files can hold tokens - including [`auth.yaml`](#provider-api-keys). Built-in carve-outs keep the agent's own working surface open without a prompt: [skills](/cli-skills/#skills-sandbox-carve-out), plans, plugins, [memory](#persistent-memory), the [artifacts directory](#artifacts-directory) and runtime output such as the [media root](#media-directories).

#### Decision order

1. **`denied` first.** A blocking entry fails whatever its position; otherwise the first matching approval entry asks the user.
2. **Built-in carve-outs**, which skip the default `.infer/` denial.
3. **The first matching `allowed` entry** - a write into a `read` entry asks.
4. **Otherwise the user is asked.** An empty `allowed` list is no boundary.

#### Loading

- Only `~/.infer/sandbox.yaml` is read. A project `.infer/sandbox.yaml` is **ignored**, so a checked-out repository cannot widen your sandbox, and the agent's file tools can never write the policy file - the same guard covers [`~/.infer/tools.yaml`](#tool-configuration).
- The file loads **over** the defaults: a list it leaves out keeps its default.
- A file that fails to parse or validate **stops `infer` from starting**, rather than falling back to a wider policy.
- `infer config set` does not reach the sandbox - edit the file.

#### Grants

When the user approves a denied path, the grant lasts for the **session**. Answering "always" persists it into `sandbox.yaml`, except for paths matched by a `denied` entry, which stay session-only - denied wins over any allowed entry an "always" could write.

#### Environment and daemon overrides

`INFER_TOOLS_SANDBOX_DIRECTORIES` (and the daemon's per-thread `sandbox_directories` thread option) **adds** directories to `filesystem.allowed` instead of replacing the list.

```bash
export INFER_TOOLS_SANDBOX_DIRECTORIES="/work/project,/tmp/scratch"
```

### Approval Workflow

Tool approval has **two independent layers** - _whether_ an action needs approval, and _how_ that approval is delivered:

- **Whether** - `safety.require_approval` (with per-tool overrides like `tools.bash.require_approval` / `tools.write.require_approval`, and for Bash the per-mode [allowed-list](#command-allow-listing)).
- **How** - `safety.approval_behaviour`, one of:

| `approval_behaviour` | How a needed approval is delivered                                                            |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `prompt` (default)   | Prompt in the chat TUI; under a channel manager, deliver over IPC; otherwise block.           |
| `ipc`                | Deliver over IPC when a broker is attached (e.g. the channel manager); otherwise block.       |
| `judge`              | One [LLM judge](/cli-judge-mode/) call decides. Always reachable - never downgraded to block. |
| `block`              | Always reject an approval-requiring action with a reason - never prompt.                      |

Both layers live in [`~/.infer/tools.yaml`](#tool-configuration), not `config.yaml`:

```yaml
# ~/.infer/tools.yaml
safety:
  require_approval: true
  approval_behaviour: prompt
```

> `judge` is the only behavior that requires a resolvable judge model - config validation fails at startup when neither `judge.model` (in [`judge.yaml`](/cli-judge-mode/#configuring-the-judge-judgeyaml)) nor `agent.model` is set. The [`auto-with-judge` mode](#auto-judge-mode) is validated separately by the headless runner at start (`--mode` / `INFER_AGENT_MODE`).

LLMs request approval before executing Write/Edit/Delete/Bash operations, with a colored, syntax-aware diff preview for file edits.

#### Headless secure-by-default

`infer headless` runs in **standard** mode, so an off-list or mutating action is **not** auto-run. With no approver reachable (CI, heartbeat) it is **blocked** with a reason; under a channel manager (`--require-approval`) it is sent for **IPC** approval (for example a Telegram confirmation). There is no `.*` default - full autonomy is an explicit opt-in (a curated allowed-list, the [append override](#append-only-override-ci), or `mode.auto` / `.*`). To keep a gate without a human, run `--mode auto-with-judge` (or set `approval_behaviour: judge`) and let an [LLM judge](/cli-judge-mode/) answer instead of blocking.

For a CI agent that should edit files and run a curated command set with **no** interactive approver, use the **controlled-autonomy** profile - `block` everything that would need approval, but let the agent write files and run a vetted allowed-list:

```yaml
# ~/.infer/tools.yaml
safety:
  approval_behaviour: block # reject anything that would otherwise prompt
tools:
  write:
    require_approval: false # ...but let the agent write/edit files freely
  bash:
    mode:
      all:
        allow: # curate exactly what may run unattended
          - git status( .*)?
          - git add( .*)?
          - go (build|test)( .*)?
```

Add a couple more commands without touching config via `INFER_TOOLS_BASH_ALLOW_APPEND="git commit,git push"`.

## Troubleshooting

### Connection Issues

```bash
# Check configuration
infer config get

# Verify gateway status
infer status

# Debug logging (logging.debug)
INFER_LOGGING_DEBUG=true infer chat
```

### Permission Issues

```bash
# Check configuration directory
ls -la ~/.infer/

# Recreate config.yaml from defaults
infer config init --overwrite

# Re-initialize the project
infer init
```

### Tool Execution Problems

```bash
# Inspect tool configuration
infer config get tools

# Check whether a bash command is allowed (without running it)
infer tools validate "git status"

# Enable debug logging
export INFER_LOGGING_DEBUG=true
infer headless "your task"
```

### Computer Use Issues

```bash
# Verify display server
echo $DISPLAY  # Linux/X11

# Check permissions (macOS) - required before the accessibility tree returns elements
# System Settings > Privacy & Security > Accessibility

# Test screenshot
infer chat
> "Take a screenshot and describe what you see"
```

If `Computer` with `action: accessibility` returns an empty tree or screenshot fallback guidance on macOS, the Accessibility permission for `infer` is the first thing to check. On Linux and Windows that fallback is expected - the accessibility providers are not implemented there yet.

### Shell Completions Not Working

```bash
# Confirm the completion script generates
infer completion zsh | head

# Zsh: the file must live on a directory in $fpath and be named _infer,
# then start a fresh shell
infer completion zsh > "${fpath[1]}/_infer" && exec zsh

# Bash: source the generated file (or place it under a bash-completion dir)
source <(infer completion bash)
```

If completions still do not appear, the shell rc is usually not sourcing the completion file. Verify `compinit` is called for zsh (or `bash-completion` is installed for bash), confirm the file path is on `$fpath`/a bash-completion directory, then start a fresh shell.

## Command Reference

| Command                               | Description                                                                                                                                                                                                                                                                   |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `infer init`                          | Seed the userspace baseline in `~/.infer/`                                                                                                                                                                                                                                    |
| `infer env`                           | Write a `.env.example` with every provider API key                                                                                                                                                                                                                            |
| `infer status`                        | Check gateway health and resource usage                                                                                                                                                                                                                                       |
| `infer chat`                          | Interactive chat session (TUI)                                                                                                                                                                                                                                                |
| `infer chat --web`                    | Web-based terminal interface                                                                                                                                                                                                                                                  |
| `infer headless <task>`               | Autonomous task execution                                                                                                                                                                                                                                                     |
| `infer skills <subcommand>`           | Manage Agent Skills (`list`, `search`, `install`, `uninstall`)                                                                                                                                                                                                                |
| `infer plugins <subcommand>`          | Manage Claude Code-format plugins (`install`, `list`, `enable`, `disable`, `update`, `remove`)                                                                                                                                                                                |
| `infer daemon`                        | Start the daemon - scheduler, channel listener, and heartbeat ([Channels](/cli-channels/))                                                                                                                                                                                    |
| `infer config <subcommand>`           | Configuration management (`init`, `get`, `set`)                                                                                                                                                                                                                               |
| `infer tools <subcommand>`            | Run agent tools directly (`execute`, `validate`)                                                                                                                                                                                                                              |
| `infer agents <subcommand>`           | A2A agent management                                                                                                                                                                                                                                                          |
| `infer binaries <subcommand>`         | Manage the helper binaries under `~/.infer/bin/` (gateway, ffmpeg, whisper-cli, llama-tts) - `status [name...]` reports each one as `missing`, `stale` or `current` by sha256 (approval-free), `install [name...]` installs or upgrades it (`--version <tag>` pins a release) |
| `infer conversations <subcommand>`    | Conversation history management (`list`, `show`, `delete`)                                                                                                                                                                                                                    |
| `infer conversation-title`            | Generate AI titles for saved conversations, or run it as a daemon                                                                                                                                                                                                             |
| `infer export <session-id>`           | Export a conversation to Markdown under the project's `exports/` directory                                                                                                                                                                                                    |
| `infer stats`                         | Summarize local telemetry - token usage, tool outcomes, and cost                                                                                                                                                                                                              |
| `infer traces`                        | Render a session's trace span tree ([Telemetry](#telemetry))                                                                                                                                                                                                                  |
| `infer insights [since]`              | Analyze past sessions for repeatable workflows and recurring failures                                                                                                                                                                                                         |
| `infer reset` / `infer reset confirm` | Preview, then wipe local runtime state ([Reset Shortcut](#reset-shortcut))                                                                                                                                                                                                    |
| `infer avatars <subcommand>`          | Avatar library management (`list`, `create`, `delete`) for `TextToVideo` renders                                                                                                                                                                                              |
| `infer completion <shell>`            | Generate a shell completion script (bash, zsh, fish, powershell)                                                                                                                                                                                                              |
| `infer version`                       | Show version information (backwards-compatible subcommand)                                                                                                                                                                                                                    |
| `infer --version`                     | Show version information (styled by fang)                                                                                                                                                                                                                                     |
| `infer --help`                        | Display styled help information                                                                                                                                                                                                                                               |

### Global Flags

Available on every command:

| Flag                               | Description                                                                                                                   |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `-v, --verbose`                    | Enable verbose output                                                                                                         |
| `--no-colors`                      | Disable ANSI colors (also auto-disabled when stdout is not a terminal or `NO_COLOR` is set)                                   |
| `--tools-bash-allow-append <cmds>` | Comma/newline-separated commands added to the bash allow-list in every mode; `INFER_TOOLS_BASH_ALLOW_APPEND` takes precedence |
| `--reminders-file <path>`          | Reminders YAML path, overriding project `.infer/` and `~/.infer/` reminders; `INFER_REMINDERS_CONFIG` takes precedence        |

For per-command flags and examples, see the CLI repository's [Commands Reference](https://github.com/inference-gateway/cli/blob/main/docs/commands-reference.md).

## Support and Resources

- **Repository**: [github.com/inference-gateway/cli](https://github.com/inference-gateway/cli)
- **Releases**: [GitHub Releases](https://github.com/inference-gateway/cli/releases)

### Canonical CLI references

This page mirrors the CLI repository's documentation; these pages are the source of truth for each topic:

| Topic                       | Reference                                                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Installation                | [installation.md](https://github.com/inference-gateway/cli/blob/main/docs/installation.md)                       |
| Commands and global flags   | [commands-reference.md](https://github.com/inference-gateway/cli/blob/main/docs/commands-reference.md)           |
| Tools and tool overview     | [tools-reference.md](https://github.com/inference-gateway/cli/blob/main/docs/tools-reference.md)                 |
| Configuration               | [configuration-reference.md](https://github.com/inference-gateway/cli/blob/main/docs/configuration-reference.md) |
| Tool approval               | [tool-approval.md](https://github.com/inference-gateway/cli/blob/main/docs/tool-approval.md)                     |
| Cost tracking               | [cost-tracking.md](https://github.com/inference-gateway/cli/blob/main/docs/cost-tracking.md)                     |
| Computer use                | [computer-use.md](https://github.com/inference-gateway/cli/blob/main/docs/computer-use.md)                       |
| Frame sources and vision    | [vision.md](https://github.com/inference-gateway/cli/blob/main/docs/vision.md)                                   |
| Persistent memory           | [memory.md](https://github.com/inference-gateway/cli/blob/main/docs/memory.md)                                   |
| Reminders and command hooks | [hooks.md](https://github.com/inference-gateway/cli/blob/main/docs/hooks.md)                                     |
| Plugins                     | [plugins.md](https://github.com/inference-gateway/cli/blob/main/docs/plugins.md)                                 |
| Runnable examples           | [examples.md](https://github.com/inference-gateway/cli/blob/main/docs/examples.md)                               |

The CLI is actively developed with regular updates and new features. Check the repository for the latest releases and announcements.