how wayari actually works

where it runs

wayari serve is the factory: one daemon per data directory, owning the shift clock, the gate queue and the caps. The Mac app starts it for you, and so does wayari start when nothing is running. The verbs that write talk to it over a local socket. The verbs that read go straight to the files, so wayari status and wayari review work with no daemon at all.

Agents live in tmux, one session per member, so they outlive the daemon. wayari stop hands the lock back and the agents keep working; the next wayari serve adopts them.

Data lives in ~/.wayari, or in the app's directory when the app is installed, or wherever WAYARI_HOME points.

branches, and what never touches main

Every channel gets channel/<id>, cut from your default branch. Each member works on agent/<id>/<member> in its own worktree, cut from the channel branch. Assembly merges the agent branches into the channel branch, and one pull request runs from there to your default branch.

The integrator refuses to merge into main, master, trunk or whatever your default branch is, and it only ever pushes channel/ and agent/ branches. Your default branch moves when you merge, and not before.

Assembly and the gate run in the channel's own checkout at <repo>/../wt/<channel>, so your HEAD never moves. A shift's branch reaches your remote within a minute of each new commit, so a laptop that dies at 4am costs a minute of work.

download

The download is Wayari, one universal dmg for Apple silicon and Intel, on macOS 11 or newer. Drag it into Applications and open it. Get it on the download page.

The first launch installs the wayari command to /usr/local/bin (macOS asks for your password once) and starts the factory in the background with wayari serve --detach. The dmg carries its own runtime, so the dock, the daemon and the command run without Node installed.

The dock is a small strip on your desktop that shows what the daemon is doing: channels, the gate queue, what waits on you. It can merge a pull request you've just read, and arm a channel. Everything else is the command, or your own agent through MCP.

check the machine

wayari doctor asks every question the factory will ask, before anything is opened, and prints the fix beside each miss. It checks tmux, git, gh signed in to GitHub and an agent CLI (Claude Code or Codex) that can actually take a turn, then the daemon, then Yari's model.

wayari doctor
wayari doctor --fix     # the installs it may run; never sudo, never a sign-in

--fix runs the package installs that need nobody's password and nobody's browser, then asks every question again, so its exit code describes the machine. Anything it won't do, it prints as the line for you to run.

pick yari's model

Yari plans, reviews and retries on the model you give him. There's no default, because a default would quietly set the price of every shift on the machine, so starting a shift refuses until you pick one.

wayari lead opus
wayari lead gpt-5.5 --agent codex   # Yari on Codex instead
wayari lead                         # lists the valid models

Builders don't take the lead's model by default. Routing puts ordinary build work on the cheapest model from the lead's own vendor, moves the second and third attempt at a stage up to the lead's model, and says which it picked and why in the channel. --model on start pins it.

your first channel

wayari start "show a real error when the password is wrong" --repo ~/code/app
wayari                       # every live channel, one line each
wayari open <channel>        # watch it live; type a line to talk to the crew
wayari review <channel>      # the read, before you merge
wayari merge <channel>

start opens the channel, staffs one builder and runs it until the work is done. There's no clock and no cap unless you name one with --hours, --minutes or --limit (dollars). A channel with no clock is still bounded: a shift that goes quiet is restarted at most three times, and then the channel holds.

Before it arms, start prints what a channel like this has cost here on that model, from the last five that ran on it, or says there's nothing to learn from yet.

• wayari do "fix the flaky auth test" is the same channel preset for a short job: one builder, the small pipeline. --wait stays for the pull request and prints the review.
• wayari take "what this change is for" is for work you do yourself. It cuts the branch and hands you a checkout, staffs nobody and spends nothing. Commit there, and wayari ship runs the same gate and opens the same pull request.
• A line whose first word isn't a verb is a goal: wayari fix the login button opens a channel the way start does. One word is never a goal, so a typo can't arm anything.

repos that aren't npm

The gate finds a repository's checks in its package.json scripts. Where there aren't any, it reads wayari.json at the root:

{
  "checks": {
    "typecheck": "mypy .",
    "tests": "pytest -q",
    "build": "make build"
  }
}

A declared command beats a script of the same name. It can't be used to skip a check: a check with no command is cannot-check, and cannot-check fails the gate.

channels

A channel is one goal on one repository, with one branch and at most one open pull request. Everything else hangs off it: the crew, the gate attempts, the cost and the record.

It's stored in two halves. What a teammate would want in code review (the goal, the pipeline state, the memory) is committed to your repo at .wayari/channels/<id>.json. Spend, file claims and live process state go to the data directory, because committing them would conflict on every heartbeat. Either half can be read without the other, so a second machine picks a channel up from the repo alone.

There's no delete. wayari archive ends the shifts and records how the channel ended, keeping the record, the worktrees and the branches. wayari clean gives back the disk of worktrees whose work has merged.

Two other kinds exist. #general is the feed channel Yari lives in, and it never ships. A hunt (--hunt) is a channel whose output is findings rather than a diff: its seat only reads, and it opens no pull request.

yari, the dispatcher

Yari is one long-lived agent in each repository's general channel. He talks with you, decides whether something is a channel yet, opens it, staffs it and starts the shifts. He writes no code: he launches in plan permission mode, so his CLI has no edit tool.

He may start a shift on his own. The hours and money you set are the authorisation, and the check that matters is at merge, which stays yours.

For a goal bigger than one channel he reads what the repository already knows, charts a map (a network of markdown questions under .wayari/maps/<name>/, at most twelve tickets in dependency order), and drafts a proposal: one channel per ticket, stacked along the map's edges, with seats, models and likely cost. Nothing opens until you approve it, and approving arms nothing.

wayari yari "the settings page needs a dark mode"
wayari yari                  # what he's holding for you
wayari propose --approve     # open what the proposal lists, in its order

the crew and roles

A channel's crew is its members. By default that's one builder; --members <n> asks for more, and they share one task and split it by claiming files. A role is standing instructions: a paragraph the agent's task file carries ahead of the task itself.

31 roles ship, in six archetypes. Each has a stance, and the stance is the rule that's enforced: a role that writes code can't be worn beside one that only reads, and a builder can't wear a reading role at all. An agent wears up to three roles, in precedence order.

wayari roles                    # every role, one line each
wayari role debugger            # one role whole
wayari start "the export drops rows past 10k" --role debugger --role test-writer

A role you write yourself, kept in roles.json in the data directory, has no stance and stacks with anything: Wayari won't guess one from your prose. Roles are recorded on the channel, so every restart wears them.

shifts

A shift is one agent's stretch of work in one channel. Every shift is a fresh session, never a resumed one, and what carries over is written down rather than remembered.

Before the agent types anything, Wayari commits a task file into its worktree at .wayari/tasks/<member>.md and records the starting commit. The opening prompt points at that file and adds five facts: claim a file before you edit it, say wayari done when finished, ask before anything irreversible, typecheck and build and tests must pass, and who else is on the same goal.

The prompt never mentions the pipeline, the budget or the stage. An agent that knows tests must pass writes passing code. One that knows how the gate works may try to argue with it.

The task file carries what the agent should know, each part derived fresh at every start: what failed last time, with the check's own output; what you said since the last shift; commands known to work here; a slice of the graph; your standing orders; and its roles.

• Claims. wayari claim <path> before editing. Two agents can't hold one file.
• Done. wayari done is checked against the diff since the shift's starting commit. A declaration with no real change, or with nothing but Wayari's checkpoint commits, is refused.
• Quiet. Eight minutes without a hook while holding uncommitted work, and Wayari commits it on the agent's behalf, with a subject line saying Wayari made it and nothing in it is known to pass.
• Stalled. Thirty minutes of silence and the shift is restarted with the same task, which spends an attempt; the fourth is a hold. An agent waiting on you (a permission prompt, an open question) is never stalled.
• Pushed. A new commit on a shift's branch reaches your remote within a minute. A failed push holds nothing and is tried again on the next minute.

stages and gates

A channel walks a pipeline of stages, and the gate is the only way from one stage to the next. Nothing advances a channel on an agent's say-so.

Small is the default. It drops stages and never a check: typecheck, build and tests all still run. ship has no gate, because what comes after it is your merge.

Your repo can add checks and never remove one. List them in package.json and each runs after the canonical three:

"wayari": { "gates": ["lint", "orphans"] }

The list is pinned when the channel opens and read again at gate time, and the gate takes the wider of the two, so a branch that deletes the block still runs every check. A listed script that doesn't exist is cannot-check, which fails.

When a check goes red, its captured output is committed into every member's task file under What failed last time, and fresh shifts start from it. Three red attempts at one stage and the channel holds for you, naming the failed checks. If your repo ships .claude/skills/on-red-<check>/SKILL.md, that skill rides in under the output.

A change that only touches docs, markdown or .wayari/ records typecheck, build and tests as unchanged rather than running them again, and an unchanged check is never shown as a pass. --full on gate or ship turns every shortcut off.

Gates queue: one runs at a time on your machine, two when the load is under half your cores. wayari gate runs the same gate against any checkout, with no channel and no agent, so you can watch what it does before you trust it with a night.

wayari gate .                  # every check the repo declares
wayari gate . --stage build    # one stage's gate, exactly as a channel ran it

the review seat

When the gate goes green, a reviewer reads the change before the pull request leaves draft. The reviewer is a member wearing the Reviewer role who took no shift on this channel, or a fresh one. The reviewer is never an author, and the code enforces it: a sign-off from one of the stage's authors is refused.

The review runs in a detached checkout at the exact commit the gate passed, and never follows a branch that moves. It reads the diff, each builder's task file and the README beside every changed directory, then files findings on path:line with a severity. Blocking and should-fix findings land on the pull request as inline comments. The reviewer can't edit: a review that leaves its checkout dirty is refused.

It runs on Yari's model unless your repo names another. The setting is read from your trunk, never from the branch under review, so a branch can't choose who reviews it:

"wayari": { "reviewer": { "agent": "codex", "model": "gpt-5.5" } }

A review never holds the ship. If the reviewer runs out of clock, stalls or loses its session, the pull request is readied anyway and the record says which happened. A reviewer's finding holds a merge grant (below) and never the gate, so read wayari review before you merge.

Adversarial mode. If your trunk's package.json names wayari.review.proof, an npm script that runs one test file, the reviewer is also asked to prove a finding with a new failing test. Wayari runs each test several times itself and calls it red only when every run fails on the same assertion. Nothing it writes is committed; the proof reaches the review read and the next builder's task.

Review rules are skills: .claude/skills/on-review-<name>/SKILL.md, with paths: prefixes, reaches the reviewer whenever a change touches those paths.

one pull request

Shipping is mechanical and no model is allowed near it. Wayari merges each member's branch into the channel branch, pushes, and opens one draft pull request with gh. It checks that gh is signed in before assembling anything; if it isn't, the channel holds with the fix, and every branch stays where it was.

The pull request body is the receipts, assembled from what the factory recorded: the goal, each builder's task, every gate attempt, what the reviewer found, which model did what, and the cost. A model may never write a measurement in it. The prose inputs have no field for a cost, a duration or an attempt count, so a model that was never shown the spend can't report it, and a sanitizer drops any sentence that tries.

The behaviour diff compares the base and the head on six surfaces: --help text, --json shapes, the declared checks, the skills, the MCP tools, and screens. It tells you what behaves differently and decides nothing about the ship.

Stacks. --after <channel> cuts a channel from another channel's branch. If that one hasn't opened its pull request yet, the new one waits armed and unstaffed, and starts itself when it does. When a follower's gate passes with every commit of its blocker inside it, the blocker counts as proved and skips its own gate. wayari graph gives the merge order: blockers first, then the smallest change.

Each pull request also carries one Wayari comment, What happened, rewritten in place from the channel's record after every notice.

approval and merge grants

Agents never merge. An irreversible act needs a person's approval every time, as a request and never a standing permission: to merge, delete a branch, run a migration, deploy or force push, an agent runs wayari request-act and waits, and nobody answering counts as no. Nothing in a role or a config can grant a standing right to any of them. Merge is the only irreversible act Wayari itself performs, and it happens one of two ways.

Your press. wayari merge <channel>, or the dock's merge sheet, which opens on the review read. It needs two independent greens: the channel's record says ready, which only a passing gate writes, and GitHub says the pull request is open, not a draft, free of conflicts, with every check it reports finished and passed. The merge is pinned to the commit you were shown through gh pr merge --match-head-commit, so a push that lands while you're reading makes GitHub refuse it.

wayari review <channel>
wayari merge <channel>
wayari merge <channel> --on-local-gate   # past checks GitHub never started
wayari merge --all-green                 # every ready one, in graph order

A grant. When you'll be away, wayari grant merge lets Wayari merge the channels you name, for up to eight hours. Only channels named at that moment are covered, so start first and grant second. Each minute it tries one covered pull request, and merges it only when all of this holds at the one commit it would merge:

• GitHub would merge it, and the gate is green again at GitHub's head.
• A review by someone who didn't write it ran at that same commit, and no blocking finding stands.
• Nothing the goal named is missing from the diff.
• The behaviour diff from the last ship is clean and was taken at that commit. A changed screen waits for your own merge.
• Every channel it stacks on has merged.

wayari grant merge <channel> <channel> --hours 8
wayari grant                 # the 9am page: what merged, what waits for you
wayari grant revoke --all

--hours is required and at most 8, refused rather than clamped. Grants survive a daemon restart. No MCP tool can give one, and over MCP wayari_merge runs only when the agent sets confirmed_by_person, its claim that you named that channel.

arming, clocks and money

Arming is what lets a channel's agents run unattended. wayari arm <channel> arms it until the work is done, or until a clock if you give --hours or --minutes, stopping at a dollar cap if you give --limit. A clock is always said out loud and never defaulted. wayari kill stops a channel's agents now; the worktrees, commits and branches survive.

wayari arm <channel> --hours 6 --limit 20
wayari kill <channel>
wayari plan max20            # which plan your agents are paid on

On a subscription a dollar figure is a fiction, because nobody is charged it. So a run's cost reads as a share of the rolling week's quota, and until you set wayari plan the quota isn't shown as a percentage at all. Dollars appear only on api, where they're real. A dollar cap needs a plan picked.

the graph

Every shift starts fresh, so each would otherwise pay to rediscover the same repository. The graph is what it gets instead, kept per repository in two stores.

The atlas is derived from git and the filesystem, with no model pass at any cadence; a test in the repo fails if anything in it imports an agent. Every field is a count, a path or a quotation. It cites each directory's README by path:line, knows what imports what, and holds markers: a failed check, a reviewer's finding or your own, pinned to a path.

The wayspace is a ledger of what work here proved: commands that passed a gate, with the commit; gate failures and the diff that fixed them; conventions that differ from a tool's default. Every entry carries a commit and the shift that learned it. Nothing in it is prose a model wrote about the code.

A shift's task file gets a slice of both, 1,600 characters between them. One shift in five gets neither, on purpose, so whether it helps is measured rather than assumed.

wayari atlas src/auth/session.ts    # what's pinned here, who touched it last
wayari findings                     # open findings, then gate verdicts
wayari finding src/auth/session.ts "refresh races the logout"

After every merge you press, a trunk gate runs the whole test suite at the merge commit in a throwaway checkout, behind any channel's gate. Red pins findings to the merged paths and marks the trunk red in wayari status until the next green.

the thread and standing orders

wayari thread is each repository's one record of what happened: channels opened, shifts, gate verdicts, holds, pull requests, merges, findings, notes, signed acts and your words to the crew, in order. It's folded on read from records that already exist, so it can't drift from them. The one thing it stores is a note.

wayari thread --since 2d
wayari thread --about src/billing/
wayari note "staging replays stripe webhooks out of order" \
  --path src/billing/webhook.ts

It reaches GitHub as the What happened comment on each pull request. A hunt with no pull request gets a Wayari thread issue instead, which "wayari": { "github": { "thread": false } } turns off. Both are redacted on the way out and never ping anyone.

Standing orders are what you'd otherwise say to every agent before every job. Say them once in .wayari/standing.md: every shift's task file carries them, and so do the instructions every MCP client gets when it connects.

wayari standing add "run the linter before you say done"
wayari standing

skills

A skill is a SKILL.md under .claude/skills/, in your repo or your home. Wayari serves skills to any agent as markdown, Codex included, which has no skills system of its own. They're pulled when needed and never pushed into the prompt.

wayari skills                            # name and one line each
wayari skill on-red-tests                # one whole, verbatim
wayari promote <channel> --as flaky-auth-tests

Two kinds are wired into the factory. on-red-<check> rides into the task file when that check goes red. on-review-<name> reaches the reviewer when a change touches its paths. Both are read at the trunk's commit, never from the branch being built.

wayari promote drafts a skill from what a channel taught: the goal, the task, the builder's doubts and the red checks, under fixed headings, ending on Do this next time, which stays empty until you write it. It's committed on the channel branch, so it arrives in the same pull request and gets the same read. No model writes any of it.

design with its eyes open

For changes to how something looks, agents get a way to see their own work, and a reviewer that judges it against taste you wrote down.

Taste. wayari taste prints what a design is judged by: Wayari's Never rules (no-em-dash, no-eyebrow, headline-two-lines, no-mascot-slop, no-landing-slop), your own in the data directory, and your repository's .wayari/taste.md, with its Look sections for the paths in play. A repository can add rules and can't switch one off.

Look. wayari look renders the checkout you're standing in, uncommitted edits included, and prints one PNG path per screen. A screen is one route of one app at one width, keyed <app>:<route>@<width> and declared in package.json under wayari.screens; widths default to 1440 and 390. It needs playwright-core in the repo and a Chromium on the machine, and never downloads either.

wayari look site:pricing --width 390
wayari taste --paths src/app/pricing

The Critic. When a change touches a Look path from your taste file, or a .css, .tsx, .jsx, .html, .svg or .mdx file under a declared screen's directory, a second reading seat sits beside the reviewer: the Critic, who wrote none of it. It looks at 390 and 1440 before filing anything, and every design finding has to cite a Never rule (weighed as blocking) or a reference (should-fix). A finding that cites nothing is refused.

Screens in the behaviour diff. Declared screens are captured at the base and the head, and the pull request shows the pictures. A changed screen refuses a merge grant, so a visual change always waits for your own merge.

connect once

wayari connect

connect registers wayari mcp with every coding agent it finds, by running that agent's own add command rather than editing its settings file. Claude Code is registered at user scope, so Wayari is there in every project; a hand-typed claude mcp add defaults to the directory you ran it in, which is the mistake this verb exists to avoid. Codex is registered globally. An agent that isn't installed is skipped.

Then ask in your own words, in the window you already have open: "use wayari to fix the login button", or "what did wayari do last night?"

by hand, and cursor

claude mcp add --scope user wayari -- wayari mcp
codex mcp add wayari -- wayari mcp

Cursor, or any client that speaks MCP over stdio, runs the command wayari mcp. In Cursor that's an entry in ~/.cursor/mcp.json:

{ "mcpServers": { "wayari": { "command": "wayari", "args": ["mcp"] } } }

what the agent gets

43 tools, one per verb, named wayari_<verb>: wayari_start, wayari_status, wayari_review, wayari_merge and the rest. wayari mcp --tools prints the list. Each tool runs the same wayari the terminal does, so the two can't disagree.

Some verbs aren't tools, on purpose. serve, attach, stop and uninstall are yours to run, because the daemon is yours. grant isn't one either: an agent's word that you said so isn't enough for eight hours of unattended merges. wayari_merge refuses unless the agent sets confirmed_by_person, and the server's instructions say to set it only when you named the channel.

When a client connects, the server hands its agent instructions: when handing work over makes sense and when doing it directly is right, to read status first, never to invent a clock, and to show you the review as written rather than summarise it. Your standing orders are appended to them.

the json envelope

Every verb answers --json in one envelope, green or red, so an agent parses one shape:

{
  "status": "action_required",
  "reason": "no-lead",
  "message": "the sentence the terminal prints",
  "data": {},
  "next": ["wayari lead opus"]
}

status is ok, action_required or error. reason is a code word such as needs-daemon, no-lead, shift-open or held, and next lists the commands that move things forward. Keep --json last on the line. review, status and doctor also carry markdown, the same answer laid out as a document, which is what an MCP client shows you.

inside an agent's own session

Inside a shift's pane, wayari is a shim with three verbs of its own, for the agent rather than for you: wayari claim <path> before editing a file, wayari done when the work is finished (committing isn't finishing), and wayari request-act to ask a person for an irreversible act.

what's counted

Wayari's launch counter sends seven events, each once in the life of an install: the first, second, third, fifth and tenth launch, and an open after 7 days and after 30. A machine that launches two hundred times sends seven requests, ever.

Each carries the app's version, your operating system, a random id made on your machine, the launch count and the days since the first launch. Nothing about your code, repositories, folders or prompts. They go to PostHog's EU cloud with person profiles off. The counter lives in the desktop app; the dock and the wayari command don't call it.

turning it off

export DO_NOT_TRACK=1
# or
export WAYARI_TELEMETRY=0

Set DO_NOT_TRACK=1 or WAYARI_TELEMETRY=0 and nothing is sent, and no id is ever made. The launch count and the date of the first launch are still written locally, because the trial clock reads them.

what else talks to the network

• Your licence key, once you have one, is checked offline against a signature. The app and the command ask wayari.com for a renewed key when they start and every twelve hours, and that request names your subscription.
• Updates. The dock checks wayari.com/downloads/dock/ for a new version at launch and once a day.
• GitHub, through your own gh: the pull request, the reviewer's inline comments, the What happened comment and, for a hunt, the thread issue. Every line is redacted on the way out.
• wayari feedback opens a prefilled issue with the version, platform and the doctor's verdicts, never their details. Whether to submit it is up to you.

On disk, wayari serve adds status hooks to ~/.claude/settings.json so it hears an agent's state without reading its screen, and leaves your own hooks alone. wayari uninstall takes them out, and --data removes the data directory too. What wayari.com keeps when you visit or buy is on the privacy page.