Files and paths

Styre keeps its own files in two places outside your repo, does its work in a throwaway directory, and touches only a small, known set of files inside your repo. This page is the map.

Where Styre keeps its files

Two locations, both following the XDG convention and identical on macOS and Linux — there is no ~/Library special case. Each has one environment variable and a default.

Config — ~/.config/styre/ (or $XDG_CONFIG_HOME/styre/). Your settings and each project’s profile:

~/.config/styre/
  config.json              # global settings
  <project>/
    config.json            # per-project settings, overriding the global
    profile.json           # written by `styre setup`

State — ~/.local/state/styre/ (or $XDG_STATE_HOME/styre/). What Styre records as it runs:

~/.local/state/styre/
  styre.db                 # the shared database, only if you use one
  telemetry.json           # anonymous analytics id
  <slug>/<ident>/          # the live checkpoint — every run journals here as it works
    run.db
    transcript.json

Two things worth knowing:

• A normal styre run does not use styre.db. Each run gets its own checkpoint database under <slug>/<ident>/ unless you point it at a shared one with --db. That checkpoint is not a throwaway temp file — it is the run’s live state of record, written continuously while the run works, so it is there to resume from if the run pauses. The styre.db file in the state tree only matters if you run styre migrate and manage a shared database yourself.
• telemetry.json is a random id and nothing else — see Telemetry.

How the project name is chosen

The <project> directory in both trees is a slug, derived from your repo:

1. Styre reads the repo’s origin remote.
2. If that is a GitHub remote, the slug is the repo name — acme-app, not acme/acme-app.
3. If there is no remote, or it is not GitHub, the slug falls back to the repo’s directory name.

--slug <name> on setup or run overrides this if you want to pin it — useful when the derived name would collide with another project’s.

Where the work happens

While a run is going, Styre works in a fresh temporary directory under your system temp location — a git worktree that is the agent’s only writable surface. It is created per run and cleaned up afterwards. Your actual checkout is not touched, and nothing about a run persists in the temp directory once it is done.

The exception is --in-place, where the “worktree” is your repo root itself. That mode is opt-in and gated, precisely because it trades this isolation away.

What Styre touches inside your repo

During setup and a run, Styre reads and writes a small, fixed set of paths in the target repo:

Path	Access	What it is
.styre-disposable	read	A marker file you create to allow --in-place and no-argument setup. Its presence means “this checkout may be rewritten.” Must be a regular file.
AGENTS.md	read	Optional project context, read at setup if present.
styre_scratch/	write, then delete	A scratch area an agent may create. Always swept away before the change is committed — it never lands in your history.
The working branch	write	Created and committed to in the temporary worktree, then pushed.
docs/**, root README / CHANGELOG / CONTRIBUTING, mkdocs.yml	write	The only paths the documentation step may edit, when a ticket calls for doc changes.

Styre writes no log files

Nothing is logged to disk. styre run puts machine-readable NDJSON on stdout and everything human-readable on stderr; redirect those streams yourself if you want a record. See Telemetry for what that stream contains.

---

For the flags that change these locations, see the CLI reference. For what goes in the config and profile files, see Configuration and Project setup.