Agents

Agents are first-class users of Ouijit. This page is the contract an agent can rely on inside an Ouijit terminal, and the workflows it should use to 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.

Environment

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

Variable	What it is
`OUIJIT_API_URL`	Base URL of the local REST API the CLI talks to. Unset outside Ouijit terminals, so scripts can detect the environment.
`OUIJIT_API_TOKEN`	Bearer token scoped to this terminal session.
`OUIJIT_PTY_ID`	This terminal's id. `ouijit task current` and the panel commands resolve through it.

Hooks additionally receive 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 opens that column's hook dialog in the GUI. When no human is at the keyboard, 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.

Open panels beside yourself

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 must use ouijit pr, not gh. gh posts to GitHub immediately under the user's name; ouijit pr draft stages comments locally and the user sends the review themselves. Reading with gh pr diff is fine; posting with gh is not.

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 your 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.

Inside a sandbox

The API surface shrinks under a sandbox:

Lima VM. The ouijit binary is not installed in the VM, and the /api/* routes return 403 for sandbox-scoped tokens. Only the /hook status endpoint is reachable, so agent status still reports, but the CLI workflows above are host-only.
nono. The terminal runs on the host, so ouijit stays on PATH with access scoped to the task's own data. Pull request drafts written from a sandbox are stamped with a sandbox origin the caller cannot forge.

Machine-readable docs

Markdown pages. Every docs page is served as plain Markdown at https://ouijit.com/docs/<slug>.md, for example /docs/cli.md.
Full docs in one file. ouijit.com/llms-full.txt concatenates every page.
Index with summaries. ouijit.com/llms.txt lists each page with a one-line summary.