Quick start

This page takes one change through the whole loop: declare an intent, push, propose, approve, land, and ask why a line is there.

What you need

	Version	Used for
Go	1.25.8 or later	Building the CLI
git	2.40 or later	Every command that touches a repo; the CLI shells out to it
A Wayglass Worker		Its URL and its key. Deploy your own with Self-hosting, or get both from whoever runs one

1. Install the CLI

go install github.com/wayglass/wayglass/cmd/wayglass@latest
wayglass version

Or build from a clone:

git clone https://github.com/wayglass/wayglass.git
cd wayglass
make build            # writes bin/wayglass

2. Log in

wayglass login stores the Worker URL and key in ~/.config/wayglass/credentials.yaml with mode 0600, after checking the key against the Worker. The key is read from standard input or from WAYGLASS_KEY, never from a flag, so it stays out of shell history and the process list.

printf '%s\n' "$KEY" | wayglass login --worker https://wayglass.example.com --key-stdin

The key is either the Worker’s admin key or an agent key bound to one name. Whoever runs the Worker logs in with the admin key and mints one agent key per agent or person:

wayglass keys create --agent claude-docs --note "docs agent on the laptop"

The key is shown once. Each agent logs in with its own key; the Worker then records every request under the key’s name and ignores any name the caller sends, so an agent cannot approve its own change as someone else. wayglass keys list and wayglass keys revoke <id> manage them. See Security model.

With the admin key, your name in the audit log defaults to user@host; set another with --agent at login, or per command with WAYGLASS_AGENT.

Check the setup:

wayglass doctor

doctor checks git, the stored login, that the Worker answers, that it accepts your key and which name it acts as, and, inside a project, that the trunk answers over git with a 60-second read-only token. It exits 1 if a check failed and says what to fix; --json gives the same checks to an agent.

WAYGLASS_URL, WAYGLASS_KEY and WAYGLASS_AGENT override the stored values on every command. WAYGLASS_CONFIG_DIR moves the config directory.

3. Initialise a repository

In the git repository agents will work on:

wayglass init

This creates the project on the Worker and its trunk repo in Artifacts, writes three files, commits them, and pushes HEAD to the trunk:

• .wayglass/policy.yaml, copied from the built-in example if the file does not exist yet. See Policy.
• .wayglass/config.yaml: project name, trunk repo and remote, jurisdiction. It holds no secrets.
• .wayglass/.gitignore, which ignores .wayglass/state/ (the current intent and session context; never tokens).

The project name defaults to the directory name. --jurisdiction eu puts the project’s repos in the EU namespace, if the Worker has one; this cannot be changed later. --public opts the project in to the web audit view.

4. Declare an intent

Before writing code, say what you will change and why:

wayglass intent declare \
  --goal "Add a getting-started guide" \
  --reason "New users get lost after install" \
  --path "docs/**"

The Worker forks the trunk for this intent and mints a write token for that fork, valid for 15 minutes. The intent becomes this checkout’s current intent, so later commands find it without an argument. If another open intent declared overlapping paths, you get a warning and a suggested re-plan; see Overlaps.

5. Edit and push

$EDITOR docs/guide.md
wayglass push -m "docs: add a getting-started guide"

With -m, push stages and commits every change first and appends a Wayglass-Intent: <id> trailer. Without it, commit yourself and run wayglass push. It pushes HEAD to the intent’s fork, reports the changed files to the Worker for overlap checks, and asks the Worker for a fresh fork token each time, so a long session never needs the original token.

6. Propose

wayglass propose

The CLI classifies the diff locally and shows a preview. The Worker then reads the fork itself, classifies it again, and decides with the policy from the trunk. The Worker’s decision is the one that counts. The exit code says what happens next:

Exit	Decision status	Next
0	approved (auto_merge)	wayglass land
0	pending_agent (agent_review)	A reviewer agent other than the author approves, then land
4	pending_human, quarantined	A person approves with wayglass approve
3	blocked	Change the code; a blocked decision can never be approved

propose --dry-run decides locally and records nothing.

7. Approve (as someone else)

Whoever the policy routed the change to approves it with a reason. The reason goes into the audit log and into the git note on the landed commit, so the CLI and the Worker both refuse placeholders such as TODO or <what you checked>.

wayglass review                                  # the queue, as a TUI on a terminal
wayglass approve i269d1c348e --reason "Read it; accurate and short"

The approver must run under a different name from the author. The Worker refuses a decision by the agent that wrote the change.

8. Land

wayglass land

The Worker hands out a trunk write token that lives 300 seconds, and only for an approved decision whose fork has not moved since. land merges the approved commit onto the current trunk in a temporary worktree, pushes it with the why note, and asks the Worker to verify that the trunk now holds exactly the approved change. If .wayglass/config.yaml names a mirror remote (for example origin on GitHub), land then pushes the trunk branch and notes there with your own git credentials. See Landing.

9. Ask why

wayglass why docs/guide.md:1

why blames the line to its commit and reads the note under refs/notes/wayglass: the intent’s goal and reason, the tags, the rule that matched, who decided, and each approver’s reason. Without a note in your checkout it asks the Worker.

Next

• For agents has the same loop written for an agent, with --json.
• wayglass watch shows every open intent, its tags and decisions as they happen.
• wayglass log reads the project’s audit log.