TerminaiConfig

Type: object

Top-level Terminai configuration loaded from
$XDG_CONFIG_HOME/terminai/terminai.yaml, falling back to
~/.config/terminai/terminai.yaml when XDG_CONFIG_HOME is unset. On
Windows it is %APPDATA%\\terminai\\terminai.yaml.

Default configuration can be installed with terminai init-config

No Additional Properties

Type: object Default: {"args": [], "command": null, "extra-args": [], "kind": "codex", "preset": "codex", "prompt-template": null, "uses-mcp": null, "uses-tool-cli": null}

External CLI agent to run in the AI terminal.

No Additional Properties

Type: array Default: []

CLI arguments passed to the agent.

Each argument can be a string rendered as a Minijinja template or an
object containing expr, whose Minijinja expression must return an array
of strings. Available variables:

General:
- {{ cwd }}: the working directory where the agent starts.
- {{ context_prompt }}: the rendered Terminai context prompt for the
resolved agent config.
- {{ uses_mcp }}: whether the resolved agent config enables
the Terminai MCP server.
- {{ uses_tool_cli }}: whether the resolved agent config enables
Terminai CLI tool instructions.

MCP:
- {{ mcp_url }}: the Terminai MCP server URL.
- {{ mcp_command }}: the command to launch MCP.
- {{ mcp_port }}: the local port used by the Terminai MCP server.

The MCP bearer token is available to the agent as the
TERMINAI_MCP_AUTH_TOKEN environment variable.

Tool CLI:
- {{ tool_command }}: the command to interact with Terminai-provided
tools.

Available filters:
- {{ value|toml }}: render value as a TOML string.
- {{ value|json }}: render value as a JSON string.

For zero or multiple arguments, use an expression object such as
expr: '["--mcp", mcp_url] if uses_mcp else []'.

No Additional Items

Each item of this array must be:

Type: object

A command-line argument rendered for an agent process.

Type: string

A static string or Minijinja template that produces one argument.

Type: object

A Minijinja expression that produces an array of strings.

No Additional Properties

Type: string

Type: string or null Default: null

Type: array Default: []

Additional CLI arguments appended after args. Supports the same
Minijinja template variables, filters, and expressions documented on
args.

No Additional Items

Each item of this array must be:

Type: object

A command-line argument rendered for an agent process.

Same definition as agent_args_items

Default: null

Type: enum (of string)

Must be one of:

  • "claude"
  • "codex"
  • "custom"
Type: null

Type: string or null Default: null

Type: string or null Default: null

Prompt template to render for this agent. Defaults to default.jinja,
which is loaded from the Terminai XDG config directory when present and
otherwise falls back to the bundled template. Other names are loaded from
the same directory. builtin/default.jinja always names the bundled
template and can be extended by a user-provided default.

Type: boolean or null Default: null

Whether this agent uses the Terminai MCP server. Defaults to false for
custom agents and inherits from the selected preset when unset.

Type: boolean or null Default: null

Whether this agent uses the Terminai CLI tools. Defaults to true for
custom agents and inherits from the selected preset when unset.

Type: object Default: {}

User-defined CLI agent presets. Built-in presets include codex and claude.

Each additional property must conform to the following schema

Type: object

Agent preset configuration.

No Additional Properties

Type: array Default: []

CLI arguments passed to the agent.

Each argument can be a string rendered as a Minijinja template or an
object containing expr, whose Minijinja expression must return an array
of strings. Available variables:

General:
- {{ cwd }}: the working directory where the agent starts.
- {{ context_prompt }}: the rendered Terminai context prompt for the
resolved agent config.
- {{ uses_mcp }}: whether the resolved agent config enables
the Terminai MCP server.
- {{ uses_tool_cli }}: whether the resolved agent config enables
Terminai CLI tool instructions.

MCP:
- {{ mcp_url }}: the Terminai MCP server URL.
- {{ mcp_command }}: the command to launch MCP.
- {{ mcp_port }}: the local port used by the Terminai MCP server.

The MCP bearer token is available to the agent as the
TERMINAI_MCP_AUTH_TOKEN environment variable.

Tool CLI:
- {{ tool_command }}: the command to interact with Terminai-provided
tools.

Available filters:
- {{ value|toml }}: render value as a TOML string.
- {{ value|json }}: render value as a JSON string.

For zero or multiple arguments, use an expression object such as
expr: '["--mcp", mcp_url] if uses_mcp else []'.

No Additional Items

Each item of this array must be:

Type: object

A command-line argument rendered for an agent process.

Same definition as agent_args_items

Type: string or null Default: null

Type: object Default: {}

Each additional property must conform to the following schema

Type: string

Type: string or null Default: null

Type: array Default: []

Additional CLI arguments appended after args. Supports the same
Minijinja template variables, filters, and expressions documented on
args.

No Additional Items

Each item of this array must be:

Type: object

A command-line argument rendered for an agent process.

Same definition as agent_args_items

Type: string or null Default: null

Prompt template inherited by agents using this preset. Uses the same XDG
lookup and default.jinja shadowing behavior as the agent setting.

Type: boolean or null Default: null

Type: boolean or null Default: null

Type: object Default: {"chat-position": "bottom", "key_bindings": {"activate-overlay": "Ctrl-Space", "approve": "y", "deactivate-overlay": "Ctrl-Space", "deny": "n"}}

Interface configuration

No Additional Properties

Type: enum (of string) Default: "bottom"

Position of the AI chat overlay (default: bottom)

Must be one of:

  • "bottom"
  • "top"

Type: object Default: {"activate-overlay": "Ctrl-Space", "approve": "y", "deactivate-overlay": "Ctrl-Space", "deny": "n"}

Key bindings

The syntax for key combinations is defined by crokey.

No Additional Properties

Type: object

Type: string

A single key combination such as Ctrl-Space

Type: array of string
No Additional Items

Each item of this array must be:

Type: object Default: {"patterns": ["default"], "strategy": "replace"}

Privacy filtering applied to terminal text returned through MCP.

No Additional Properties

Type: array of string Default: ["default"]
No Additional Items

Each item of this array must be:

Type: string

Type: enum (of string) Default: "replace"

How matching terminal data is anonymized before being sent to an agent.

Must be one of:

  • "replace"
  • "mask"
  • "hash"
  • "encrypt"
  • "redact"

Type: object Default: {"args": [], "command": null}

Default wrapped shell.

No Additional Properties

Type: array of string Default: []
No Additional Items

Each item of this array must be:

Type: string

Type: string or null Default: null