# zidane/output/terminal

> A terminal renderer that streams an agent run to stdout, with depth-aware output for sub-agents.

Import: `import { … } from 'zidane/output/terminal'`. Source: [src/output/terminal.ts](https://github.com/Tahul/zidane/blob/main/src/output/terminal.ts).

Use `setupTerminalOutput()` when you run an agent from a script or CLI: text and thinking deltas, tool calls and sub-agent activity print as they happen. It attaches to the agent's [hooks](https://zidane.si/docs/hooks.md) and returns a function that detaches it again. `printTerminalHeader()` prints the title, model, prompt and tool names on its own.

```ts
import { createAgent } from 'zidane'
import { setupTerminalOutput } from 'zidane/output/terminal'
import { basic } from 'zidane/presets'
import { anthropic } from 'zidane/providers/anthropic'

const agent = createAgent({ ...basic, provider: anthropic() })
const prompt = 'Summarize README.md in three bullets.'
const detach = await setupTerminalOutput(agent, 'claude-fable-5-1', prompt, basic, { title: 'Docs run' })

await agent.run({ prompt })
detach()
```

## Functions

### `printTerminalHeader`

Function.

Prints the run header: title, model, prompt, preset name and tool names.

```ts
function printTerminalHeader(
  agent: Agent,
  model: string,
  prompt: string,
  preset: Preset,
  title?: string,
): void
```

**Parameters**

- `agent` (`Agent`): Agent in use. Its auth mode is shown beside the model.
- `model` (`string`): Model id to show.
- `prompt` (`string`): Prompt to show.
- `preset` (`Preset`): Preset whose name and tools are listed.
- `title?` (`string`, default `'⚽ Zizou'`): Title line of the header.

Source: [src/output/terminal.ts:79](https://github.com/Tahul/zidane/blob/main/src/output/terminal.ts#L79)

### `setupTerminalOutput`

Function.

Wire the depth-aware terminal renderer onto an agent's hook bus.

Returns a disposer that unregisters every hook this function installed —
hosts reusing one agent across phases can detach the renderer without
tearing the agent down. Callers that never detach can ignore the return value.

```ts
function setupTerminalOutput(
  agent: Agent,
  model: string,
  prompt: string,
  preset: Preset,
  options?: TerminalOutputOptions,
): Promise<() => void>
```

**Parameters**

- `agent` (`Agent`): Agent whose hooks the renderer attaches to.
- `model` (`string`): Model id shown in the header.
- `prompt` (`string`): Prompt shown in the header.
- `preset` (`Preset`): Preset whose name and tools are shown in the header.
- `options?` (`TerminalOutputOptions`, default `{}`): Header and filtering options. See [`TerminalOutputOptions`](https://zidane.si/docs/reference/output-terminal.md#TerminalOutputOptions).

**Returns** `Promise<() => void>`

**Example**

```ts
import { createAgent } from 'zidane'
import { basic } from 'zidane/presets'
import { anthropic } from 'zidane/providers'
import { setupTerminalOutput } from 'zidane/output/terminal'

const agent = createAgent({ ...basic, provider: anthropic({ apiKey: 'sk-ant-...' }) })
const prompt = 'build a REST API'
const detach = await setupTerminalOutput(agent, 'claude-opus-4-7', prompt, basic)
await agent.run({ prompt })
detach()
```

Source: [src/output/terminal.ts:118](https://github.com/Tahul/zidane/blob/main/src/output/terminal.ts#L118)

## Interfaces

### `TerminalOutputOptions`

Interface.

Options for [`setupTerminalOutput`](https://zidane.si/docs/reference/output-terminal.md#setupTerminalOutput).

```ts
interface TerminalOutputOptions
```

**Properties**

- `printHeader?` (`boolean`, default `true`): Print the header before streaming starts. Set `false` to skip it.
- `shouldPrint?` (`() => boolean`): Checked before every write. Return `false` to silence all output.
- `shouldPrintSummary?` (`(stats: AgentStats) => boolean`): Checked before the run summary is printed. Return `false` to hide it.
- `shouldPrintToolCall?` (`(ctx: ToolHookContext & { coercions?: readonly string[]; priorContent?: string; runToolCounts: Readonly<Record<string, number>>; unknown?: boolean }) => boolean`): Checked before each tool call line is printed. Return `false` to hide that call.
- `title?` (`string`, default `'⚽ Zizou'`): Title line of the header.

Source: [src/output/terminal.ts:49](https://github.com/Tahul/zidane/blob/main/src/output/terminal.ts#L49)