File Locations

Where pitchfork stores its files.

Configuration Files

Pitchfork supports configuration files in multiple locations. Files are merged in order, with later files overriding earlier ones.

Location	Purpose
/etc/pitchfork/config.toml	System-wide configuration
~/.config/pitchfork/config.toml	User configuration
.config/pitchfork.toml	Project configuration
.config/pitchfork.local.toml	Project configuration
pitchfork.toml	Project configuration
pitchfork.local.toml	Local project overrides

Config File Precedence (lowest to highest)

1. /etc/pitchfork/config.toml - System-wide (lowest precedence)
2. ~/.config/pitchfork/config.toml - User-wide
3. .config/pitchfork.toml - Project-level (in project's .config/ subdirectory)
4. .config/pitchfork.local.toml - Project-level (in project's .config/ subdirectory)
5. pitchfork.toml - Project-level (in project root)
6. pitchfork.local.toml - Local project overrides (highest precedence)

Within a given project directory, files take precedence in this order:

• .config/pitchfork.toml has lowest precedence in that project
• .config/pitchfork.local.toml overrides .config/pitchfork.toml
• pitchfork.toml overrides anything in .config/
• pitchfork.local.toml overrides both (typically git-ignored)

State Directory

Location: ~/.local/state/pitchfork/

File/Directory	Purpose
state.toml	Persistent daemon state
logs/	Daemon log files
ipc/main.sock	Unix socket for CLI-supervisor communication

State File

~/.local/state/pitchfork/state.toml tracks:

• Known daemons and their status
• Enabled/disabled state
• Last run information

Logs

Each daemon has its own log directory and file. The log path is determined by the daemon's qualified ID (namespace + name):

~/.local/state/pitchfork/logs/<namespace>--<daemon-name>/<namespace>--<daemon-name>.log

The namespace is derived from top-level namespace in the config when present, otherwise from the project directory name (or global for global config files). For example:

• Daemon api in project myapp → logs/myapp--api/myapp--api.log
• Daemon api in project yourapp → logs/yourapp--api/yourapp--api.log
• Daemon postgres in global config → logs/global--postgres/global--postgres.log

The -- separator is used to convert the / in qualified daemon IDs (e.g., myapp/api) to a filesystem-safe format.

Because -- is reserved for this encoding, project directory names containing -- (or other invalid namespace characters) require a top-level namespace override in pitchfork.toml.

See Namespaces for more details on how daemon IDs work across projects.

IPC Socket

~/.local/state/pitchfork/ipc/main.sock

Unix domain socket used for communication between CLI commands and the supervisor daemon.

Boot Start Files

Varies by platform:

Platform	Location
macOS	~/Library/LaunchAgents/com.pitchfork.agent.plist
Linux	~/.config/systemd/user/pitchfork.service
Windows	Registry at HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run