CLI

Every agent running in Ouijit gets the ouijit CLI for driving Ouijit itself. An agent can file tasks, move its own card, open panels and stage review comments from the shell.

Where it lives

The ouijit command is auto-installed into every terminal Ouijit opens, host and sandboxed alike. It talks to the running app over a localhost API authenticated by a per-session token, so it only works from inside an Ouijit terminal.

Output format

Every successful command writes a single JSON value to stdout and exits 0. Errors write {"error": "..."} to stderr and exit non-zero. Pipe to jq to extract fields:

ouijit task list | jq '.[] | select(.status == "in_progress") | .name'

Project detection

Inside an Ouijit terminal, commands act on that terminal's project, even after the shell has moved into another repository. Elsewhere the CLI walks up from your current directory to the nearest git root, following a worktree back to its main repository. Override either with --project <path>.

Tasks

Statuses are todo, in_progress, in_review, and done.

ouijit task list                              # array of tasks
ouijit task get 5                             # single task
ouijit task current                           # task owning this terminal
ouijit task create "Fix login bug"
ouijit task create "Refactor auth" --prompt "Extract middleware"
ouijit task start 5                           # creates worktree, sets in_progress
ouijit task start 5 --branch custom-name
ouijit task start 5 --run-hook                # run the configured start hook, no dialog
ouijit task start 5 --skip-hook               # spawn the terminal, run no hook
ouijit task start 5 --hook-command "claude"   # one-off command instead of the configured hook
ouijit task start 5 --run-hook --sandbox custom # run it in a sandbox other than the hook's own
ouijit task create-and-start "Add 2FA"        # create + start in one step
ouijit task create-and-start "Add 2FA" --prompt "..." --branch custom --skip-hook
ouijit task spawn "Add 2FA"                   # alias for create-and-start
ouijit task set-status 5 in_review            # the review hook waits for you by default
ouijit task set-status 5 in_review --run-hook # run the review hook, no dialog
ouijit task set-status 5 in_review --skip-hook
ouijit task set-status 5 done --hook-command "npm run deploy"
ouijit task bulk-set-status done 5 6 7        # set status on many in parallel
ouijit task set-name 5 "Better name"
ouijit task set-description 5 "More detail"
ouijit task set-merge-target 5 develop
ouijit task trash 5                           # worktree goes to the system trash

--run-hook, --skip-hook, and --hook-command are mutually exclusive. By default a status change whose hook would ask first waits for you, so an agent never puts a dialog over what you're doing. These flags run without waiting for you. They apply to task start and create-and-start (the start hook) and to set-status into in_progress, in_review or done (the continue, review and done hooks). bulk-set-status takes the same flags. Setting status to todo runs no hook and rejects these flags.

--sandbox host|nono|custom overrides the hook's own sandbox setting for that run, with or without the flags above. When the hook waits for you, the dialog preselects it.

ouijit task current resolves the task that owns the current terminal, through the OUIJIT_PTY_ID variable Ouijit sets on every spawn:

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

Hooks

Manage the hooks. Hook types are start, continue, review and done.

ouijit hook list
ouijit hook get start
ouijit hook set start --name "Install & agent" --command 'npm install && claude "$OUIJIT_TASK_DESCRIPTION"'
ouijit hook set continue --name "Agent" --command "claude -c" --sandbox custom
ouijit hook delete done

--sandbox host|nono|custom sets where the hook always runs. nono is Ouijit's sandbox. hook set replaces the whole hook, so leaving --sandbox out makes the hook follow the project default.

Sandbox command

The launcher for the Custom sandbox backend. Host terminals only. A sandboxed session gets 403.

ouijit sandbox-command get
ouijit sandbox-command set "$HOME/.local/bin/ouijit-sandbox --strict"
ouijit sandbox-command clear

Terminals

See every open terminal, read what's on its screen, open and close terminals, and paste a message into one for you to send. A terminal opened here goes behind the one on screen, and a paste never presses Enter. From a sandbox only terminal read works, on its own terminal.

ouijit terminal list                          # every project's terminals, with task, sandbox and agent status
ouijit terminal read pty_abc123 --lines 40    # its screen and recent scrollback, as text
ouijit terminal open --task 5                 # a shell in a started task's worktree
ouijit terminal open --task 5 --resume        # running the continue hook
ouijit terminal open                          # a shell in the project
ouijit terminal paste pty_abc123 "run the tests again"
ouijit terminal paste pty_abc123 - < followup.md
ouijit terminal close pty_abc123

A multi-line paste is refused where the program in that terminal would read each newline as Enter.

Diff notes

The notes you've left on a worktree's diff, so an agent can read them itself. Without --task it reads the current terminal's worktree, which works from a sandbox too.

ouijit diff notes
ouijit diff notes --task 5
ouijit diff open                              # show this terminal's diff panel
ouijit diff close

An agent can put a link in its reply that takes you somewhere in Ouijit: a line of the diff, a panel, a pull request, another task. Click it in the terminal to go there. A link only navigates. It never runs anything.

ouijit link diff src/auth/session.ts:88       # → {"url": "ouijit://horizon/tasks/14/diff/src/auth/session.ts:88"}
ouijit link task 14
ouijit link terminal pty_abc123
ouijit link panel panel-3fa9
ouijit link pr 212
ouijit link issue ENG-231                     # or a GitHub issue number
ouijit link board
ouijit link project

Waiting for you

An agent can leave two things for you to decide: a command it asks to run, and a task move whose hook would open a dialog. Either opens over its terminal's card, and stays until you answer it. While you're looking elsewhere it also shows as a toast you can run from or close. A closed toast leaves it waiting on the card.

Asking you to run something

An agent can ask you to run a command on your computer, outside its sandbox. The ask waits for you on its terminal's card. It shows the exact command, where it runs and the script file it runs, then Run or Decline. Nothing runs until you press Run. A script the command runs, from the agent's worktree or a temp folder, is shown in full, and the copy you read is what runs. The command runs in a runner panel on the agent's terminal, without a pager. With --wait the agent gets the exit code and output back. Run privately and the agent gets only the exit code. It can't read that runner's output.

ouijit ask run -m "Needs the keychain" -- npm run release:sign
ouijit ask run --wait -- ./scripts/migrate.sh --dry-run
ouijit ask script "Dev server"                # a project script, by id or name

Tags

Tag a terminal to group and filter it. A terminal can carry several, and the pty id defaults to the current terminal. A sandboxed session can tag its own terminal.

ouijit tag list                               # tags on open terminals, and which carry each
ouijit tag get                                # this terminal's tags
ouijit tag add review
ouijit tag add review pty_abc123              # explicit pty id
ouijit tag remove review
ouijit tag clear                              # removes all of them

Scripts

Scripts are saved shell commands that show up in the panel menu and the CLI. Unlike hooks, they don't fire on lifecycle events.

ouijit script list
ouijit script set --name "Lint" --command "npm run lint"
ouijit script set --name "Dev" --command "npm run dev" --restart-if-running
ouijit script run Lint                        # by name
ouijit script run <id>                        # by id
ouijit script run Tests --task 5              # run inside task 5's worktree
ouijit script delete <id>

script run streams the command's output through your terminal and exits with the command's exit code. script set upserts by name, so re-running with the same --name updates that script.

Pull requests

Inspect pull requests and stage review drafts. Drafts stay local until the user sends the review from the app.

ouijit pr list                                # open PRs, grouped review/yours/others
ouijit pr view 42                             # one PR with threads, timeline, checks
ouijit pr link 42 --task 5                    # link a PR to a task
ouijit pr draft list 42
ouijit pr draft add 42 --file src/api.ts --line 88 --body "typo" --origin claude
ouijit pr draft add 42 --file src/api.ts --line 88 --body -   # body from stdin
ouijit pr draft add 42 --file src/api.ts --start-line 80 --line 88 --body "range"
ouijit pr draft discard 42 <draft-id>
ouijit pr lens get 42                         # the lens shown in the Code pane
ouijit pr lens set 42 --body -                # grouping as JSON on stdin
ouijit pr lens clear 42

--body - reads the body from stdin, the safe path for multi-line text. --origin names the author shown beside the draft. --side defaults to RIGHT, the new file. Anchor comments to lines that appear as added lines in the diff.

pr lens set takes a lens an agent wrote itself: a head sha and the parts of the change, each naming paths and new-file line ranges. A range touching any line of a hunk claims the whole hunk, so approximate ranges are fine, and omitting a file's ranges claims all of it. Run ouijit pr lens set --help for the shape.

Issues

Link an issue to a task: a GitHub issue by its number, or a Linear issue by its identifier.

ouijit issue link 17 --task 5                 # a GitHub issue
ouijit issue link ENG-214 --task 5            # a Linear issue

Linear issues

Read the Linear issues this project is scoped to and stage a comment. Comments stay local until the user sends them from the app. Nothing here moves an issue. That is a control on the issue itself.

ouijit linear list                            # this project's issues, in the panel's groups
ouijit linear view ENG-214                    # one issue with its comments and states
ouijit linear draft list ENG-214
ouijit linear draft add ENG-214 --body "the retry loop drops the last error" --origin claude
ouijit linear draft add ENG-214 --body -      # body from stdin
ouijit linear draft discard ENG-214 <draft-id>

A task created from an issue carries its identifier, so ouijit task current | jq .linearIssueIdentifier is the issue an agent is working on.

Markdown panels

Open markdown files as panels on a terminal. The pty id defaults to the current terminal.

ouijit markdown add ./plan.md                 # uses current OUIJIT_PTY_ID
ouijit markdown add ./plan.md pty_abc123      # explicit pty id
ouijit markdown list
ouijit markdown remove ./plan.md

Web preview panels

ouijit preview add http://localhost:3000      # uses current OUIJIT_PTY_ID
ouijit preview add http://localhost:3000 pty_abc123
ouijit preview list
ouijit preview remove http://localhost:3000

Runners

Run a project script in a runner panel beside a terminal, as the + menu does, in the project's default sandbox.

ouijit runner add "Dev server"                # by id or name
ouijit runner list
ouijit runner remove "Dev server"             # stops the script

Panels

List every panel on a terminal, read one, and bring one to the front.

ouijit panel list                             # ids, kinds, labels, which is active
ouijit panel read panel-3fa9 --lines 40       # a runner's screen, status and exit code
ouijit panel focus panel-3fa9
ouijit panel focus terminal                   # back to the terminal itself

Themes

Themes are global, not project-scoped.

ouijit theme list                             # preference, presets, custom themes
ouijit theme use dracula
ouijit theme use system
ouijit theme save '{"id":"my-theme","name":"My Theme","base":"dark","tokens":{"--color-accent":"#ff2d55"}}'
ouijit theme save --file my-theme.json
ouijit theme delete my-theme

Projects

ouijit project list                           # every project registered with the app

Environment variables

Ouijit sets these on every terminal it spawns:

VariableWhat it is
OUIJIT_API_URLBase URL for the local REST API the CLI talks to.
OUIJIT_API_TOKENBearer token scoped to this terminal session.
OUIJIT_PTY_IDUnique id for this terminal session. Every command that takes a [pty-id] defaults to it.

Hooks get task context on top of these. See Hooks → Hook environment for the OUIJIT_TASK_* variables.