Storage Reference

Ante persists configuration and state on the local filesystem. This page is a reference for every location Ante reads or writes.

Locations

Location	Purpose
`~/.ante/settings.json`	User preferences (model, provider, theme, MCP servers)
`~/.ante/<name>.settings.json`	Whole-file settings profile selected by `--profile <name>` or `ANTE_PROFILE`
`~/.ante/catalog.json`	Custom providers, OAuth profiles, and credential helpers
`~/.ante/auth/credentials/`	Stored credentials, owner-only: `secret/` (API keys), `oauth/` (sign-ins), `helper/` (helper output). Manage with `ante auth`
`~/.ante/AGENTS.md`	Global instructions injected into every project session
`~/.ante/skills/`	User-level skills
`~/.ante/agents/`	User-level sub-agents
`~/.ante/.system/`	Bundled skills and sub-agents managed by the installed Ante version
`~/.ante/sessions/<session-id>/`	Persisted sessions (for `/resume` and `--resume`)
`~/.ante/projects/<project-id>/memory/`	Per-project auto-memory
`~/.ante/run/jobs/<proc-id>/`	Background Bash job handles: `status.json`, `stdout.txt`, and `stderr.txt`
`~/.ante/run/offline/`	Managed router process record (`router.json`) and model presets (`presets.ini`), retained so a kept router can be reused by a later launch
`~/.ante/run/serve.sock`	Default Unix socket for `ante serve --sock`; a `serve.sock.lock` sibling holds the host's exclusive lock
OS cache dir (`~/Library/Caches/ante`, `$XDG_CACHE_HOME/ante`)	Oversized WebFetch response spill files
OS temp dir	Disposable staging files and intermediate downloads
`~/.ante/logs/<YYYY-MM-DD>/`	Application and crash logs, partitioned by UTC date (`ante.<pid>.log` and `ante.<pid>.crash.log`)
`~/.ante/logs/llama-server.log`	Local inference server log
`~/.ante/models/`	Default directory for local GGUF models
`~/.ante/llama.cpp/`	Managed llama.cpp installation
`~/.ante/offline-config.json`	Offline-mode engine, model, and server preferences
`~/.ante/verified_models.json`	Optional user additions and overrides for the verified local-model list
`~/.ante/channels.json`	Slack and Discord gateway configuration
`~/.ante/versions.json`	Cached update check and release-note state
`~/.ante/user_input_history.jsonl`	TUI prompt history
`~/.ante/tip_history.json`	Show history for spinner tips (delete to reset the rotation)
`~/.ante/installation-id`	Installation label for telemetry, written when telemetry is configured (edit to set a common name like `anon`, or delete to reset)
`AGENTS.md`	Project instructions injected alongside global instructions
`.ante/settings.json`	Project settings layered over the user's, resolved from the nearest ancestor of the session directory
`.ante/`	Project-local configuration (skills, sub-agents)
`.agents/`, `.claude/`	Additional project-local skill/sub-agent directories

<project-id> is a sanitized form of the project's absolute path. The ANTE_HOME environment variable overrides ~/.ante.

WebFetch spill files use the OS cache directory: ~/Library/Caches/ante on macOS, $XDG_CACHE_HOME/ante on Linux (falling back to ~/.cache/ante when unset or not absolute), and %LOCALAPPDATA%/ante on Windows. Only when the OS cache directory cannot be resolved does Ante fall back to $ANTE_HOME/cache; changing ANTE_HOME normally does not move the cache. Cache entries older than 48 hours are collected on a later startup. Disposable staging files and intermediate downloads use the OS temp directory and are outside this 48-hour cache sweep.

Background job directories are live process state rather than scratch data. Ante never removes a live job because of age; after a job settles, its directory is retained for 24 hours and then collected on a later startup.

`settings.json`

Stores user preferences. All fields are optional.

{
  "model": "claude-sonnet-5-5",
  "provider": "anthropic",
  "theme": "default",
  "permission_mode": "strict",
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "deny": ["Bash(rm *)"]
  },
  "channel": "stable",
  "has_completed_onboarding": true,
  "status_line": ["model-name", "current-dir"],
  "model_effort": {
    "claude-sonnet-5-5": "medium",
    "gpt-6.1-sol": "high"
  },
  "provider_model": {
    "anthropic": "claude-sonnet-5-5"
  },
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

Named profile files have the same schema but replace settings.json wholesale for that run; they do not inherit missing values from it. See Preferences for profile behavior and the full field reference.

A project's .ante/settings.json uses the same schema but layers over the user file: only the keys it sets are overridden. As repository content it may pin or narrow only, so permission_mode, permissions.allow, mcp_servers, system_prompt, model, and provider are dropped with a notice. See Project settings.

Saved conversations

Each ~/.ante/sessions/<session-id>/ directory holds the resumable dialog, event log, and metadata. Metadata includes the session's creation time and last activity; the resume picker orders by last activity, falling back to creation time for older snapshots. Forks also record forked_from, the source session ID. The size shown in /resume is the size of events.jsonl (zero if missing), not the entire session directory or its context-token count.

Before a rewind replaces the current history, Ante keeps the abandoned dialog and event log under abandoned/<rwd-id>/dialog.json and events.jsonl inside that session directory. These are retained copies, not separate sessions in the resume picker. See rewind and fork for the conversation-only restore boundaries.

`catalog.json`

Adds or patches providers on top of the built-in catalog, and defines OAuth profiles and credential helpers. All top-level keys are optional. The my-provider key is what you pass to --provider. An entry whose key matches a built-in (e.g. openai) patches that provider field by field, and a new key adds a provider.

{
  "providers": {
    "my-provider": {
      "display_name": "My Provider",
      "base_url": "https://api.example.com/v1",
      "wire_style": "OpenAiCompatible",
      "credential": "env:MY_PROVIDER_API_KEY"
    }
  }
}

Malformed entries are skipped individually and reported at startup. Valid entries in the same file still load.

See the Catalog Reference for the full schema, credentials, and resolution rules, and custom catalog recipes for customization recipes.

`AGENTS.md`

Stores persistent instructions for the agent. ~/.ante/AGENTS.md applies globally, and a project AGENTS.md applies to that repository. When both exist, Ante includes both in the session preamble, ahead of the conversation.

See AGENTS.md for usage guidance and precedence details.

Layout

User-level (`~/.ante/`)

~/.ante/
├── settings.json       # User preferences
├── <name>.settings.json # Named settings profiles
├── catalog.json        # Custom providers, OAuth profiles, helpers
├── auth/credentials/   # Stored keys, sign-ins, helper output (owner-only)
├── AGENTS.md           # Global instructions
├── installation-id     # Random telemetry installation label
├── user_input_history.jsonl # TUI prompt history
├── tip_history.json    # Spinner-tip history
├── versions.json       # Update cache and release-note state
├── channels.json       # Gateway configuration
├── offline-config.json # Offline-mode preferences
├── verified_models.json # Optional local-model catalog overrides
├── .system/            # Bundled skills and sub-agents (Ante-managed)
├── skills/             # User-level skills
├── agents/             # User-level sub-agents
├── sessions/           # Persisted sessions (for /resume)
├── projects/           # Per-project state (memory, etc.)
│   └── <project-id>/
│       └── memory/
│           └── MEMORY.md
├── run/
│   ├── jobs/
│   │   └── <proc-id>/  # Background Bash status and output
│   ├── offline/
│   │   ├── router.json # Router PID, port, and identity
│   │   └── presets.ini # Model load presets
│   ├── serve.sock      # `ante serve --sock` listener
│   └── serve.sock.lock # Ownership lock for the socket above
├── logs/
│   ├── <YYYY-MM-DD>/   # ante.<pid>.log and crash logs
│   └── llama-server.log
├── models/             # Local GGUF models
└── llama.cpp/          # Managed local inference engine

Project-local

AGENTS.md               # Project instructions

.ante/
├── settings.json       # Project settings layered over the user's
├── 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)

Preferences — full settings.json reference and environment variables
Catalog Reference — catalog.json schema, built-in providers, and model IDs
Connect a provider — sign in with OAuth or an API key
Skills — skill directory layout
Sub-agents — sub-agent directory layout
Memory — auto-memory format

Locations​

settings.json​

Saved conversations​

catalog.json​

AGENTS.md​

Layout​

User-level (~/.ante/)​

Project-local​

Related​