Install

OAK is one npm package that carries the CLI, the terminal app, and the capture hook, plus two editor extensions that render the same record inside VS Code and JetBrains IDEs. Installing it is two steps: put the CLI on your machine, then let it wire up the hook and your editors.

Requirements

• Node.js 20 or newer, with npm.
• herdr, the terminal backend the terminal app runs on, which you do not install yourself. The install scripts, oak update and oak doctor --fix install the version pinned in herdr.lock, currently 0.9.1, verify its checksum, set up its integrations, link OAK’s herdr plugin and widen herdr’s sidebar (its default 36-column ceiling stops the divider short of the session titles OAK gives herdr’s tabs; a width you set yourself is kept). A newer herdr already on the machine is kept. herdr ships for Linux and macOS on x86_64 and arm64, and for Windows on x86_64; Windows on ARM has no herdr build, and Windows support for herdr-backed pane listing, replies and agent start is untested in this release.
• Linux and macOS: python3, which herdr’s agent hooks need for sessions to join their panes, and which OAK’s herdr plugin runs on.
• Linux: make and a C++ compiler (g++, or whatever $CXX names; build-essential on Debian and Ubuntu), and an npm prefix with no space in its path. npm compiles node-pty, the helper the terminal app’s herdr tab runs herdr in, while it installs OAK, and npm 12 runs that build only when it is allowed with --allow-scripts=node-pty (the install scripts and oak update pass it for you). macOS and Windows use node-pty’s prebuilt binaries.

Without node-pty the install still succeeds, but the herdr tab cannot start, and oak doctor warns and names what is missing: fix that, then reinstall OAK (re-run its installer, or oak update --cli-only --force). Meanwhile oak attach opens herdr without it, handing the terminal to herdr’s own client with OAK in a pane.

Install the CLI

The install script installs the CLI from the latest release after checking its published sha256, then the extensions for whatever editors are on the machine, the bundled status line (when jq is present), and herdr:

curl -fsSL https://raw.githubusercontent.com/cell-observatory/oak-observatory/main/scripts/bootstrap.sh | bash

On Windows, run its PowerShell peer in native PowerShell, with no bash or WSL:

irm https://raw.githubusercontent.com/cell-observatory/oak-observatory/main/install.ps1 | iex

Run in a terminal, either script offers to add the capture hooks; through a pipe it prints the oak init step instead, since it cannot prompt. To follow the rolling pre-release channel, pass the channel through the pipe: append -s -- --channel dev to the bash line, or run the PowerShell one as & ([scriptblock]::Create((irm <url>))) -Channel dev. The choice is remembered, so later updates follow it.

Or install the CLI tarball from a release yourself. Each release attaches it as oak-observatory-X.Y.Z.tgz, for version X.Y.Z. Download it, then install the downloaded file (in Windows PowerShell 5.1, type curl.exe: curl there is an alias of Invoke-WebRequest):

curl -fLO https://github.com/cell-observatory/oak-observatory/releases/download/vX.Y.Z/oak-observatory-X.Y.Z.tgz
npm install -g --allow-scripts=node-pty ./oak-observatory-X.Y.Z.tgz
oak doctor --fix

This gives you the oak command, plus oak-observatory and the deprecated claude-observatory as aliases. npm 12 runs a dependency’s install script only when it is allowed, and --allow-scripts=node-pty allows the one OAK needs; earlier npm versions accept the flag. npm 12 also refuses a tarball URL on a host other than its registry’s, which is why the file is downloaded first. oak doctor --fix then installs herdr, its integrations and OAK’s herdr plugin.

Verify either way:

oak --version
oak doctor
oak status

Upgrading from claude-observatory

claude-observatory is now OAK. Version 0.9.5 and earlier, and the 0.10.0 pre-releases published under the old name, cannot update themselves across the rename: claude-observatory update stops with an npm EEXIST error (the old packages keep working), the old VS Code extension’s update notifier does not see this release, and a JetBrains IDE subscribed to the old plugin repository is offered a new plugin id rather than an update. Upgrade once, by hand:

1. Re-run an install script from Install the CLI. It removes the old claude-observatory npm package first, then installs OAK and the renamed editor extensions. To install by hand instead, first download the release tarball as above, so a failed download leaves the old CLI in place. Then run npm uninstall -g claude-observatory, install the downloaded file, and run oak doctor --fix and oak install-extensions. OAK needs Node.js 20 or newer (0.9.5 ran on 18), and on Linux the build tools under Requirements.
2. Quit Claude Code, then run oak init, even if you ran it on a pre-release. It rewrites the capture hooks to the new command and hooks six events beside PreToolUse and PostToolUse; until it runs, the file changes of a Bash command that fails are not recorded. oak doctor names any event that is not hooked, and oak status shows the hook count with the command to run.
3. Editors: the new VS Code extension uninstalls the old one, and the new JetBrains plugin disables the old one and offers a restart. If you subscribed to the JetBrains plugin repository, replace its URL with https://github.com/cell-observatory/oak-observatory/releases/latest/download/updatePlugins.xml.
4. Other machines: machines configured for the old SSH session listing are no longer read. Add each one with oak machine add <label> <ssh-target>.

Your store (~/.claude/claude-observatory), prefs, editor settings (claudeObservatory.*) and .observatoryignore files carry over unchanged, and claude-observatory keeps working as a deprecated alias of oak. Saved Timeline column widths reset once in both editors, because the Timeline gains a fourth tab.

Turn on capture

Capture is what makes an observed session show up. oak init installs the local hook that snapshots each file change — it prints nothing, returns immediately, and costs the agent no tokens. Run it with Claude Code closed: Claude Code snapshots its hooks when a session starts, and a session that is already running reverts hook edits made under it.

oak init

From here, every Claude Code session on this machine is recorded automatically (oak init --project writes the hook into one repository’s .claude/settings.json instead). When codex is on the PATH, oak init installs Codex capture too (--no-codex skips it), and --with-statusline adds the bundled status line. Run oak status at any time to confirm the hook is installed and see what has been captured.

Add the editor extensions

The same record renders inside your editor. oak install-extensions side-loads the VS Code and JetBrains extensions. The VS Code one then keeps itself updated; JetBrains updates once you add its plugin repository (the command prints that one-time step):

oak install-extensions

See VS Code and JetBrains for what each one surfaces. The extensions are thin renderers over the CLI, so every number matches the terminal app.

Other ways to install the extensions

Every release carries both editor packages as plain files, installable by hand with no CLI involved:

• VS Code family — download oak-observatory-vscode-v<version>.vsix, then Extensions view → ⋯ → Install from VSIX…
• JetBrains IDEs — download oak-observatory-jetbrains-v<version>.zip, then Settings → Plugins → ⚙ → Install Plugin from Disk… and restart. For native auto-updates, add the plugin repository once under Settings → Plugins → ⚙ → Manage Plugin Repositories: https://github.com/cell-observatory/oak-observatory/releases/latest/download/updatePlugins.xml