Environment variables

The environment variables that piloop reads, and the ones that it sets for the programs it runs.

Variables that you set

Variable	Default	Meaning
PILOOP_HOME	~/.piloop	The directory of the database (piloop.db), the daemon’s files (serve.pid, serve.log) and the directories of the runs and agents. One daemon runs for each PILOOP_HOME.
PILOOP_ACTOR	human	The name that this process signs its writes with. The database records it in updated_by and in the events. An orchestrator sets PILOOP_ACTOR=orchestrator, so that piloop inbox wait skips its own writes.
PILOOP_PROJECT_<KEY>	none	Overrides a key of piloop.toml when piloop init reads the file. piloop init stores the result, and the daemon uses it until the next piloop init. Set on piloop serve, it has no effect. Join nested keys with __, for example PILOOP_PROJECT_RUNTIME=herdr. piloop doctor reads it too.
PILOOP_SECRETS_COMMAND	none	A shell command that prints NAME=value lines. The daemon adds them to its environment when it starts and when it restarts. See Secrets.
PILOOP_HERDR_SESSION	piloop	The name of the Herdr session that piloop uses. piloop starts a headless Herdr server for this session on first use. It never uses the session that you work in.
PILOOP_DEBUG	off	Set it to 1 to see the full traceback of an unexpected error, instead of a short message.
PILOOP_TICK_SECONDS	2	How often the daemon checks the triggers of every project and starts the requested agents.
OTEL_EXPORTER_OTLP_ENDPOINT	none	Sends the daemon’s spans to this OpenTelemetry collector.
CLAUDE_CONFIG_DIR	~/.claude	Claude Code’s configuration directory. piloop install-skills writes Claude Code’s skills to its skills/ directory. piloop reads the token usage of Claude Code agents from its projects/ directory.
CODEX_HOME	~/.codex	Codex’s home directory. piloop reads the token usage of Codex agents from its sessions/ directory.
PILOOP_AGENT_SKILLS_DIR	~/.agents/skills	The skill directory of Codex, pi, Gemini CLI and Cursor.
UV_TOOL_DIR	~/.local/share/uv/tools	Where uv keeps its tools. piloop upgrade reads how piloop was installed from there. If you set XDG_DATA_HOME, uv uses another directory: set UV_TOOL_DIR to it.
PILOOP_SRC	PyPI	For install.sh only: install piloop from this checkout or pip-style URL instead of from PyPI.
HERDR_SOCKET_PATH	none	Herdr sets it in every pane that it manages. piloop attach reads it to tell whether it already runs in the piloop session. Do not set it yourself.

Timeouts

These control how long piloop waits for Herdr and Entire. The defaults suit most machines.

Variable	Default	Meaning
PILOOP_HERDR_SERVER_START_SECONDS	10	How long to wait for the Herdr server of the piloop session to answer after it starts.
PILOOP_HERDR_START_TIMEOUT_SECONDS	60	How long Herdr may take to detect an agent that just started.
PILOOP_HERDR_CLI_TIMEOUT_SECONDS	30	The timeout of one herdr command, in addition to the time that it waits.
PILOOP_HERDR_UNAVAILABLE_SECONDS	300	How long to retry a read of a Herdr server that does not answer before the read fails. Prompts and keys are never sent twice.
PILOOP_HERDR_PROMPT_PICKUP_SECONDS	5	How long to wait for an idle agent to resume work after piloop prompts it, and for Herdr to report the session of a started agent.
PILOOP_HERDR_STARTUP_GRACE_SECONDS	60	How long an agent has to start its first turn after its brief is submitted. Until then, a brief not yet picked up is not lost, and a quiet agent is not finished.
PILOOP_HERDR_SHELL_READY_SECONDS	10	How long to retry the start of an agent while the shell of a new tab starts.
PILOOP_HERDR_WAIT_CHUNK_SECONDS	10	The longest single wait on an agent. A closed tab is noticed within this time.
PILOOP_ENTIRE_ATTACH_TIMEOUT_SECONDS	120	How long entire session attach may take before piloop stops it.

Variables that piloop sets

Variable	Set for	Meaning
PILOOP_ACTOR	every agent	The agent’s signature, <role>#<worker-id>, for example worker#12. A scout sweep signs scout#<worker-id>.
PILOOP_HOME	every agent	The same directory as the daemon’s, so that the agent’s piloop commands use the same database.
PILOOP_UNITS_FILE	the evaluate command, in piloop’s own measurements only: the daemon’s, and the baseline that piloop init measures. Never in an agent’s environment.	The path where the evaluate command may write its per-unit results.
PILOOP_WORKER_TOKEN	every agent, with the Herdr runtime	A token that lets piloop find the background jobs that an agent started.
CLAUDE_CODE_CHILD_SESSION	every agent, set to empty	Claude Code sets it for every process that it runs. A Claude Code agent that inherits it saves no transcript, so piloop clears it.