guild-cli

A file-based CLI for a team of agents — human and AI — to ask each other for work, review it, and leave an append-only trail.

Reviews are pinned to (actor, lense, moment). Corrections are new entries, never edits. Over time the content_root becomes an event log of judgments — not "what was decided" but how the decision was formed: who proposed, who objected, through which lense, and whether the objection was absorbed or overridden.

Status: alpha (0.x), latest v0.6 — multi-executor waves, profile- based swarm coordination, plugin extension surface (verb / hook / voice). Strict 0.x semver — see docs/POLICY.md. Threat model: SECURITY.md. Changes: CHANGELOG.md.

30 seconds

Pick the install style that fits — every step after register is the same.

# A. Use it standalone (most common):
git clone https://github.com/eris-ths/guild-cli && cd guild-cli && npm install

# B. Use it inside an existing repo:
npm install --save-dev eris-ths/guild-cli            # then `npx gate <verb>`
# (or `npm i -g eris-ths/guild-cli` for a system-wide `gate` command)

# C. One-off try without installing:
npx -y github:eris-ths/guild-cli gate <verb>

# Then, in whatever directory you want as the content_root:
gate register --name <you>               # once per content_root
export GUILD_ACTOR=<you>                 # once per shell (POSIX)
                                          #   fish: set -x GUILD_ACTOR <you>
                                          #   powershell: $env:GUILD_ACTOR = "<you>"
gate boot                                # orient (identity + queues + tail + inbox)
gate fast-track --action "..." --reason "..."   # request→approve→execute in one self-flow call

Throughout this README gate <verb> is the canonical form. After install A or B, gate resolves to ./bin/gate.mjs. If you'd rather spell it out, node ./bin/gate.mjs <verb> works too.

No guild.config.yaml? No problem. gate register works in any empty directory — the cwd becomes the content_root and you'll see a notice: config: none — cwd used as fallback root line so you know nothing is being silently inferred elsewhere. Drop in a guild.config.yaml later if you want to customize host_names or paths. If you do, pick <you> to be a name distinct from host_names: (default reservations: eris, nao) — hosts and members are different roles, and register --name eris is rejected with a one-line hint to pick a different name.

That's the loop. The whole tool is six verbs:

gate register   # become an actor
gate request    # ask for work
gate approve    # / deny
gate execute    # take it on
gate complete   # / fail
gate review     # leave a judgment under a named lense

These six are the full deliberation loop — for work someone else reviews or runs. gate fast-track (used in the 30-second loop above) is the self-flow shortcut: it collapses request → approve → execute into one call when you file and run the work yourself.

Everything else is depth on top.

Reading by depth

Pick a route. Each works on its own.

Goal	Path
Run something now	examples/quick-start/
Full verb map (AI-first reference)	AGENT.md
Multi-agent / swarm coordination	docs/swarm.md
Per-verb examples + design notes	docs/verbs.md
The newcomer translation (Jira / PR / ADR)	docs/concepts-for-newcomers.md
Why a choice was made (principles)	lore/principles/ or gate lore list
Combos, recipes, bug-killing flow	docs/playbook.md
Substrate-craft showcase (eris play)	docs/eris-playbook.md
Real long sessions	examples/dogfood-session/
Stability / on-disk shape contracts	docs/POLICY.md + docs/storage-format.md

For AI agents: read AGENT.md first, not this README. It's the quick reference — every verb, every state machine, in one file. The README exists to point you there.

日本語 → README.ja.md (independent, not a translation).

Passages

guild is the container; passages are different shapes of agent interaction running through the same content_root.

Passage	Shape (一語)	When to reach for it
gate	判断 / judgment	something needs a verdict
agora	探索 / exploration	stay with a thought; suspend / resume cliffs
devil	守備 / defense	protect third parties from an unsafe change
ctx	事実 / fact accumulation	record an observation; no verdict required

Set is open — see lore/principle 12. Architecture detail in AGENT.md. agora / devil / ctx are alpha and opt-in: only gate and guild are registered as bin commands (see package.json), so the alpha passages run via their script path — node ./bin/<name>.mjs .... gate is the primary entry; guild is the admin-side helper for managing the container itself.

Make it yours (optional)

The substrate ships with a neutral voice so AI agents reading on a cold session see the same shape across deployments. You may attach a deployment-local voice plugin to add personality without touching the upstream substrate:

# guild.config.yaml
plugins:
  trusted: true
  voices:
    - plugins/voices/mine.mjs
voice:
  default: mine

gate voice mine        # set the deployment-local voice mode
gate voice             # introspect (which voice + which layer)
gate voice off         # clear

Voice plugin contributes optional sections, each independent:

• verbs — ornamental narration on write-verb responses, surfaced as _meta.voice on the JSON envelope (and as a ⟶ ... line on stderr in text mode). Doctrinal handler prose is unchanged — augment, never replace (principle 08).
• schema — per-verb summary + per-flag description overrides, revealed via gate schema --voice <name>.
• essentials — a curated verb list driving gate --help --essentials. Mode switch swaps both 耳 (narration) and 手 (visible verbs).
• read.past_cliffs — re-renders gate boot's "past cliffs" section as letters from your past selves.

See examples/plugins/README.md § "Voice plugins" for the shape and AGENT.md § "Voice plugin" for the contract.

This is the eris-first half of the design: upstream substrate stays AI-agent-first and neutral; voices live local. Forking is not required to wear your own voice.

Install / Tests / License

Node 20 or 22. npm install auto-builds (prepare: tsc).

npm test

CI on Linux × Windows × Node 20 / 22 — CI is the source of truth. A handful of macOS-only failures (/var/folders ↔ /private/var/folders symlink resolution) do not occur in CI. See CONTRIBUTING.md for env-sensitivity notes.

MIT. See LICENSE.