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
  <project>/<ticket>/      # a parked run's saved state
    run.db
    transcript.json

Two things worth knowing:

• A normal styre run does not use styre.db. Each run gets its own throwaway database unless you point it at a shared one with --db. The file in the state tree only matters if you run styre migrate and manage a 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.