olivergraph

The Oliver CLI. Captures local Claude Code and Codex agent activity and uploads it to your Oliver workspace.

It installs repo-local Claude/Codex hooks that write each hook payload to a local queue (.oliver/agent-hooks/pending.jsonl), then a background uploader normalizes those payloads into Oliver events and sends them to authenticated POST /events.

Install

Install the CLI globally, then run oliver start inside the repo you want to capture:

npm install -g olivergraph
cd your-project
oliver start

oliver start is the single entry point: it wires the hooks (idempotent), then runs the background uploader, opening the Oliver portal to sign in on first run. It writes repo-local config:

• .codex/config.toml
• .claude/settings.local.json
• .oliver/agent-hooks/config.json

These are local machine state (absolute paths to the installed CLI) and should stay out of git. Install globally rather than via npx — the hook commands embed the CLI's absolute path, and an npx cache path can be garbage-collected out from under the installed hooks.

Use OLIVER_AGENT_HOOK_SCOPE=user oliver install only when you intentionally want to wire global ~/.codex/config.toml and ~/.claude/settings.json. oliver install (advanced) wires the hooks without starting the uploader — for CI, headless setups, or user-scope installs where the uploader runs elsewhere.

Run the uploader

oliver start runs the background uploader (after wiring hooks). On first run, if no credential is saved it opens the Oliver portal to sign in and then starts — so a fresh setup is just:

oliver start

oliver status    # queue, capture/upload counts, hook warnings, uploader state
oliver stop      # stop the background uploader
oliver flush     # flush the queue once, now
oliver watch     # run the uploader in the foreground

The uploader stores its PID and log under .oliver/agent-hooks and pushes every OLIVER_AGENT_PUSH_INTERVAL_SECONDS seconds.

oliver status also inspects repo/user Claude and Codex hook configuration. If it finds an older localhost listener hook, a queue hook for another repo root, or mixed hook modes, it prints a warning in the hooks section. Hook command failures are appended to .oliver/agent-hooks/hook-errors.log.

Authentication

oliver start handles sign-in for you on first run, but you can authenticate explicitly:

• Browser login (to re-authenticate): oliver login / oliver logout. To switch workspaces without re-auth, see Workspaces.
• API key from the portal, saved once: oliver start --api-key usr_... --workspace default — supported on start only; saved under .oliver/agent-hooks/auth.json.
• Static token / headless / CI: export OLIVER_TOKEN=usr_.... In a non-interactive shell oliver start will not open a browser — set a token, or pass --no-login to fail fast instead of waiting on a login it can't complete.

Token precedence: OLIVER_TOKEN env → saved token (login or --api-key) → browser login.

Workspaces

Your login token can address any workspace you belong to — the active workspace is a separate value saved in local config and sent as X-Workspace on each event. Switch it without re-authenticating:

oliver workspace list          # all workspaces you belong to (* marks the active one)
oliver workspace set <slug>     # switch the active workspace
oliver workspace                # print the current active workspace

set verifies you are a member of the target slug before saving. A running uploader picks up the change on its next flush; run oliver restart to apply it immediately. Workspace selection precedence matches events: --workspace / OLIVER_WORKSPACE → saved config → default.

Environments

By default the CLI talks to production (https://api.olivergraph.com). Target a different environment with --env on any command, or set OLIVER_ENV:

oliver login --env staging     # sign in against staging
oliver install --env local     # develop against a local stack
export OLIVER_ENV=staging       # or set it once for the shell

| env | API | portal | |-----|-----|--------| | prod (default) | https://api.olivergraph.com | https://dashboard.olivergraph.com | | staging | https://staging-api.olivergraph.com | https://staging-dashboard.olivergraph.com | | local | http://127.0.0.1:8081 | http://127.0.0.1:5173 |

oliver login/oliver install save the resolved API into local config, so later start, status, and flush stay on the same environment without repeating --env.

Configuration

Environment variables override saved login/config values:

• OLIVER_ENV: target environment prod | staging | local (default prod)
• OLIVER_API: backend API URL — overrides --env (default https://api.olivergraph.com)
• OLIVER_APP: portal URL for browser login — overrides --env (default https://dashboard.olivergraph.com)
• OLIVER_TOKEN: bearer token for authenticated POST /events; normally saved by oliver login
• OLIVER_WORKSPACE: workspace slug for event writes (default default)
• OLIVER_PROJECT: event project target value (default default)
• OLIVER_AGENT_PUSH_INTERVAL_SECONDS: uploader/flush cadence (default 15)
• OLIVER_AGENT_PUSH_BATCH_SIZE: max events to flush per pass (default 100)

Privacy

Hook payloads may contain prompts, tool inputs/outputs, paths, and transcript references. The backend redacts common secret keys before storage, but the local queue holds raw payloads — keep .oliver/ local and uncommitted. Install these hooks only for repos whose agent activity should be stored in Oliver.