FAQ
Common questions about Ouijit, gathered in one place.
What is Ouijit?
Ouijit is a desktop app for project management with integrated terminal sessions, git worktree-based task isolation, and CLI agent support. It runs on macOS and Linux, is free and open source, and requires no account or sign-in.
What does Ouijit do?
Ouijit is a customizable task and terminal session manager that integrates with agent CLIs and TUIs like Claude Code via lifecycle hooks, scripts, and a session-aware CLI. It offers basic comforts for agentic development like live agent status with notifications, automatic worktree management for parallel workstreams, and VM sandboxing for untrusted code.
What operating systems does Ouijit support?
macOS 13 (Ventura) or later, and Linux x64. Builds are distributed as zipped binaries on the GitHub releases page.
Is Ouijit free?
Yes. Ouijit is free and open source under the AGPL-3.0 license. No account, no sign-in, no paid tier.
Which CLI agents does Ouijit integrate with?
Any CLI tool runs in an Ouijit terminal. Claude Code, Codex, and Pi additionally get live status indicators (thinking / idle) on the terminal card and receive an injected Ouijit CLI reference in their system prompt, so they can create tasks, flip statuses, and update plans from the shell.
How does Ouijit isolate work between tasks?
Every task gets its own git worktree under ~/Ouijit/worktrees/, on its own branch. Worktrees are created via Copy-on-Write cloning (APFS on macOS, reflinks on Linux) so creation is nearly instant regardless of repo size. Each project picks between Quick start (gitignored files copied across) and Clean checkout (tracked files only) in Project Settings.
What does the VM sandbox do?
Sandboxed terminals run inside a Lima Linux VM in a parallel git worktree that contains only tracked files. The user worktree is never mounted. .git is mounted with hooks/, config, and packed-refs read-only. Agent commits land on a child branch s/<your-branch>, and a host watcher fast-forwards them back onto your branch.
Can the agent inside a sandbox terminal use the Ouijit CLI?
No. The ouijit binary is not installed inside the sandbox VM, and the /api/* routes return 403 for sandbox-scoped tokens. Only the /hook endpoint accepts them, which the agent uses to report status back to the host.
Where do I download Ouijit?
From ouijit.com or the GitHub releases page: github.com/ouijit/ouijit/releases/latest. Unzip the archive and move Ouijit.app to your Applications folder on macOS, or extract the binary to a directory on your PATH on Linux.
How do I build Ouijit from source?
Clone github.com/ouijit/ouijit, run npm install, and then npm start. Requires Node.js 20+ and C/C++ build tools for native modules (better-sqlite3, node-pty, koffi). On macOS run xcode-select --install; on Debian/Ubuntu Linux run sudo apt install build-essential python3.