Getting started

Ouijit is a task and terminal manager for running coding agents in parallel. Each task gets its own git worktree and terminal, lifecycle hooks launch your agent with the right context, and a session-aware CLI lets agents drive the board back. From download to an agent working on your first task takes about a minute.

Reading this from inside an Ouijit terminal? You're an agent with ouijit on PATH and its reference in your system prompt. The Agents page is your contract, and every page here is plain Markdown at /docs/<slug>.md.

Requirements

  • macOS 13+ (Apple Silicon or Intel) or Linux x64
  • Git 2.20+ on PATH
  • An agent CLI you already use: claude, codex, pi, or opencode

The downloads are self-contained. Nothing else is required to run the app.

Download and install

On macOS, open the DMG and drag Ouijit.app to Applications. On Linux, unzip the archive and put the binary somewhere on your PATH.

Your first agent task

  1. Add a project. Click the + button in the sidebar and open a folder, create one, or clone from GitHub. If the folder isn't a git repository yet, Ouijit offers to run git init in place.
  2. Describe the task. Press ⌘N (Ctrl+N on Linux), give the task a name, and write the prompt you'd give your agent. Paste in screenshots if you have them.
  3. Drag the card to In Progress. Ouijit creates a branch and an isolated worktree, opens a terminal in it, and asks what to run. Enter: 
    claude "$OUIJIT_TASK_DESCRIPTION"
    Save remembers it as the project's start hook, so from now on every card you drag starts an agent on its own copy of the repo.
  4. Watch it work. The card shows whether the agent is thinking or waiting on you, and Ouijit chimes when a turn ends. Press ⌘D to review the diff, leave notes on changed lines, and drag the card to In Review when it's ready.

Repeat from step two, in parallel: each task runs in its own worktree, so agents never trip over each other.

Where to go next

  • Command palette: jump between everything with ⌘K.
  • Panels: put the agent's plan, its dev server, and a runner beside its terminal.
  • Sandbox: run a task in a Lima VM or under nono when you don't trust the code.
  • Pull requests: review and merge without leaving Ouijit.

Build from source

Building needs Node.js 20+ (the repo pins 22) and C/C++ build tools for the native modules (better-sqlite3, node-pty, koffi):

  • macOS: xcode-select --install
  • Linux: sudo apt install build-essential python3 (Debian/Ubuntu)
git clone https://github.com/ouijit/ouijit.git
cd ouijit
npm install
npm start

Projects folder

New projects are created in ~/Ouijit/projects by default. Change it under App Settings → Projects. If projects still live in the old folder, Ouijit asks whether to move them (tasks, hooks, and settings stay attached), forget them (files stay on disk), or leave them where they are.

Check your environment

Ouijit checks your environment at startup: git, the agent CLIs (claude, codex, pi, opencode), and the tools behind optional features (gh, Lima, nono). The Help & setup dialog shows each result, and dialogs that need a missing tool say so inline.

Update Ouijit

Ouijit checks for updates at launch and hourly. On macOS the update downloads in the background and a dialog offers to restart when it is ready. On Linux a notice links to the release page. After an update, a What's New dialog shows that version's release notes once. Turn automatic checks off under App Settings → Updates.