Etiquette

Govern agent-assisted engineering work with seats, evidence, and promotion gates. Local-first: your repo is the ledger, receipts are the proof, and no server ever sees your code.

When several coding agents (and humans) work the same repository, the hard part isn't running them — it's knowing who did what, on whose authority, and what proved it worked. Etiquette gives each participant a seat, each unit of work a task envelope, each completion a receipt, and each merge a promotion gate — recorded as plain files and git history you can audit.

Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt

Package split

Etiquette is now shipped as a small open core plus execution planes:

| Package / repo | Role | | --- | --- | | @etiquekit/core | Public open governance contract: schemas, pure state machines, authority/refusal rules, plane profiles, and conformance. | | @etiquekit/etq | Thin local execution plane: CLI, git journal, worktree/session ergonomics, local evidence return, and developer-facing docs. It consumes @etiquekit/core. | | remote-etq | Private managed execution plane: API, sequencer, workers, tenancy, and hard-stop enforcement. |

The public source homes are linked from npm package metadata and https://etiquekit.com/docs/. The open reference is the core contract plus sample/conformance surfaces. etq is the production local plane that dogfoods that contract.

Install

npm install -g @etiquekit/etq        # local exec plane; installs @etiquekit/core
curl -fsSL https://etiquekit.com/install.sh | sh   # or: native installer

Requires bun >= 1.3 and git >= 2.40. macOS and Linux. The installer verifies signatures against a pinned key before executing.

Sixty seconds to a governed workspace

etq init --project .                  # provision folders, journal, roster
etq doctor --project .                # readiness — green before work
etq bootstrap local --project . \
    --profile codex-cc-gemini --task-prefix APP
etq setup --target auto --project .   # register your agent CLI (explicit)
etq join --seat codex-seat --project . # profile seats: codex/cc/gemini/manager
etq console board --project . --text  # the live task board

Per-runtime seat packs: provision-seat claude-code · provision-seat codex · provision-seat gemini · provision-seat ollama · provision-seat openrouter.

The daily loop:

etq pickup --seat codex-seat --task APP-001 --expect-project-id <id> --text
# ... do the work; write the receipt at the path pickup names ...
etq post --role implementation-return --lane APP-001 \
    --from codex-seat --to manager-seat --project .
etq return check --task APP-001 --seat codex-seat   # the completion gate

(dispatch check gates routing BEFORE work; return check gates completion.) Every step appends to the workspace journal — an append-only event log inside your repo. Nothing leaves your machine: no backend, no telemetry, no account.

Concepts in one breath

| Concept | Answers | | --- | --- | | Seat | What durable work role is acting? | | Task envelope | What writes, validation, and stop conditions are allowed? | | Session | Which bounded run produced the evidence? | | Receipt | What proves the work happened? | | Promotion gate | Where does candidate work become accepted truth? |

Commands initialize, check, record evidence, and project read models. They never grant, merge, close, publish, or promote — evidence, not authority.