Skip to main content

Pinax

Pinax is a Git-native tracker for software delivery work. It stores an append-only JSONL event log in the repository, derives the current board from that log, and commits the generated Markdown board alongside the code.

The tracker gives a team one durable record of items, dependencies, ownership, status, and completion briefings. Git carries the record between clones and branches. There is no service to host, database to operate, or account to create.

Install

Pinax requires Python 3.10 or later and Git.

pipx install pinax-tracker
pinax --help

The same package installs with pip:

python -m pip install pinax-tracker

To work from a checkout:

git clone https://github.com/antikas/pinax-tracker.git
cd pinax-tracker
python -m pip install -e .

Start tracking a repository

Run pinax init at the root of the repository you want to track. It creates .ergon/, records the initial events, configures the log's merge attributes, and installs a pre-commit verification hook when Git allows it.

pinax init --actor alex@laptop
pinax add --title "Ship the widget" --actor alex@laptop
pinax claim <item-id> --actor alex@laptop
pinax done <item-id> --briefing completion.md --actor alex@laptop
pinax status

completion.md is a short work record. It stays with the item in the generated projection.

Everyday commands

pinax add --title TEXT
pinax claim ITEM_ID
pinax done ITEM_ID --briefing FILE
pinax block ITEM_ID --gate scope|decision|destructive|proposal [--owner-gate CLASS]
pinax park ITEM_ID --reason TEXT
pinax dep add FROM_ID --blocks TO_ID
pinax ready [--under ITEM_ID]
pinax next [--under ITEM_ID]
pinax status [--json] [--under ITEM_ID]
pinax board [--json]
pinax report [--json]
pinax release ITEM_ID --reason TEXT
pinax policy claim-expiry --hours N
pinax policy process --mode flow|strict
pinax policy owner-gates --class TEXT [--class TEXT ...]
pinax policy check [--json]
pinax verify [--fix]
pinax replay --at GIT_REF

pinax verify checks that every physical parsed event has a valid event hash unless it is covered by a valid tombstone, then compares the generated board and item pages with the committed projection. --fix regenerates only a drifted projection. It refuses invalid event history without changing the log or projection.

Owner-gate classes

A block with gate decision or destructive is a block for the owner: the item waits until the owner decides or approves. scope and proposal are not, and never need a class.

Each project chooses a process with pinax policy process --mode flow|strict. The last such event in the log is the one in force, and a log without one runs on flow.

Before you set strict, upgrade every clone, and every older pinax on PATH that a pre-commit hook could run, to 0.3.0 or later. Under strict the board and item files show the class, which an earlier Pinax does not write: it reports drift, its pre-commit hook refuses every commit, and its next write removes the class from the projection. After upgrading, run pinax verify --fix to repair the projection. The command prints the same warning when it sets strict.

  • flow: nothing is checked. --owner-gate CLASS on pinax block records the class in the event and nowhere else, so the board and item files are the same as an earlier Pinax writes for the same log. A block without the option is the same event as before. A class that matches a listed one, whatever its case and spacing, is stored in the list's spelling; any other class is stored as given with its spaces collapsed.

  • strict: a block for the owner must name a class with --owner-gate, and any class given must be on the project's list. A block with no class, or with a class not on the list, is refused, nothing is appended, and the command ends with exit 8. The check runs on the union with the remote, so a process set on another clone already binds. With --offline there is no remote check, so a strict process set on another clone and not yet pulled does not bind. The refusal is one line that shows the list, for example:

    pinax: strict process: 'because I said so' is not an owner-gate class. Give one of these with --owner-gate: production deployment; publication; ... Nothing was appended.
    pinax: strict process: a block with gate decision needs an owner-gate class. Give one of these with --owner-gate: production deployment; publication; ... Nothing was appended.
    

Under strict, while the item is blocked, the class shows on its board line (gate=decision · owner gate: publication) and as owner_gate: in its item file. When the item leaves blocked, the class goes with the block.

The list is project policy too: a project sets its own list with pinax policy owner-gates --class TEXT [--class TEXT ...]. Until it does, the list is:

  • production deployment
  • publication
  • real personal data
  • irreversible or destructive act
  • material change of scope, cost or architecture
  • login-bound act or owner-held input
  • start signal for a material plan

pinax policy check lists every blocked item for the owner with no class, or with a class not on the list. Under flow it only reports and exits 0. Under strict it exits 1 when it lists any item. It reads the local log and changes nothing, so pull before you run it.

Publishing a state change

Every command above that appends an event (add, claim, done, block, park, priority, dep, note, annul) runs the same publish sequence. It fetches the remote named origin, folds the union of the local log and the remote default branch's committed shards, appends the event, regenerates the board and item pages, commits the shard and the projection with the repository's hooks running, and pushes the remote default branch when that branch is checked out. This is what makes a claim or a completion visible to every other clone as soon as the command returns.

The commit carries the resolved tracker root in its environment, as PINAX_ROOT. The sequence gives a hook no arguments, so a hook that calls Pinax back, such as the pre-commit hook pinax init installs and the pinax verify it runs, checks the tracker the command resolved rather than whatever root the surrounding environment happened to name.

Every one of these commands also refuses an actor that is not written as role@host, before it appends anything.

All of them except claim accept --offline, or the PINAX_OFFLINE=1 environment variable, to skip the fetch and the push and commit locally only. A repository with no reachable origin, or no published default branch, behaves the same way on its own: the command commits locally and prints a warning naming the remote, instead of failing. A directory that is not a git repository at all falls back the same way, appending and regenerating the projection with a warning and no commit attempted, since there is nothing to commit into. claim is the one exception. Its whole purpose is telling every other machine an item is taken, so it always needs the remote: without a reachable origin, or without a git repository to fetch from, it ends without appending anything at all, rather than recording a claim nobody else can see.

The exit codes these commands share are:

0  the event is committed, and published when the remote default
   branch is checked out
1  the command names an item that does not exist (an annulment: an
   event that does not exist); nothing was appended
2  the actor is not written as role@host; nothing was appended
3  a published claim that the fold over the pushed remote state reports
   superseded
4  claim needed the remote and could not reach or read it, or any
   command's remote answered but its committed events could not be
   read
5  the push was rejected on every attempt
6  a claim's timestamp is behind published history, or cannot be read;
   nothing was appended
7  the shard and the projection could not be staged, or the commit
   was refused; the appended event stays uncommitted either way
8  the project's policy refuses the event: under the strict process,
   a block for the owner without a listed owner-gate class; nothing
   was appended

A hook that refuses the commit is never worked around. The command prints the hook's output, names the shard and the event id, leaves the appended event uncommitted, and ends with exit 7; fix what the hook objected to and commit the shard and the projection. A .gitignore rule that swallows .ergon/log/ is one of these refusals: the installed hook's pinax verify fails while the log is ignored, so a state-changing command ends with exit 7 instead of committing an event the repository would silently keep to itself. Run pinax init again to reinstall the .ergon/.gitignore negation, or fix the repository's own .gitignore, then commit the shard.

registry, reconcile, and init do not run this sequence. They keep their own local behaviour: registry records and lists remote repositories for pinax overview --remote, reconcile imports already-completed offline work from a text file into ordinary events, and init creates .ergon/ itself. None of the three needs cross-machine visibility the moment it runs, so none of them fetches or pushes.

pinax doctor reports two separate things a git-native tracker can be behind on: shards committed to HEAD but not yet on the remote default branch (unsynced, a normal state for offline work waiting to be pushed), and events appended to the working tree but not yet committed at all (uncommitted, an orphaned trail worth investigating). They are listed in distinct sections because they call for different next steps: push one, commit the other.

Storage model

.ergon/
  log/*.jsonl       append-only event shards
  board.md           generated project board
  items/<id>.md      generated item pages

Each event has a content-derived identifier. The fold sorts events by (seq, ts, actor, id), deduplicates by identifier, and applies the resulting stream deterministically. Git's union merge driver preserves concurrent JSONL appends; a duplicated line is a no-op in the fold.

Claims resolve during the fold. If two claims name one item, the earliest (ts, actor, id) claim wins and the other becomes a reported supersession. Dependency edges drive ready and next.

A live claim also makes its item ineligible for ready and next, on every clone, from the moment the claim reaches that clone's log - a claim and a status change are two different events, so a claimed item can still show status queued. pinax status renders such an item in its building list with the owner and how many hours ago the claim was made, labelled by the claim itself rather than the item's creation time, even before its status field ever moves to building. A held claim ends when it is released with pinax release ITEM_ID --reason TEXT, or when it expires: the policy in force is the last pinax policy claim-expiry --hours N event at or before the claim, and twenty-four hours by default when the log carries none before it. A quiet log - one that records nothing after the claim - never expires it, so a claim only ends when the log itself records the release or a later event past the deadline.

--under ITEM_ID on ready, next, and status restricts the view to the transitive parent-child descendants of that item - the ancestor's own row is never included, only its descendants; an id that names no item in the log is refused, nothing is appended. status --under requires repo scope; it is refused together with --portfolio and with the two-argument setter form. It scopes the building/shipped/parked lists and the next/queue_depth figures; the repo-wide claim-reconciliation notice count is unaffected.

next --json and status --json are JSON objects with an under key: the ancestor id, or null when --under is not given. ready --json is a bare array of item ids when --under is not given; with --under it is {"ready": [...], "under": "<id>"}. ready --json --all-branches is an object that also carries the under key.

An item with at least one parent-child child carries a derived rollup value beside its own status - done, building, blocked, or queued - summarising its children without ever changing the item's own status or its eligibility for ready/next. pinax board and pinax status render it alongside the status wherever it is present; the rule the fold applies is in DESIGN.md.

The predecessor field is a local consistency check. It can report a dangling predecessor reference, but version 1 does not hash the predecessor field or provide remote anchoring, signatures, or hostile-writer authentication.

The event envelope, integrity rules, and projection model are described in DESIGN.md. The executable event handlers and renderers are the authoritative implementation details. Architecture decisions are in docs/decisions.

Licence

Pinax is available under the MIT License.

Metadata

Release files for pinax-tracker 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pinax-tracker 0.3.0
File Size Uploaded Provenance Actions
pinax_tracker-0.3.0.tar.gz 330.6 kB With provenance Details for pinax_tracker-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pinax-tracker 0.3.0
File Interpreter ABI Platform Actions
pinax_tracker-0.3.0-py3-none-any.whl Python 3 none any Details for pinax_tracker-0.3.0-py3-none-any.whl

Total release size: 506.8 kB

Release files / pinax_tracker-0.3.0.tar.gz

Download URL pinax_tracker-0.3.0.tar.gz
Size 330.6 kB
Tags Source
SHA-256 checksum
How to use checksums
4137961bb2ed16fe1a92ebc36571158a1230eea74a93f3260db5e870ba8ca61a
BLAKE2b-256 checksum
How to use checksums
a1b9215d24357be31e6d7fbe66609765f96047188f21b3bf0c3925300ca219f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / pinax_tracker-0.3.0-py3-none-any.whl

Download URL pinax_tracker-0.3.0-py3-none-any.whl
Size 176.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1d903d1fef5dd42fa9e92508d2d2b31e8058efd3e1da1c54b901ec8c299d9d83
BLAKE2b-256 checksum
How to use checksums
4f08c1732410447571000eec45e635ca925adbd2f71d1acfd924daf4d31244ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for pinax-tracker 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pinax_tracker-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page