Configuration files

Where Miton stores settings and project data — user profile, project `.miton/` folder, override order, and wipe options.

Product stage: Development build
Last reviewed: 2026-08-27
Successful result: The change is visible in the active project.

Who this is for: power users and developers who need to know what lives on disk, what is safe to commit, and how to reset a bad state.

Most settings are easier to change in Settings (Cmd+, / Ctrl+,). This page describes the files behind those panels.

User profile (application data)

Created on first launch. Typical locations:

Platform	Path
macOS	`~/Library/Application Support/Miton/`
Windows	`%APPDATA%\Miton\`
Linux	`~/.config/Miton/`

Common contents:

Path	Holds
`settings.json`	Global preferences (theme, defaults, telemetry toggles)
`recent.json`	Recent projects list
`logs/`	Rotated application logs
`queue.ndjson`	Pending telemetry events (only if you opted in)
`crashes/`	Local crash reports (only if enabled)

Wipe everything: Settings → Diagnostics → Wipe user data (irreversible).

Some UI state (for example parts of the session list) also uses browser localStorage in the desktop shell.

Shared CLI/desktop files (`~/.miton/` by default)

The CLI and desktop use a second, home-relative directory (separate from the platform app-data path above) for their small interoperability files. The CLI uses ~/.miton/ by default; set MITON_CONFIG_DIR to give CLI-owned configuration and credential fallbacks another root. That override also means the CLI will not see the desktop snapshot in the default location.

Path	Holds
`config.json`	Chosen provider and default model, shared between desktop and CLI
`desktop-state.json`	Preferences, project list, and active project — read by the CLI on launch
`plugins/`	Installed plugin bundles
`athenaeum/<type>/<slug>/`	Marketplace installs — skills, themes, workflows, and templates
`skills/_drafts/`	Skills Miton proposes from a session, pending your approval
`logs/react-crash.log`	Crash log for the desktop UI

A second, separate app-data directory (the platform path from the table above, with a miton/ subfolder) holds two more shared stores that are easy to mistake for project files because a project window is what triggers them:

Path	Holds
`catalogue/catalogue.db`	One shared database: the model/provider catalogue, Writer citations, and saved Automation workflow versions (including anything built from a preset). Not project-scoped — citations and workflow versions from every project you’ve opened live in the same file.
`argus/tantivy`	The code-search index. One index at a time, rebuilt when you open a project — not a per-project folder, and not inside any project’s own `.miton/`.

The CLI’s own configuration and usage ledgers live under ~/.miton/ by default and follow MITON_CONFIG_DIR. Its workflow runs, cron schedules, sessions, model caches, egress ledger, activity and checkpoints follow MITON_STATE_DIR. Both defaults are ~/.miton/, so existing installations do not change location.

Project folder (`.miton/`)

Each project has a .miton/ directory in the project root, created on first open.

Path	Holds	Usually in git?
`plan.md`	Written project plan	Yes
`blueprint.md`	Written project blueprint (Blueprint tab: title, status, components)	Yes
`milestones.json`	Goals — the milestone list behind the Goals view	Yes
`milestones.json.bak`	Previous `milestones.json`, kept as a recovery copy	No
`drift.json`	Drift findings (blueprint-stale, dependency, security, and other checks)	Varies
`memory.sqlite`	Workspace memory database	No (local)
`canvas/*.sqlite`	Canvas data blocks, one file per data source	Varies
`blueprint/blueprint.sqlite`	Internal code-structure index (AST graph) that backs code search and context — regenerates automatically, not something you edit	No
`worktrees/`	Sub-agent git worktrees	No
`wiki/`	Project wiki pages	Yes
`shared-preferences.json`	A snapshot of your preferences, written only when you import a project someone shared with you	Varies

There’s no project-level settings.json override file and no per-project starters/, presets/, citations.db, data/*.db, argus/, or logs/ — see “Override order” and the shared app-level stores above for where those settings and databases actually live.

The project’s .gitignore template excludes heavy or machine-local paths (blueprint/, worktrees/, memory.sqlite, etc.). Commit the plan, blueprint, and goals you want to share with teammates.

Custom, project-specific commands are not a YAML file convention — extend chat with a skill instead, installed from the marketplace or proposed by Miton from a session.

Also at the project root (outside .miton/):

MITON.md — project overview the agent reads every session
.miton/rules/ — rule files injected into context (path may be .miton/rules/ per project layout)

Override order

There’s no project-level settings file to layer on top of your preferences. For a given setting, Miton resolves:

user settings.json → built-in default

Environment variables override file settings where supported — see environment variables.

Wipe and recovery

Target	Effect
User data wipe	Clears global settings, caches, custom skills, logs
Project data wipe	Clears project memory, code search index, worktrees, local databases

All wipes require confirmation in Settings → Diagnostics → Wipe.

Secrets (API keys) are not in JSON files — they live in the OS keychain.

Settings across several machines

Settings in this build are per-machine. Signing in to your Miton account on a second computer restores your account, not your preferences — themes, model groups, routing weights and the rest start at their defaults there.

Account-based preference sync is designed and planned, but is not in this build. When it arrives it will cover portable preferences only: machine-specific values (ports, paths, hardware profiles, local model endpoints) are deliberately excluded, and secrets will continue to stay in the OS keychain and never sync.

Until then, two things are worth knowing:

Project content already travels. plan.md, blueprint.md, milestones.json, and wiki/ sit in the project’s own .miton/ folder, so committing the project carries that work to every machine and teammate. Your app preferences don’t move with it — there’s no project-level settings override.
Your own sync tool works for the user profile, with one caveat: syncing the whole profile directory between different operating systems will carry machine-specific values across too, and those can misbehave. Sync deliberately, not wholesale.

What this page does not cover

Encrypted settings files — JSON is plain text; keys stay in the keychain
Full settings schema — see architecture package docs for field-level detail