OakTreeAI CLI

The OakTreeAI terminal coding agent — an interactive, AI-powered coding agent that runs in your terminal.

Installation

Install globally so the oaktree command is on your PATH (requires Node.js 22+):

npm install -g @oaktreeai/cli

To upgrade later, run npm install -g @oaktreeai/cli@latest. To run it without a global install, use npx @oaktreeai/cli.

A plain npm install @oaktreeai/cli (without -g) only adds the package to a local node_modules and does not put oaktree on your PATH — you'd get command not found: oaktree. Use -g for the command, or invoke it via npx.

Usage

The CLI uses React Ink for the interactive terminal renderer and defaults to the local ASP.NET Core API at http://127.0.0.1:5050, using versioned REST routes under /api/v1 and the SignalR hub at /realtime/agent-session for live sessions:

oaktree auth login
oaktree
oaktree --api-url http://127.0.0.1:5050 --ws-url http://127.0.0.1:5050/realtime/agent-session doctor

Headless one-shot execution is available without importing the Ink renderer:

oaktree exec --print "summarize this repo"
oaktree exec --json --message-file prompt.md
oaktree exec --print --allow-edits "update the changelog"
oaktree exec --print --allow-shell "run the unit tests"

exec defaults to CI-safe local policy: mutating client tools are denied unless explicitly allowed with --allow-edits or --allow-shell. --json emits newline-delimited events with schema_version: 1; --print emits a stable plain-text transcript suitable for normal terminal scrollback. The interactive app renders on the main terminal screen with native scrollback for the transcript; completed entries are committed to the terminal's scrollback buffer, and only the active assistant response stays in the live frame.

Canonical assistant transcript rendering, composer input, slash commands, the / command picker, in-app /login and /logout, model switching, cancellation, session activation, deferred client-tool registration and execution, approval policy, browser auth, file attachments, artifact actions, and cache-assisted session picking are available.

Attachments can be added with /attach <workspace-path>, /attach clipboard, /paste, or Ctrl+V when your terminal forwards that key to the app. Clipboard attachment paste supports copied screenshots/images and copied files through the native system clipboard on macOS, Windows, and supported Linux desktops. If a Linux compositor or CPU/libc target cannot load the native clipboard binding, oaktree doctor reports that limitation instead of crashing the CLI.

The CLI automatically sends compact local context with each prompt, including the workspace root, current date, OS, shell and shell version when available, terminal hints, Node.js version, and CLI version. This context is sent through hidden prompt metadata, so the visible transcript still shows only the message you typed.

Agent skills

The CLI discovers agent skills from a .agents/skills directory in two locations:

• Project: <workspaceRoot>/.agents/skills/
• User: ~/.agents/skills/

Each skill is a directory containing a SKILL.md file with YAML-style frontmatter (name, description) and an instruction body, plus optional bundled assets:

.agents/skills/
  review-pr/
    SKILL.md          # frontmatter (name, description) + instructions
    checklist.md      # optional bundled asset

---
name: review-pr
description: Review a pull request diff and report high-confidence bugs.
---

Step-by-step instructions the model loads on demand when it calls the `skill` tool.

name must be a safe slug (^[a-z0-9][a-z0-9-]*$) and description is a single-line summary. Skills use progressive disclosure: only each skill's name and description are injected up front, and the model calls the skill tool with a skill's name to load its full body on demand. On a name collision, project skills win over user skills. Discovered skills (and any discovery warnings) are surfaced in the status report.

Verify and update an existing install:

oaktree --version
npm install -g @oaktreeai/cli@latest   # upgrade to the latest release
oaktree doctor
oaktree update

oaktree doctor checks local runtime, package metadata, auth, backend reachability, realtime connection.ready, Git root, and tool registration. Crash diagnostics are written to oaktreeai-cli.log under the CLI config directory with tokens and sensitive environment values redacted.

Development

When working on the CLI from a checkout of the monorepo:

npm run build
npm run lint && npm run type-check
npm test
npm run smoke:pack      # validate packaged tarball contents
npm run smoke:install   # validate a real install of the packed tarball

See the repository root README.md and CLAUDE.md for the full release process.