Getting Started

AgentOps is a local-first telemetry layer for AI coding agents. It intercepts command output from Claude Code, Codex CLI, Gemini CLI, and OpenCode, classifies it, and returns compact summaries instead of raw dumps — saving tokens on every command your agent runs. Everything is stored locally in SQLite; nothing leaves your machine unless you explicitly submit a score.

This page takes you from zero to a scored session in about 5 minutes.

1. Install

npm i -g https://useagentops.com/download/agentops-latest.tgz

Verify it works:

agentops --version

Expected success:

0.1.x

If install fails with a permission error, fix your global npm prefix or rerun the same command in the Node environment you use for global CLIs. Do not install the bare agentops npm package name; AgentOps is distributed from the site-hosted tarball above.

2. Initialize your project

From your project root:

agentops install

This runs agentops init (creates .agentops/config.yaml and the local SQLite store) and installs the local hook wrappers and host integrations in one step. Then confirm everything is healthy:

agentops doctor
agentops hooks status

Expected success:

AgentOps doctor
OK config
OK database
OK cli

agentops hooks status should show each installed integration as OK. If a hook is MISSING or NOT EXECUTABLE, rerun the matching install command from the next section, then run agentops hooks status again.

3. Hook up your agent

AgentOps observes your agent through hooks. Pick your agent:

Claude Code

agentops hooks install claude

This creates a wrapper script at .agentops/hooks/claude.sh. Point your Claude Code hook configuration at that script. If the AgentOps CLI is not on your PATH, set:

export AGENTOPS_CLI_PATH=/absolute/path/to/agentops

Codex CLI

agentops hooks install codex

This creates a fallback wrapper at .agentops/hooks/codex.sh and prepares a Codex plugin bundle under .agentops/codex/marketplace. If the Codex CLI is on your PATH, AgentOps registers the plugin automatically. To register manually:

codex plugin marketplace add .agentops/codex/marketplace
codex plugin add agentops@agentops-<project-name>

Gemini CLI

agentops hooks install gemini

This creates a wrapper script at .agentops/hooks/gemini.sh and registers an AfterTool hook entry for run_shell_command in your project's .gemini/settings.json, so Gemini CLI calls AgentOps after every shell command. Requires Gemini CLI v0.26.0 or newer (hooks are enabled by default). Gemini fingerprints project-level hooks, so it will ask you to trust the AgentOps hook the first time it runs.

OpenCode

agentops opencode install

This installs a plugin-native entrypoint at .opencode/plugins/agentops.js. OpenCode loads it automatically when started from the same project directory.

Verify hooks

agentops hooks status

Every hook should report OK. If one reports MISSING or NOT EXECUTABLE, the status output tells you the exact command to fix it.

Quick repair commands:

agentops hooks install claude
agentops hooks install codex
agentops hooks install gemini
agentops opencode install
agentops hooks status

4. Run a session

Use your agent normally. Every command it executes flows through AgentOps: raw output is stored on disk, classified locally (test, typescript, eslint, build, git-diff, search, logs, generic), and a compact summary goes back to the agent instead of the full dump. Nothing leaves your machine during local use.

After a session, check what you saved:

agentops report
agentops score

agentops score shows your session grade and the token savings breakdown. agentops report --cost adds an estimated cost breakdown in dollars.

If the report is empty, run one normal agent session from the same project root and check:

agentops commands --last 5
agentops pipeline --inspect

Expected success is at least one recent command row. If there are none, the agent hook is not being called; return to agentops hooks status.

5. Submit to the leaderboard

Sign in first (Google OAuth, opens your browser):

agentops login

Expected success:

Logged in as <your-email>

Then submit your latest session:

agentops submit

The CLI shows exactly what will be sent — score, grade, token counts, cache rate — and asks for confirmation. No source code, file paths, or raw output is included. See Model Communication and Privacy for the full transmitted-fields list.

If you are not logged in, submit prints an authentication error. Run:

agentops login
agentops status
agentops submit

agentops status should show your player dashboard. If it has no remote data yet, submit one scored session first.

6. View the dashboard

You can also generate a local HTML dashboard without any account:

agentops dashboard

Agent checklist

Use this block when an AI coding agent needs exact setup steps:

npm i -g https://useagentops.com/download/agentops-latest.tgz
agentops --version
agentops install
agentops hooks install claude   # or codex, gemini; use opencode install for OpenCode
agentops hooks status
agentops status

Expected state:

  • agentops --version prints a version number.
  • agentops hooks status reports the target hook as OK.
  • agentops status works after agentops login; before login, use local commands such as agentops report, agentops score, and agentops commands.
  • Data that leaves the machine on submit is numeric scoring telemetry plus project metadata; raw command output, source code, prompts, transcripts, and file paths are not submitted.

Next steps

How Scoring Works →