ploeg

module
v0.2.0-rc.64 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 24, 2026 License: Apache-2.0

README

Ploeg

Developed independently at ploeg-hq/ploeg. See provenance.

Ploeg is a self-hosted service for authorizing and coordinating agent work. Tracker assignments can start unattended workers; an operator consumer 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

  • Quickstart: install a signed release on a local kind cluster and complete your first Run, with no outside accounts.
  • Documentation: current guides, contracts and design history.
  • Architecture: what runs where and who holds authority.
  • Managed workers: required configuration and recovery.
  • Network policies: what every Ploeg pod may reach, and what your CNI must enforce.

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.

An operator consumer supplies the human workbench and delegated workspace execution through the operator API. Its admitted 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, ClickUp and GitHub Issues tracker integrations, Forgejo, GitLab and GitHub 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.

GitHub Issues can be a runtime tracker: a ploeg:<team> label on an issue in a configured repository dispatches it (how to connect it). GitHub can also be the forge: a Run pushes and opens its pull request with its own GitHub App installation token (how to connect it). Hosting Ploeg's own backlog on GitHub configures nothing; a deployment opts in.

Project

Governance · Maintainers · Contributing · Code of conduct · Security · Scope and stewardship · Provenance

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. Documentation: CC-BY-4.0.

REUSE.toml says which licence covers each file. Markdown pages, llms.txt and images under docs/ are CC-BY-4.0. Everything else is Apache-2.0, including the API specifications in docs/contracts/ and the brand files in docs/brand/. Code samples inside the documentation are also available under Apache-2.0, so you can paste them into your own code. When you republish the documentation, credit it as Ploeg documentation, link https://github.com/ploeg-hq/ploeg, keep the copyright notice, name CC BY 4.0 and say if you changed it. The split follows the CNCF charter, §11(b)(iii) for code and §11(b)(iv) for documentation; see ADR-0140.

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-mcp command
Command ploeg-mcp serves Ploeg's operator API as MCP tools.
Command ploeg-mcp serves Ploeg's operator API as MCP tools.
ploeg-okf command
Command ploeg-okf works with the OKF bundles Ploeg briefs Runs from:
Command ploeg-okf works with the OKF bundles Ploeg briefs Runs from:
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
activework
Package activework tells a Run which other active Shifts work in its repository and which paths they share with it (ADR-0123).
Package activework tells a Run which other active Shifts work in its repository and which paths they share with it (ADR-0123).
boardview
Package boardview renders a Run's view of the blackboard (ADR-0124): the findings section of its briefing under a fixed budget, freshest first and every item cited, and the short difference a Run is handed when it catches up with the board at a checkpoint.
Package boardview renders a Run's view of the blackboard (ADR-0124): the findings section of its briefing under a fixed budget, freshest first and every item cited, and the short difference a Run is handed when it catches up with the board at a checkpoint.
claudesession
Package claudesession verifies the session token Anthropic gives every Claude Code session in a self-hosted environment (CLAUDE_CODE_SESSION_ACCESS_TOKEN), so ploegd can trust a request that comes from a runner's session hook (ADR-0084).
Package claudesession verifies the session token Anthropic gives every Claude Code session in a self-hosted environment (CLAUDE_CODE_SESSION_ACCESS_TOKEN), so ploegd can trust a request that comes from a runner's session hook (ADR-0084).
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.
consumers
Package consumers checks the expectations that consumers of Ploeg's contracts record against the contracts and routes this Ploeg serves (ADR-0147).
Package consumers checks the expectations that consumers of Ploeg's contracts record against the contracts and routes this Ploeg serves (ADR-0147).
contextbundle
Package contextbundle checks and unpacks the files a person attaches to a Work Item (proposed, context bundles proof of concept).
Package contextbundle checks and unpacks the files a person attaches to a Work Item (proposed, context bundles proof of concept).
contracts
Package contracts names the published contracts under docs/contracts that this Ploeg serves, and the major version of each it answers (ADR-0147).
Package contracts names the published contracts under docs/contracts that this Ploeg serves, and the major version of each it answers (ADR-0147).
diffmeasure
Package diffmeasure takes raw per-file measurements from a unified diff, so Ploeg can keep them as delivery facts without keeping the diff (ADR-0079).
Package diffmeasure takes raw per-file measurements from a unified diff, so Ploeg can keep them as delivery facts without keeping the diff (ADR-0079).
findings
Package findings derives the findings ledger of a Work Item (ADR-0121): which reviewer findings were raised by id, how each writer answered them, which questions Runs asked and who answered, and where a shadow reviewer's verdict differed from the acting reviewers'.
Package findings derives the findings ledger of a Work Item (ADR-0121): which reviewer findings were raised by id, how each writer answered them, which questions Runs asked and who answered, and where a shadow reviewer's verdict differed from the acting reviewers'.
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 reads the reason a Work Item bounced back (ADR-0051).
Package gate maps tracker statuses to the delivery gates a Work Item passes, and reads the reason a Work Item bounced back (ADR-0051).
githubapi
Package githubapi holds what every GitHub caller in Ploeg shares: where the REST API lives for a GitHub web root, a client that waits out GitHub's primary and secondary rate limits, and Link-header pagination (ADR-0086).
Package githubapi holds what every GitHub caller in Ploeg shares: where the REST API lives for a GitHub web root, a client that waits out GitHub's primary and secondary rate limits, and Link-header pagination (ADR-0086).
githubapp
Package githubapp mints repository-scoped GitHub App installation tokens.
Package githubapp mints repository-scoped GitHub App installation tokens.
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/claudeenv
Package claudeenv runs a Run as a Claude Code session in a Team's self-hosted Claude environment (ADR-0084).
Package claudeenv runs a Run as a Claude Code session in a Team's self-hosted Claude environment (ADR-0084).
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/claudeplugins
Package claudeplugins installs the Claude Code plugins a Team declares into a claude-code Run (ADR-0139): each plugin is fetched from a marketplace at a pinned commit, copied with only its skills, commands, agents and hooks, and every hook command is rewritten to run under a guard that hands it only the plugin's declared environment and never lets it block or stop the Run.
Package claudeplugins installs the Claude Code plugins a Team declares into a claude-code Run (ADR-0139): each plugin is fetched from a marketplace at a pinned commit, copied with only its skills, commands, agents and hooks, and every hook command is rewritten to run under a guard that hands it only the plugin's declared environment and never lets it block or stop the Run.
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/launch
Package launch carries a Run's processes from ploeg-worker to the harness's own container (ADR-0138).
Package launch carries a Run's processes from ploeg-worker to the harness's own container (ADR-0138).
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).
httpclient
Package httpclient holds the one connection pool Ploeg's outbound API clients share: forges, trackers, the model gateway and the notes graph.
Package httpclient holds the one connection pool Ploeg's outbound API clients share: forges, trackers, the model gateway and the notes graph.
knowledge
Package knowledge selects the part of one or more OKF bundles that bears on a Work Item and writes it as a knowledge pack: an OKF bundle of its own that a Run reads from disk, with an index that says why each concept is there.
Package knowledge selects the part of one or more OKF bundles that bears on a Work Item and writes it as a knowledge pack: an OKF bundle of its own that a Run reads from disk, with an index that says why each concept is there.
knowledgegraph
Package knowledgegraph reads and writes a Tenant's knowledge graphs through the stored queries of the tenant-knowledge and tenant-notes schemas (ADR-0087, ADR-0088, ADR-0122).
Package knowledgegraph reads and writes a Tenant's knowledge graphs through the stored queries of the tenant-knowledge and tenant-notes schemas (ADR-0087, ADR-0088, ADR-0122).
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.
mcpauth
Package mcpauth makes an MCP server, or any Ploeg API, an OAuth 2.1 resource server for an OpenID Connect issuer such as Authentik.
Package mcpauth makes an MCP server, or any Ploeg API, an OAuth 2.1 resource server for an OpenID Connect issuer such as Authentik.
notes
Package notes holds the rules every note in a Tenant's notes graph follows (ADR-0122): who wrote it and from what, whether its text may be trusted, which Runs may read it, when it stops being read, when a newer note replaces it, when two notes disagree, and when a note may reach a wider level.
Package notes holds the rules every note in a Tenant's notes graph follows (ADR-0122): who wrote it and from what, whether its text may be trusted, which Runs may read it, when it stops being read, when a newer note replaces it, when two notes disagree, and when a note may reach a wider level.
okf
Package okf reads and writes Open Knowledge Format (OKF) v0.1 bundles: a directory of markdown files, one concept per file, each opening with YAML frontmatter whose only required field is type.
Package okf reads and writes Open Knowledge Format (OKF) v0.1 bundles: a directory of markdown files, one concept per file, each opening with YAML frontmatter whose only required field is type.
omnigraph
Package omnigraph is a minimal client for an Omnigraph server's stored queries: ploegd invokes the queries a deployment's bundle declares and never sends query text of its own.
Package omnigraph is a minimal client for an Omnigraph server's stored queries: ploegd invokes the queries a deployment's bundle declares and never sends query text of its own.
omnigraph/omnigraphtest
Package omnigraphtest fakes an Omnigraph server's notes graph over HTTP, answering the tenant-notes stored queries the way Omnigraph 0.11 does, including the conditional route that refuses a write with 412 once the branch moved past the commit it names.
Package omnigraphtest fakes an Omnigraph server's notes graph over HTTP, answering the tenant-notes stored queries the way Omnigraph 0.11 does, including the conditional route that refuses a write with 412 once the branch moved past the commit it names.
operatorclient
Package operatorclient is a Go client for Ploeg's operator API (docs/contracts/operator-api.v1.schema.json).
Package operatorclient is a Go client for Ploeg's operator API (docs/contracts/operator-api.v1.schema.json).
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).
premise
Package premise is the premise check before a Work Item's writer (ADR-0123, deciding ADR-0036's T0): one classifier call on a gateway model that costs nothing per token says whether the Work Item can go to a writer as written, needs a person's answer first, or is too big for one pull request.
Package premise is the premise check before a Work Item's writer (ADR-0123, deciding ADR-0036's T0): one classifier call on a gateway model that costs nothing per token says whether the Work Item can go to a writer as written, needs a person's answer first, or is too big for one pull request.
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/github
Package github is the ForgeProvider for GitHub (github.com and GitHub Enterprise Server), the sibling of pkg/provider/forgejo and pkg/provider/gitlab (ADR-0086).
Package github is the ForgeProvider for GitHub (github.com and GitHub Enterprise Server), the sibling of pkg/provider/forgejo and pkg/provider/gitlab (ADR-0086).
provider/githubissues
Package githubissues is a TrackerProvider for GitHub Issues: webhook verification and parsing, authenticated issue reads, and the comment and close write-backs that let a Run reach a person (ADR-0085).
Package githubissues is a TrackerProvider for GitHub Issues: webhook verification and parsing, authenticated issue reads, and the comment and close write-backs that let a Run reach a person (ADR-0085).
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).
runidentity
Package runidentity issues and verifies the Run identity (ADR-0149): a short-lived JWT, signed ES256 by ploegd, that names one Run and its place in its Work Item for a declared observer.
Package runidentity issues and verifies the Run identity (ADR-0149): a short-lived JWT, signed ES256 by ploegd, that names one Run and its place in its Work Item for a declared observer.
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.
svgsafe
Package svgsafe decides whether an SVG an operator consumer hands Ploeg is safe to store on a forge and embed in a pull request comment (ADR-0079).
Package svgsafe decides whether an SVG an operator consumer hands Ploeg is safe to store on a forge and embed in a pull request comment (ADR-0079).
target
Package target resolves where a Work Item's changes land.
Package target resolves where a Work Item's changes land.
taskprompt
Package taskprompt renders the task prompt every harness delivers to its agent: the Work Item, the briefing of earlier Rounds and the delivery contract.
Package taskprompt renders the task prompt every harness delivers to its agent: the Work Item, the briefing of earlier Rounds and the delivery contract.
transcript
Package transcript records what an agent did during a Run as ordered, typed entries and ships them to ploegd in batches (ADR-0090).
Package transcript records what an agent did during a Run as ordered, typed entries and ships them to ploegd in batches (ADR-0090).
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL