Preferences
Settings file
Ante stores user preferences in ~/.ante/settings.json.
Most of these settings can also be viewed and changed interactively with the /config command in the TUI — a searchable settings dialog with in-place toggles (tips, ambient predictions, short prompt, auto compact, resize reflow, default permission mode, update channel) and shortcuts into the dedicated dialogs (theme, model, provider, status line, MCP servers, offline mode). Changes are persisted to settings.json immediately; settings consumed at startup, such as resize_reflow, are marked "(next session)" in the dialog and take effect on the next session.
An example settings.json:
{
"model": "claude-sonnet-4-6",
"provider": "anthropic",
"theme": "default",
"permission_mode": "auto",
"permissions": {
"allow": ["Bash(npm run *)"],
"deny": ["Bash(rm *)"]
},
"has_completed_onboarding": true,
"ambient_prompt_suggestion": true,
"ambient_thinking_phrase": true,
"tips": true,
"short_prompt": false,
"auto_compact": true,
"channel": "stable",
"resize_reflow": "conservative",
"status_line": ["model-name", "current-dir"],
"status_line_command": {
"command": "~/.config/ante/statusline.sh",
"padding": 1,
"refresh_interval": 5
},
"model_effort": {
"claude-sonnet-4-6": "medium",
"gpt-5.4": "high"
},
"provider_model": {
"anthropic": "claude-sonnet-4-6",
"openai": "gpt-5.6-sol"
},
"mcp_servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}
}
}
| Field | Description |
|---|---|
model | Default model name |
provider | Default API provider |
theme | TUI color theme |
permission_mode | Default permission mode (strict, auto, or yolo). strict and auto are written automatically when you cycle modes with Shift+Tab in the TUI; yolo remains session-only. Unrecognized values are ignored rather than failing the whole file |
permissions | Persistent tool permission rules, grouped by allow, ask, and deny matchers (see Permissions) |
has_completed_onboarding | Whether the onboarding flow has been completed |
ambient_prompt_suggestion | Whether the TUI shows a next-prompt suggestion as ghost text after a turn. On unless set to false |
ambient_thinking_phrase | Whether the TUI predicts a task-specific spinner phrase while you type. On unless set to false |
tips | Whether the TUI shows a tip line under the spinner while the agent works. On unless set to false |
short_prompt | Use the compact prompt set — a condensed system prompt and shorter built-in tool descriptions — for new and resumed sessions. Off unless set to true; the --short-prompt CLI flag enables it for a single run |
auto_compact | Proactively summarize conversation history as it nears the model's context limit. On unless set to false; /compact and overflow recovery still work when disabled. Toggling it in /config applies to the running session |
channel | Release channel ante update tracks (stable or nightly). Defaults to stable; legacy latest values are treated as stable. See Update & Channels. |
resize_reflow | Scrollback strategy on terminal resize: conservative (default) or purge (see below) |
status_line | Items to display in the TUI status line footer (see below) |
status_line_command | Shell command that renders a fully custom status line (see below). Takes precedence over status_line while set |
model_effort | Per-model effort overrides — keys are model names, values are min / low / medium / high / xhigh / max. Written automatically when you move the effort slider in /models |
provider_model | Last model used per provider — a provider switch adopts this before falling back to the provider's default model. Written automatically on every model/provider selection |
mcp_servers | MCP servers to launch on session start (see MCP Servers) |
Status line
The status_line field controls which items appear in the TUI's footer bar. It accepts an array of item identifiers:
| Item | Description |
|---|---|
model-name | Current model name |
effort | Current effort level (omitted when thinking is disabled) |
provider | Current provider |
current-dir | Current working directory |
git-branch | Current Git branch (omitted when unavailable) |
pr-link | GitHub pull request link for the current branch (requires gh) |
context-used | Context-window usage, shown as N% ctx of the window remaining (omitted until known) |
Default: all items, in the order above. Configure via ~/.ante/settings.json or the /statusline command in the TUI.
Command-based status line
For full control, status_line_command runs a shell command of your choice and renders its output as the status line, replacing the item-based one:
{
"status_line_command": {
"command": "~/.config/ante/statusline.sh",
"padding": 1,
"refresh_interval": 5
}
}
A plain string is accepted as shorthand: "status_line_command": "echo hello".
| Field | Description |
|---|---|
command | Script path or inline shell command, run via sh -c (required) |
padding | Extra horizontal padding in columns (default: 0) |
refresh_interval | Also re-run every N seconds (minimum 1). Useful for clocks or external data. Omit to run only on session events |
How it works. Ante pipes a JSON snapshot of the session to your command's stdin and displays whatever it prints to stdout. The command re-runs (debounced at 300ms) after each assistant message and whenever the model, provider, effort, pull request, working directory, or terminal size changes. Runs are capped at 5 seconds, and a newer run cancels the one in flight.
The JSON input is a compatible subset of Claude Code's statusline input, so existing Claude Code statusline scripts work unchanged:
{
"cwd": "/work/repo",
"session_id": "ses_...",
"version": "0.1.0",
"model": { "id": "claude-sonnet-4-6", "display_name": "claude-sonnet-4-6" },
"workspace": { "current_dir": "/work/repo", "project_dir": "/work/repo" },
"thinking": { "enabled": true },
"pr": { "number": 7, "url": "https://github.com/..." },
"provider": "anthropic",
"context_window": {
"context_window_size": 200000,
"total_input_tokens": 36000,
"used_percentage": 18,
"remaining_percentage": 82
}
}
pr is present only when an open pull request is detected for the current branch; context_window is present after the first response when the model's context limit is known, and reports the raw window size alongside used/remaining percentages using Claude Code's field names. provider is an Ante extension. The thinking key keeps Claude Code's schema even though Ante's knob is effort: enabled is true whenever the session's effort is above min. The command also receives COLUMNS and LINES (current terminal size) and ANTE_PROJECT_DIR (nearest ancestor with .git) in its environment.
Output. Each line of stdout becomes a footer row (up to 8). ANSI colors and OSC 8 hyperlinks are rendered; color state carries across lines. Blank lines are dropped, and empty output renders a blank status line.
A minimal example script:
#!/bin/sh
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
dir=$(basename "$(echo "$input" | jq -r '.workspace.current_dir')")
printf '\033[36m[%s]\033[0m %s' "$model" "$dir"
Make it executable (chmod +x) before pointing command at it. If the command fails — not executable, non-zero exit, or timeout — the footer shows a one-line diagnostic such as status line: sh: …: Permission denied based on the script's stderr. Script changes are picked up on the next run, but changes to settings.json itself require a restart.
Resize reflow
When the terminal window is resized, ante rebuilds its display at the new size. The resize_reflow field selects what happens to the scrollback history above the visible screen:
| Value | Behavior |
|---|---|
conservative (default) | Never rewrites scrollback that has already been printed. Safe on every terminal; after aggressive drag-resizes, a few lines near the resize point may keep their old wrapping. |
purge | Clears the terminal's scrollback and replays the recent transcript at the new width — after a resize the session looks as if it had started at the final size. |
{ "resize_reflow": "purge" }
purge is opt-in rather than automatic because it requires a terminal that honors the erase-scrollback escape sequence (CSI 3 J, the terminfo E3 capability) — and there is no way for ante to detect that support: an ignored 3 J fails silently, and enabling purge on such a terminal duplicates scrollback instead. Most terminals honor it, but iTerm2 has an advanced setting — "Prevent CSI 3 J from clearing scrollback history" — that blocks it. To check your terminal, run:
seq 1 200; printf '\033[2J\033[3J\033[H'
then scroll up — if the numbers are gone, your terminal honors 3 J and purge is safe to enable.
In iTerm2, the capability is toggled under Settings → Advanced: search for "3 J" and set "Prevent CSI 3 J from clearing scrollback history" to No to allow it (required for purge), or Yes to block it. The change applies immediately — re-run the check above to confirm.
Trade-offs of purge: the first resize clears everything in that tab's scrollback, including shell output from before ante started, and only the most recent 2,000 transcript lines are replayed across a resize. Inside tmux or zellij ante always uses the purge strategy regardless of this setting, since both reliably support 3 J.
Settings can be overridden per-session via CLI flags.
Environment variables
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY | API key for Anthropic (Claude) |
OPENAI_API_KEY | API key for OpenAI |
OPENAI_COMPATIBLE_API_KEY | API key for OpenAI-compatible providers |
GEMINI_API_KEY | API key for Google Gemini |
VERTEX_GEMINI_API_KEY | API key for Vertex AI Gemini |
XAI_API_KEY | API key for Grok (xAI) |
OPENROUTER_API_KEY | API key for Open Router |
ZAI_API_KEY | API key for Zai |
DEEPSEEK_API_KEY | API key for DeepSeek |
ALI_CODING_PLAN_API_KEY | API key for Ali Coding Plan |
ANTIX_API_KEY | API key for Antix |
MODEL_BASE_URL | Global fallback base URL (overridden by per-provider vars below) |
ANTHROPIC_BASE_URL | Override the Anthropic base URL |
OPENAI_BASE_URL | Override the OpenAI base URL |
OPENAI_COMPATIBLE_BASE_URL | Override the base URL for the OpenAI Compatible provider |
OPENROUTER_BASE_URL | Override the Open Router base URL |
DEEPSEEK_BASE_URL | Override the DeepSeek base URL |
ANTIX_BASE_URL | Override the Antix base URL |
MODEL_TEMPERATURE | Override model temperature (float) |
MODEL_TOP_P | Override model top_p sampling parameter (float) |
MODEL_MAX_TOKENS | Override max output tokens (integer) |
MODEL_CONTEXT_LIMIT | Override max context window size (integer) |
ANTE_LOCAL_PROVIDER_PORT | Override the local provider port (default: 8080) |
ANTE_HOME | Override the home config directory (default: ~/.ante) |
ANTE_INSTALL_DIR | Installer-only override for the binary install directory (default: ~/.ante/bin) |
ANTE_OPENAI_TRANSPORT | OpenAI Responses transport: http_sse (default) or websocket_auto (see OpenAI transports) |
Directory structure
User-level (~/.ante/)
~/.ante/
├── settings.json # User preferences
├── catalog.json # Custom provider/model catalog
├── AGENTS.md # Global instructions
├── sessions/ # Persisted sessions (for /resume)
├── skills/ # User-level skills
└── agents/ # User-level sub-agents
When ~/.ante/AGENTS.md doesn't exist, Ante falls back to ~/.claude/CLAUDE.md for global instructions, so Claude Code setups work without migration. Only one file is read — an existing AGENTS.md (even an empty one) always wins.
Project-level
AGENTS.md # Project instructions
CLAUDE.md # Project instructions (fallback when no AGENTS.md)
.ante/
├── skills/ # Project-specific skills
└── agents/ # Project-specific sub-agents
.agents/
├── skills/ # Project-specific skills
└── agents/ # Project-specific sub-agents
.claude/
├── skills/ # Project-specific skills (Claude Code compatibility)
└── agents/ # Project-specific sub-agents (Claude Code compatibility)
Project instructions are found by walking up from the working directory: in each ancestor directory Ante checks AGENTS.md first, then CLAUDE.md, and the first directory containing either wins. A directory with both reads only AGENTS.md — CLAUDE.md is a fallback, never a second source.
Project memory (~/.ante/projects/)
Project-scoped state — memory, persisted sessions, event logs — lives under ~/.ante/projects/<project-id>/, where <project-id> is a sanitized form of the project's absolute path.
~/.ante/projects/
└── <project-id>/
└── memory/
└── MEMORY.md # Auto-memory for this project
Temporary files
Per-project temp files live under ~/.ante/cache/<project-id>/.
Precedence
Configuration is resolved in this order (later overrides earlier):
- Built-in defaults
~/.ante/settings.json- CLI flags (
--model,--provider, etc.)