# 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](https://ouijit.com/docs/harnesses/) 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](https://ouijit.com/docs/hooks/#hook-environment) 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 ""` (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](https://ouijit.com/docs/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/.md`, for example [/docs/cli.md](https://ouijit.com/docs/cli.md). - **Full docs in one file**. [ouijit.com/llms-full.txt](https://ouijit.com/llms-full.txt) concatenates every page. - **Index with summaries**. [ouijit.com/llms.txt](https://ouijit.com/llms.txt) lists each page with a one-line summary.