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
External CLI agent to run in the AI terminal.
No Additional PropertiesCLI 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 []'.
A command-line argument rendered for an agent process.
A static string or Minijinja template that produces one argument.
A Minijinja expression that produces an array of strings.
No Additional PropertiesAdditional CLI arguments appended after args. Supports the same
Minijinja template variables, filters, and expressions documented on
args.
A command-line argument rendered for an agent process.
Same definition as agent_args_itemsPrompt 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.
Whether this agent uses the Terminai MCP server. Defaults to false for
custom agents and inherits from the selected preset when unset.
Whether this agent uses the Terminai CLI tools. Defaults to true for
custom agents and inherits from the selected preset when unset.
User-defined CLI agent presets. Built-in presets include codex and claude.
Each additional property must conform to the following schema
Type: objectAgent preset configuration.
No Additional PropertiesCLI 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 []'.
A command-line argument rendered for an agent process.
Same definition as agent_args_itemsEach additional property must conform to the following schema
Type: stringAdditional CLI arguments appended after args. Supports the same
Minijinja template variables, filters, and expressions documented on
args.
A command-line argument rendered for an agent process.
Same definition as agent_args_itemsPrompt template inherited by agents using this preset. Uses the same XDG
lookup and default.jinja shadowing behavior as the agent setting.
Interface configuration
No Additional PropertiesPosition of the AI chat overlay (default: bottom)
Key bindings
The syntax for key combinations is defined by crokey.
No Additional PropertiesA single key combination such as Ctrl-Space
Privacy filtering applied to terminal text returned through MCP.
No Additional PropertiesHow matching terminal data is anonymized before being sent to an agent.
Default wrapped shell.
No Additional Properties