Installation

Prerequisites

• Node.js 22+: the runtime OpenLoop runs on (Bun 1.x also works).

• Bun (optional): only the interactive TUI needs it. When you launch the TUI on a Node-only machine, the CLI re-executes itself under Bun; without Bun installed it prints a clear message and suggests openloop watch, a no-Bun live dashboard.

• git: OpenLoop is git-native (branches, optional worktrees, PR creation).

• A coding-agent CLI on PATH: Pi is the default provider. Alternatives (Claude Code, Aider, Codex, OpenCode) are optional; check what OpenLoop can find:

  openloop config list-providers

• git worktree support, only if you enable runtime.useWorktree (opt-in isolation). runtime.worktreeSetupCommand can provision worktree-local build state (e.g. npm install).

API keys are not managed by OpenLoop. Each agent tool keeps its own credentials in its own config; OpenLoop only spawns the binary.

Install from npm (recommended)

npm install -g openloop

Verify:

openloop --version
openloop doctor   # checks prerequisites, providers, and daemon health

Install from source

To run the latest unreleased code:

git clone https://github.com/jaltez/openloop.git
cd openloop
npm install
npm run build
npm link          # puts `openloop` on your PATH

The build targets Node, so the published CLI runs on plain Node 22+; Bun works too.

Development setup

If you want to hack on OpenLoop itself:

npm run check     # type-check
npm test          # vitest unit + integration suites
npm run build     # build dist/

What gets installed where

OpenLoop keeps global state under ~/.openloop/:

~/.openloop/
├── config.json     # global configuration
├── projects.json   # registry of linked projects
└── run/            # daemon runtime state
    ├── daemon.pid
    ├── daemon-state.json
    ├── daemon.log
    └── events.jsonl

Set the OPENLOOP_HOME environment variable to relocate all of it (see environment variables).

Uninstall

openloop service stop
npm rm -g openloop          # or: in the cloned repo, `npm unlink`
rm -rf ~/.openloop          # optional: global state

Per-repository .openloop/ directories are left untouched; remove them manually if you want.