Agent setup

Agent setup is the recommended way to get started. Ask your coding agent to install Yoke and guide you through the choices; you approve changes and complete browser sign-in yourself. Start with Get started for the short guide.

The details below are for the agent running setup. In agent mode, setup asks one question at a time as JSON lines. The agent shows each question to the person and answers it with a command.

When agent mode runs

Without a terminal, yoke setup starts in agent mode by itself. The public installer does the same: an agent's curl … | sh installs Yoke, then runs yoke setup --agent --post-install and prints the first question.
yoke setup --agent forces agent mode, even in a terminal.
yoke setup --tui forces the full-screen wizard; without a terminal it refuses with setup_tui_requires_terminal.
--non-interactive and --json keep the one-shot flag path, which takes every answer as a flag.

The loop

Run yoke setup --agent.
Read the last line on stdout. It is one JSON object.
When state is question, show the person question, detail and the answers labels. Follow guidance. Ask the person; never guess a choice that is theirs to make.
Run the line's answer_command with the chosen value, for example yoke setup --agent --answer project.mode=machine-only.
Repeat until state is done, then show the person detail, install_health in full and the next steps in order.

Setup first asks project.mode (where the code lives), before sign-in and GitHub connection, and saves that answer. The chosen create, existing-folder or clone path runs after connection; private-clone screens still need GitHub. A CLI project preset or saved checkout skips this early question; choosing another project in a saved or restored project picker asks it again. The first question also explains that setup disables command approval and sandbox restrictions in installed agent tools across the machine, and that workers bypass approval (Codex workers also bypass sandbox and CLI hook trust). These changes are required; there is no separate permission question.

When setup runs outside the project folder, install_health.ready covers install checks and reports “new project session verification pending” separately. Open a new chat in the project folder and run yoke doctor run --session to verify its session hooks; that pending step does not make installation fail. Setup run inside the project folder includes session hook registration in install readiness.

Answers are saved by question key, so every call resumes where setup stopped. Steps that change the machine record what they did in the same setup file: the Project step's clone, a saved connection, a backup restore, an opened git installer, and what Apply created. Later calls read those records first, so the next printed answer_command is always the next answer accepted. Setup never asks to resume its own clone, approve its own connection again, or restore the same backup twice. A bare yoke setup --agent repeats the waiting question. Human progress and wait notices go to stderr; stdout carries only the JSON lines.

{"setup": "agent", "version": 1, "state": "question", "step": "project",
 "key": "project.mode", "question": "Set up a project.", "detail": [],
 "answers": [{"value": "machine-only", "label": "Don't set up a project now", "description": "just the machine"}],
 "input": null, "fields": [], "secret": false, "human": null,
 "guidance": "…", "answer_command": "/Users/me/.local/bin/yoke setup --agent --answer project.mode=<value>"}

answer_command names the running yoke by absolute path, so it works before the shell reloads PATH.

Answer shapes

A choice: --answer KEY=VALUE, where VALUE is one of answers[].value.
A typed value: input is set. --answer KEY=TEXT runs the screen's own check; an empty value takes input.default.
A form: fields lists KEY.FIELD keys. Give one --answer per field in the same call, plus --answer KEY=VALUE when the form also has answers. An omitted field takes its default. If the form has answers, a different value redraws the form first, so answer its fields in the next call.

Only the waiting question and its fields are accepted. The first call may answer the first question.

Browser steps

A line with state browser carries human.url, human.user_code and human.instructions. Setup never opens a browser in agent mode.

As the last line, a browser line is a step waiting on approval: machine approval (key connect.hosted_machine_approval) or GitHub sign-in (key github.machine). The call has ended. The agent approves machine and GitHub codes; only password entry goes to a person. Open the link in a browser already signed in and approve the code, or approve a Yoke machine with yoke machines approve CODE on a machine already connected. When a password is needed, ask the person for just that entry. When approval is done, run the line's answer_command. The same browser line again means approval has not finished. The code lapses after wait.max_seconds. A lapsed or failed machine approval asks connect.hosted_machine_error on every call until it is answered; retry starts one fresh approval. guidance names how to choose differently instead.

Earlier in the output, a browser line is a link to open on the way, such as the GitHub App installation page; the last line says what comes next.

Device codes and tokens never appear in any line. A pending step's short-lived device code waits in the private (0600) setup file until the step completes, fails or lapses.

Secrets

A question with "secret": true never takes its value through --answer. Take the route its guidance names: for a team-server token, answer the token source file and give the token file's path; hosting credentials can be skipped for now. Or ask the person to finish that step with yoke setup --tui.

Presets, Apply and starting over

Setup flags given to the first agent call (for example --local or --yes) are presets, like wizard defaults. Later calls may repeat them or leave them out. Changed project flags (such as --project-mode, --checkout or --remote-url) keep sign-in answers, the confirmed folder and item prefix; other project answers are asked again for the new path. Changing any other flag refuses with setup_agent_flags_changed before setup runs, leaves the setup file unchanged and names the saved waiting key. Rerun without changed flags to see that question. --yes answers the review question with apply.

Answering review.confirm with apply writes the setup and returns done. A failed Apply returns state failed with reason setup_apply_failed, the run report path and the failure question; show the person the cause, then answer it (resume, when offered, continues the same run). Answering a cancel choice returns done with "cancelled": true and deletes the saved answers. yoke setup --agent --discard deletes an in-progress agent setup.

Exit codes, refusals and failures

Exit 0 means the last line is question, browser or done; 1 means failed; 2 means refused. Every refusal and failure carries reason and recovery. A refusal saves no answer. Answer refusals repeat the question setup waits at now, which can be an earlier one when machine state changed, and that question's printed answer_command is the next answer accepted. If setup already requested a browser approval before a later answer refusal, it keeps that pending approval in the private setup file so a later call can collect it.

reason	what to do
`setup_answer_not_current`	answer the repeated question by its key
`setup_answer_not_allowed`	use one of `answers[].value`
`setup_answer_invalid`	correct the value; `recovery` says why
`setup_secret_answer_refused`	take the question's non-secret route
`setup_agent_flags_changed`	non-project flags changed; rerun without changed flags, or `--discard`
`setup_agent_busy`	wait for the other `yoke setup --agent` call
`setup_agent_store_unreadable`	run `yoke setup --agent --discard`
`setup_tui_requires_terminal`	run in a terminal, or use `--agent`
`setup_step_failed` (failed)	fix the named cause, then run `yoke setup --agent`
`setup_apply_failed` (failed)	answer the failure question shown with it

Optional issue mirroring

When GitHub issue mirroring would help this project, explain that it copies backlog items and tasks into the repository’s Issues and offer a separate opt-in after setup. Connecting GitHub or approving setup leaves sync off. Enable only after the person agrees; otherwise continue with sync off. Use the project setting recipe to check permissions and enable or change it later. Do not add a wizard question or ask this during machine-only or no-GitHub setup.

After setup

For Yoke’s core words and first actions, read Concepts.

done lists the next steps. When shell files changed, the first one opens a new terminal. When this session already runs in the project folder, the last step is a readiness check here:

yoke doctor run --session

It checks three things about this session only: it is registered, its harness CLI is signed in, and its harness runs yoke without approval prompts. Other installed harnesses do not block it. Each failed check names one next step: a new session, a restart, a sign-in such as claude auth login, or a hook approval. Give the person that step, then rerun the check. When every check passes, follow the returned next_action command and deeper home.

Whether the session that ran setup needs replacing depends on its harness. Claude Code picks up the new hooks and registers on the next prompt, so run the check there without a restart. Codex and Cursor do not load hooks installed during a session, so its session-hook-registration check fails: open a new session in the project folder and run the check there. Do not ask for a restart the check does not name.

When this session runs elsewhere, done says to open Claude Code, Codex or Cursor in the project folder, run the same check there, then follow next_action. Yoke never opens a new session for the person. A machine-only setup adds a project later through another yoke setup --agent.

yoke connect --json and yoke github connect --json stay available as standalone commands for one sign-in outside setup.

Setup facts and next action

yoke onboard checklist get --json

Read run.next_action.command and run.next_action.home for the next required repair or first-work action. run.setup_readiness describes current prerequisites; optional deferred, not-needed and unknown capabilities do not force setup. The human reply leads with Next and Setup; install, refresh, register and checklist init reuse the summary. JSON keeps next_action structured; setup_summary retains setup diagnostics in install, refresh and register replies.

Orientation shows this machine's facts alongside shared project choices once per session, then suppresses settled setup after the first item reaches done. Outside a project it shows only machine facts and a public guide. Under budget pressure, Setup: run yoke onboard checklist get points to the complete read. A failed read names its reason and recovery. Follow that repair, then retry; unknown never means ready. Actors without project-install permission see no setup suggestion. An older server without next_action supplies no guessed Next line.