README
¶
Ploeg
Developed independently at ploeg-hq/ploeg. Extracted from Unfold; see provenance.
Ploeg is a self-hosted service for authorizing and coordinating agent work. Tracker assignments can start unattended workers; De Vloer can run interactive sessions under the same execution authority. PostgreSQL retains the work, leases, outcomes, evidence and accounting.
Ploeg is Dutch for a work crew or shift. The software is experimental and starts its independent release line at 0.1.0. Qualification applies to specific tested paths, not every provider or deployment.
Ploeg is the project. ploegd is its long-running controller/server (the d means daemon). ploeg-worker claims authorized work and executes it. Both binaries ship in the controller image.
Start here
- Documentation: current guides, contracts and design history.
- Architecture: what runs where and who holds authority.
- Managed workers: required configuration and recovery.
- De Vloer's local demonstration: both applications and PostgreSQL, using a deterministic fixture with no model calls.
How it works
Verified tracker webhooks enqueue work. KEDA or the CronJob executor starts workers that must claim authorized work. Configured Shift plans coordinate roles and review rounds. Workers invoke a harness, report results and renew their leases. KEDA polls queue depth; idle queue checks do not require model calls.
De Vloer supplies the human workbench and delegated workspace execution. Its shared path retains one Ploeg Work Item, Shift and operator Run across changes in supervision. Supported tracker selections can bind an existing queued Work Item. Manual-origin admission need not create a tracker ticket.
Management credentials remain in the controller. Scoped worker capabilities authorize control and inference. Unknown spending stays unresolved until trusted reconciliation.
The source includes Vikunja and ClickUp tracker integrations, Forgejo and GitLab forge integrations, team plans, tracker write-backs and multiple harness adapters. Capabilities differ by provider. See the implementation map and published contracts.
Delegated candidate delivery records verified evidence and candidate-bound approval. Its live publisher executor is not enabled. A completed Run is not automatically a published or accepted result.
Develop
Run mise run setup, mise run verify and mise run docs-check. Run tooling through mise and follow the repository instructions. The CI workflow defines Go build, vet and tests, Helm validation and golden renders, and brand/license checks. The backlog records planning history; GitHub Issues owns Ploeg priority.
Hosting Ploeg's backlog on GitHub does not enable GitHub Issues as a runtime tracker. The initial source has no GitHub tracker/forge adapter; that integration is separate planned work.
Releases
See release instructions and CI and infrastructure. Version 0.1.0 remains experimental; it does not claim production qualification or CNCF membership.
License
Code: Apache-2.0.
The name Ploeg and the Ploeg mark are trademarks — §6 of that licence grants no rights in them, deliberately. docs/brand/TRADEMARK.md says what you may do with them without asking (reproduce them, link, say your software works with Ploeg) and the two things that need permission (shipping a fork under the name, implying endorsement). Settled in ADR-0022.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ploeg-worker
command
ploeg-worker runs as the main container of an executor-spawned Job (docs/contracts/executor.md): it claims one work item from ploegd, drives a headless harness run via the adapter selected by PLOEG_HARNESS (design §5), and reports an OutcomeReport before exit.
|
ploeg-worker runs as the main container of an executor-spawned Job (docs/contracts/executor.md): it claims one work item from ploegd, drives a headless harness run via the adapter selected by PLOEG_HARNESS (design §5), and reports an OutcomeReport before exit. |
|
ploegd
command
ploegd is Ploeg's single daemon: webhook ingest, provider SPI host, lease manager, outcome ingestion.
|
ploegd is Ploeg's single daemon: webhook ingest, provider SPI host, lease manager, outcome ingestion. |
|
internal
|
|
|
ledger
Package ledger holds the consistency gate for the ADR corpus in docs/adrs/ (ADR 0001).
|
Package ledger holds the consistency gate for the ADR corpus in docs/adrs/ (ADR 0001). |
|
pkg
|
|
|
cardimage
Package cardimage draws a Run card as a static SVG image and as a compact Markdown summary, for the card comment Ploeg keeps on a pull request (ADR-0055).
|
Package cardimage draws a Run card as a static SVG image and as a compact Markdown summary, for the card comment Ploeg keeps on a pull request (ADR-0055). |
|
config
Package config loads ploegd's routing and roster configuration from a FILE rather than from environment variables.
|
Package config loads ploegd's routing and roster configuration from a FILE rather than from environment variables. |
|
flow
Package flow derives a Run card's flow figures from recorded tracker statuses, Runs, merges and deploys: time in every status, lead and cycle time, flow efficiency and working time under a team calendar (ADR-0057).
|
Package flow derives a Run card's flow figures from recorded tracker statuses, Runs, merges and deploys: time in every status, lead and cycle time, flow efficiency and working time under a team calendar (ADR-0057). |
|
followup
Package followup decides what happens to the Work Items a Run proposes (Product R12, ADR-0031): which are stored, for which Team, in which state, with how much budget, and why any are rejected.
|
Package followup decides what happens to the Work Items a Run proposes (Product R12, ADR-0031): which are stored, for which Team, in which state, with how much budget, and why any are rejected. |
|
forgebroker
Package forgebroker is the credential seam between Ploeg and a git forge: mint a repo-scoped, write-scoped token for one writing Run, hand it over, and revoke it when the Run settles or its Lease lapses.
|
Package forgebroker is the credential seam between Ploeg and a git forge: mint a repo-scoped, write-scoped token for one writing Run, hand it over, and revoke it when the Run settles or its Lease lapses. |
|
forgefacts
Package forgefacts turns what a forge reported about a pull request into the facts pkg/store keeps (ADR-0045, ADR-0046).
|
Package forgefacts turns what a forge reported about a pull request into the facts pkg/store keeps (ADR-0045, ADR-0046). |
|
gate
Package gate maps tracker statuses to the delivery gates a Work Item passes and derives bounces from the recorded moves (ADR-0051).
|
Package gate maps tracker statuses to the delivery gates a Work Item passes and derives bounces from the recorded moves (ADR-0051). |
|
harness
Package harness defines the contract between Ploeg and an agent harness: TaskSpec in, OutcomeReport out.
|
Package harness defines the contract between Ploeg and an agent harness: TaskSpec in, OutcomeReport out. |
|
harness/adapters/acp
Package acp adapts any agent speaking the Agent Client Protocol (ACP wire version 1) to Ploeg's harness seam — opencode, Gemini CLI, Goose and OpenHands natively, plus Codex and Claude Code through npm adapter processes.
|
Package acp adapts any agent speaking the Agent Client Protocol (ACP wire version 1) to Ploeg's harness seam — opencode, Gemini CLI, Goose and OpenHands natively, plus Codex and Claude Code through npm adapter processes. |
|
harness/adapters/claudecode
Package claudecode adapts the Claude Code CLI (backlog #62): a headless `claude -p` run with a JSON result envelope mapped into OutcomeReport usage (cost, tokens, session id).
|
Package claudecode adapts the Claude Code CLI (backlog #62): a headless `claude -p` run with a JSON result envelope mapped into OutcomeReport usage (cost, tokens, session id). |
|
harness/adapters/execbin
Package execbin is the generic escape-hatch adapter: run any binary against the published task contract.
|
Package execbin is the generic escape-hatch adapter: run any binary against the published task contract. |
|
harness/adapters/openhands
Package openhands adapts the OpenHands agent-runner image: the prompt is written to a task file and the image's baked entrypoint runs it headless.
|
Package openhands adapts the OpenHands agent-runner image: the prompt is written to a task file and the image's baked entrypoint runs it headless. |
|
harness/harnesstest
Package harnesstest is the adapter conformance kernel (backlog #69): every adapter must satisfy these properties regardless of which harness it wraps.
|
Package harnesstest is the adapter conformance kernel (backlog #69): every adapter must satisfy these properties regardless of which harness it wraps. |
|
harness/skills
Package skills holds the Agent Skills Ploeg mounts into every Run.
|
Package skills holds the Agent Skills Ploeg mounts into every Run. |
|
httpapi
Package httpapi exposes ploegd's two surfaces: webhook ingest (tracker → queued work) and the run API an agent container uses (claim, renew, checkpoint, outcome) per the worker-claims-at-startup convention (backlog #48).
|
Package httpapi exposes ploegd's two surfaces: webhook ingest (tracker → queued work) and the run API an agent container uses (claim, renew, checkpoint, outcome) per the worker-claims-at-startup convention (backlog #48). |
|
litellm
Package litellm wraps the LiteLLM proxy admin API for per-run key lifecycle (mint + revoke, list + batch delete).
|
Package litellm wraps the LiteLLM proxy admin API for per-run key lifecycle (mint + revoke, list + batch delete). |
|
llmbroker
Package llmbroker is the credential seam between Ploeg and an LLM gateway: mint a budgeted per-run credential before the harness starts, revoke it on every return path, and reconcile leaks from ploegd's sweeps.
|
Package llmbroker is the credential seam between Ploeg and an LLM gateway: mint a budgeted per-run credential before the harness starts, revoke it on every return path, and reconcile leaks from ploegd's sweeps. |
|
plan
Package plan parses and validates Team plans: the ordered list of Rounds a Shift works through, each naming Roles with their writes flag and per-Run spending cap (run-multi-agent-shifts design.md D5).
|
Package plan parses and validates Team plans: the ordered list of Rounds a Shift works through, each naming Roles with their writes flag and per-Run spending cap (run-multi-agent-shifts design.md D5). |
|
playkpi
Package playkpi derives the pull request, CI and change-shape figures of a Run card's plays from the facts a forge reported (ADR-0058): when a play was opened, became ready, got its first feedback and approval and merged; how its CI runs went; and how large, tested and indented its change was.
|
Package playkpi derives the pull request, CI and change-shape figures of a Run card's plays from the facts a forge reported (ADR-0058): when a play was opened, became ready, got its first feedback and approval and merged; how its CI runs went; and how large, tested and indented its change was. |
|
provider
Package provider defines Ploeg's SPI.
|
Package provider defines Ploeg's SPI. |
|
provider/clickup
Package clickup is a TrackerProvider for ClickUp, the sibling of pkg/provider/vikunja: webhook verification and parsing, plus the API write-backs that let a run reach a person (backlog #31).
|
Package clickup is a TrackerProvider for ClickUp, the sibling of pkg/provider/vikunja: webhook verification and parsing, plus the API write-backs that let a run reach a person (backlog #31). |
|
provider/forgejo
Package forgejo is the reference ForgeProvider (design §4): the first implementation of an interface that has been declared since the SPI was carved and had no caller until the blackboard needed one (ADR-0011).
|
Package forgejo is the reference ForgeProvider (design §4): the first implementation of an interface that has been declared since the SPI was carved and had no caller until the blackboard needed one (ADR-0011). |
|
provider/gitlab
Package gitlab is a ForgeProvider for GitLab (self-managed or gitlab.com), the sibling of pkg/provider/forgejo.
|
Package gitlab is a ForgeProvider for GitLab (self-managed or gitlab.com), the sibling of pkg/provider/forgejo. |
|
provider/vikunja
Package vikunja is the reference TrackerProvider (design §4): webhook verification and parsing, plus the API write-backs that let a run reach a person (backlog #31).
|
Package vikunja is the reference TrackerProvider (design §4): webhook verification and parsing, plus the API write-backs that let a run reach a person (backlog #31). |
|
rarity
Package rarity computes how exceptional a Run card's change was: a challenge score from facts the steward does not control after the fact, and the tier that score earns in its cohort (ADR-0056).
|
Package rarity computes how exceptional a Run card's change was: a challenge score from facts the steward does not control after the fact, and the tier that score earns in its cohort (ADR-0056). |
|
sandboxlaunch
Package sandboxlaunch starts one Run on kubernetes-sigs/agent-sandbox: it creates a single cold SandboxClaim for the launcher's Job and waits for it to finish (docs/contracts/executor.md, the agent-sandbox executor).
|
Package sandboxlaunch starts one Run on kubernetes-sigs/agent-sandbox: it creates a single cold SandboxClaim for the launcher's Job and waits for it to finish (docs/contracts/executor.md, the agent-sandbox executor). |
|
shiftengine
Package shiftengine owns the Shift lifecycle: when a Shift opens, how a Round advances, when a Shift closes, and what happens when either is left half-done (run-multi-agent-shifts, shift-orchestration spec).
|
Package shiftengine owns the Shift lifecycle: when a Shift opens, how a Round advances, when a Shift closes, and what happens when either is left half-done (run-multi-agent-shifts, shift-orchestration spec). |
|
store
Package store is Ploeg's Postgres data layer: work items, leases, checkpoints, runs, and the audit log.
|
Package store is Ploeg's Postgres data layer: work items, leases, checkpoints, runs, and the audit log. |
|
target
Package target resolves where a Work Item's changes land.
|
Package target resolves where a Work Item's changes land. |
|
work
Package work defines Ploeg's core semantics: work items, leases, checkpoints, and outcomes.
|
Package work defines Ploeg's core semantics: work items, leases, checkpoints, and outcomes. |
|
worker
Package worker is the run orchestrator that executes one claimed work item: claim → clone → compose prompt → mint credential → harness adapter run → forge-poll outcome resolution → outcome report.
|
Package worker is the run orchestrator that executes one claimed work item: claim → clone → compose prompt → mint credential → harness adapter run → forge-poll outcome resolution → outcome report. |