Pidgen worker

The Pidgen worker is the program that does Pidgen's work on a machine you control. When a run in your Account reaches a step, the hosted Pidgen service hands that step to one of your workers; the worker checks out the repository, runs a coding agent or a script in a workspace on your machine, and sends the result back. Your source code, your coding-agent logins and the agents' sessions stay on that machine.

The worker is installed as one command, pidgen-worker. You normally set it up with the Pidgen CLI (pidgen setup), which installs the worker, enrolls it into your Account and starts it. These pages cover what happens on the machine after that: how the worker is sized, which coding agents and subscriptions it uses, and the pidgen-worker commands you run there.

Installing, enrolling, starting and stopping

The Pidgen CLI owns these, and its documentation describes them:

• Install a worker: install the worker, enroll it into your Account, and start it.
• Workers: start, stop, update a worker and check its status.

What the worker does on your machine

A worker is one long-running process, the manager, and the processes it starts:

• Prompt workers run coding-agent steps. They form one pool shared by every coding agent the worker runs. The manager grows the pool while agent steps are waiting and shrinks it again when they are not.
• Script workers run the bash: and script: steps of a workflow, in a pool of their own that grows and shrinks the same way.
• One workspace worker owns the repository clones and working trees on the machine. It prepares a workspace before a step runs and delivers the step's changes afterwards.

Only the manager talks to the Pidgen service. The processes it starts reach the service through the manager, and none of them, nor any coding agent they run, receives the worker's credential. A coding agent also runs with a limited environment rather than everything exported in your shell; Coding agents and subscriptions says what it gets.

How many processes run, and how many sessions of each coding agent run at once, is up to you: see Configure the worker.

Where the worker keeps its files

Everything the worker owns lives under one directory, its home: ~/.pidgen unless your setup chose another one (the PIDGEN_HOME environment variable names it).

Path under the home	What it is
worker.env	The worker's credential and connection settings. Readable only by you; never share it.
config/node.yaml	How the worker is sized and which coding agents it runs. See Configure the worker.
config/worker-policy.yaml	How each coding agent runs on this machine. See The worker policy.
repos/	The repository clones the worker keeps.
workspaces/	The working trees steps run in.
logs/	The worker's logs.

What the machine needs

• Linux (x86_64 or arm64) or macOS (Apple Silicon or Intel).
• Python 3.12, 3.13 or 3.14.
• Git 2.25 or newer.
• Node.js 20 or newer and npm 10 or newer: every coding agent is installed with them.
• At least one coding agent, logged in: Pi, Claude Code or Codex. See Coding agents and subscriptions. Pi needs Node.js 22.19 or newer.

pidgen-worker doctor checks all of this and names everything that is missing; it starts nothing and changes nothing but creating the home if it is absent.

pidgen-worker doctor

It exits 0 when every check passes and 1 when any does not. pidgen-worker doctor --json prints the same report as JSON.

The worker and the Pidgen CLI

The Pidgen CLI (pidgen) and the worker (pidgen-worker) are two programs:

• pidgen is the Pidgen CLI. It sets workers up and manages them: install, enroll, start, stop, update and status.
• pidgen-worker runs on the machine that does the work. Its own commands configure that machine: pidgen-worker capacity sizes it, pidgen-worker subscriptions chooses the coding-agent login new work runs on, and pidgen-worker doctor checks it.

pidgen-worker --help lists every command, and pidgen-worker --version prints the version.