Configuration and state

Configuration is optional. Lookup order:

1. $SHIREI_CONFIG.
2. $XDG_CONFIG_HOME/shirei/config.toml.
3. ~/.config/shirei/config.toml.

Example

backend = "tmux"
roots = ["~/projects/*", "~", "~/.config"]
recent_cap = 20
worktree_root = "~/.local/share/shirei/worktrees"
worktree_exclude_prefixes = ["~/Library/Caches"]
run_install_on_create = true

Settings

Setting	Default	Description
backend	"tmux"	"tmux" or "herdr"
roots	~/projects/*, ~, ~/.config	Paths included in root discovery
recent_cap	20	Maximum recent directories retained
worktree_root	~/.local/share/shirei/worktrees	Parent directory for branch worktrees
worktree_exclude_prefixes	~/Library/Caches	Prefixes ignored during scans
run_install_on_create	true	Run detected setup in a new worktree

Configured roots support literal paths and a final /* for direct children. They are not recursive shell globs. Shirei expands ~ and leading ~/; it does not expand arbitrary environment variables in config values.

State

State lookup order:

1. $SHIREI_STATE_DIR/state.json.
2. $XDG_DATA_HOME/shirei/state.json.
3. ~/.local/share/shirei/state.json.

The JSON file stores:

• Recent directories and their last-used timestamps.
• Registered worktree path, repository, branch, and creation time.

Shirei has no daemon or database. State writes are not locked, so avoid running multiple state-mutating Shirei commands concurrently.

Back up state

Before a broad scan or manual edit:

cp ~/.local/share/shirei/state.json ~/.local/share/shirei/state.json.bak

If you override SHIREI_STATE_DIR or XDG_DATA_HOME, back up the resolved file instead.