For agents

What an agent can rely on inside an Ouijit terminal, and how it should drive the app.

What an agent receives

Every supported harness gets the ouijit CLI reference appended to its system prompt automatically, from ~/.config/Ouijit/ouijit-cli-reference.md. It covers the commands in these docs plus behavioral notes: JSON output on stdout, errors as {"error": "..."} on stderr with a non-zero exit, and the flags for headless status changes.

In a sandboxed terminal the reference opens with a short section of its own. It says the terminal is sandboxed, what Ouijit lets it write, and the project's CLI access level. It tells the agent to ask with ouijit ask run when the sandbox blocks a command, rather than work around it. What else the sandbox allows is up to its profile or launcher, so the section doesn't list it.

Environment

Every Ouijit terminal has these set. An agent can read them directly:

VariableWhat it is
OUIJIT_API_URLBase URL of the local REST API the CLI talks to. Unset outside Ouijit terminals, so scripts can detect the environment.
OUIJIT_API_TOKENBearer token scoped to this terminal session.
OUIJIT_PTY_IDThis terminal's id. Every command that takes a [pty-id] defaults to it.

Hooks also get OUIJIT_TASK_* context.

Drive the board

An agent working a task should resolve its own task first, then advance it when the work is committed:

TASK=$(ouijit task current | jq -r .taskNumber)
ouijit task set-status "$TASK" in_review --skip-hook

By default a status change whose hook would ask first waits for the user. To run without waiting, pass --run-hook (run the configured hook immediately), --skip-hook (no hook), or --hook-command "<cmd>" (a one-off command). The same flags apply to task start and task create-and-start. The hook runs where its sandbox setting says, or the project default, unless --sandbox host|nono|custom says otherwise. nono is Ouijit's sandbox.

Open panels beside the terminal

An agent can put its plan or its running app next to its own terminal. Both commands default to the current terminal via OUIJIT_PTY_ID:

ouijit markdown add ./plan.md
ouijit preview add http://localhost:3000

Review without posting

For anything that belongs to a pull request review, agents default to ouijit pr over gh. gh posts to GitHub the moment it runs, under the user's own account. ouijit pr draft stages comments locally, and the user sends the review themselves. Reading with gh pr diff is always fine, and a gh write the user asks for by name, such as gh pr create, still goes through, as them.

PR=$(ouijit task current | jq .githubPrNumber)
gh pr diff $PR                                # read it
ouijit pr draft add $PR --file src/api.ts --line 88 \
  --origin claude --body "this can throw when the token is missing"

Pass --origin with the agent's name so the user can tell agent comments apart before sending, and --body - to read multi-line bodies from stdin. Anchor each comment to a line that appears as an added line in the diff, by its new-file line number. GitHub rejects the whole review at submit time if any comment points outside the diff.

A Linear comment works the same way, and for the same reason. Nothing an agent runs moves an issue. That is a control on the issue, pressed by someone looking at it.

ISSUE=$(ouijit task current | jq -r .linearIssueIdentifier)
ouijit linear view $ISSUE                     # read it
ouijit linear draft add $ISSUE --origin claude \
  --body "the retry loop drops the last error"

Inside a sandbox

Inside a sandbox, ouijit can do what the project's Ouijit CLI access allows. By default it can read its own task and diff notes, stage comments, and print links. On its own terminal it can read the screen, set tags, read panels and open markdown from its worktree. At Its own task it can also move, rename and describe its task. At Everything it can do what a host terminal can. At any level it can ask the user to run a command outside the sandbox, which runs only when they press Run. A hook that would run on the host waits for the user even with --run-hook. Pull request drafts written from a sandbox are stamped with a sandbox origin the caller cannot forge. Under the Custom sandbox, whether ouijit is reachable at all is up to the launcher.

Machine-readable docs