Reference · 3 min read

Configuration files

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

Product stage: Pre-release development
Last reviewed: 2026-07-31
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
`skills/`, `subagents/`	User-global custom skills and sub-agents
`themes/`	Custom themes
`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.

Project folder (`.miton/`)

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

Path	Holds	Usually in git?
`settings.json`	Project-level settings overrides	Often yes
`plan.md`	Written project plan	Yes
`commands/`	Custom slash-command YAML files	Yes
`commands.yaml`	Enabled commands and shortcuts	Yes
`starters/`	Custom Writer document starters	Yes
`presets/`	Custom Automation workflow presets	Yes
`memory.sqlite`	Workspace memory database	No (local)
`citations.db`	Writer citation database	Varies
`data/*.db`	Canvas data blocks	Varies
`argus/`	Code search index	No
`argus-ignore`	Paths excluded from search (project root file)	Yes
`worktrees/`	Sub-agent git worktrees	No
`goals/`	Goal JSON files	Yes
`blueprint/`	Blueprint SQLite store	Varies
`wiki/`	Project wiki pages	Yes
`logs/`	Project-scoped diagnostic logs	No

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

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

For a given setting, Miton resolves:

workspace / project .miton/settings.json → user settings.json → built-in default

Unset keys fall through to the next level. 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, search index, worktrees, local databases
Workspace settings only	Deletes `.miton/settings.json`; re-created from project defaults on next open

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 settings already travel. .miton/settings.json is committed with the project, so anything you set at project level follows the repository to every machine and teammate.
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