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 provider/model catalog
`~/.ante/auth/`	OAuth credentials and API keys pasted in-app (owner-only; env vars take precedence)
`~/.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/cache/`	Oversized WebFetch response spill files; entries older than 48 hours are removed at startup
`~/.ante/run/jobs/<proc-id>/`	Background Bash job handles: `status.json`, `stdout.txt`, and `stderr.txt`
`~/.ante/run/serve.sock`	Default Unix socket for `ante serve --sock`; a `serve.sock.lock` sibling holds the host's exclusive lock
`~/.ante/tmp/`	Disposable staging files; entries older than 48 hours are removed at startup
`~/.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`	Random installation label for telemetry, written only when telemetry is configured (delete to reset the identity)
`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.

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",
  "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": "medium",
    "gpt-5.4": "high"
  },
  "provider_model": {
    "anthropic": "claude-sonnet-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.

`catalog.json`

Adds or overrides providers and models on top of the built-in catalog. Both 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, a new key adds a provider, and a models entry patches that model's fields wherever it is defined.

{
  "providers": {
    "my-provider": {
      "display_name": "My Provider",
      "base_url": "https://api.example.com/v1",
      "wire_style": "OpenAiCompatible",
      "auth": { "bearer": { "env_key": "MY_PROVIDER_API_KEY" } }
    }
  },
  "models": {
    "claude-sonnet-5": { "effort": "high", "max_tokens": 64000 }
  }
}

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

See the Catalog Reference for the full schema, authentication forms, and resolution rules, and Providers 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 first user message of a session.

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 provider/model catalog
├── auth/               # OAuth credentials and pasted API keys
├── 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
├── cache/              # WebFetch spills (48-hour scratch)
├── run/
│   ├── jobs/
│   │   └── <proc-id>/  # Background Bash status and output
│   ├── serve.sock      # `ante serve --sock` listener
│   └── serve.sock.lock # Ownership lock for the socket above
├── tmp/                # Disposable staging (48-hour scratch)
├── 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
Providers — choosing a provider and customization recipes
Skills — skill directory layout
Sub-agents — sub-agent directory layout
Memory — auto-memory format

Locations​

settings.json​

catalog.json​

AGENTS.md​

Layout​

User-level (~/.ante/)​

Project-local​

Related​