Install and configure

Install

Pheebs is published on npm. Install it globally:

npm install -g pheebs

Run pheebs init next to set up the hooks.

Configure

pheebs init

init is interactive, and one run configures all three agents. It looks for the ones you already have installed, then asks five questions.

1. Which agents to configure. Claude Code, Cursor and Codex, as a multi-select. Anything already on the machine is detected and preselected.
2. Where the hooks go. Project-local, the default, writes to the current repo only, so instrumentation is opt-in per repo and your personal projects stay out of the data. User-level applies to every repo on the machine.
3. The backend endpoint. Blank by default. Leave it blank and Pheebs stays local-only: events are written to ~/.pheebs/logs/ and nothing leaves your machine.
4. Your Pheebs API token. This provisions your developer identity and authenticates telemetry. It is entered masked and validated against the pheebs_ prefix. Leave it blank to skip and set it later with pheebs config set token <token>.
5. Whether to enable OpenTelemetry. Asked only when Claude Code or Codex is in your selection, because Cursor has no native OTel export to configure.

It then applies each agent in turn and prints what it wrote: the hook count, the hook-type count, the settings file, and whether OTel was configured.

Verify

pheebs doctor            # checks Claude Code config
pheebs doctor --cursor   # checks Cursor config
pheebs doctor --codex    # checks Codex config
pheebs doctor --global   # checks user-level config instead of project-local

doctor reports whether every expected hook entry is registered correctly, along with your endpoint and token status.

Skipping the prompts

Passing any flag drops init out of interactive mode and into a single scripted run. That is what the agent flags are for: each targets one agent and asks nothing.

pheebs init --cursor     # Cursor only, no prompts
pheebs init --codex      # Codex only, no prompts
pheebs init --global     # user-level instead of project-local
pheebs init --no-otel    # skip OpenTelemetry configuration

Each agent writes to its own config location, so they do not interfere with one another.

Scope

init is project-local by default. For Claude Code it writes to .claude/settings.local.json in the current directory, which is gitignored by default. To instrument every repo on the machine instead, personal ones included:

pheebs init --global

That writes ~/.claude/settings.json.

Codex is the exception. It reads <cwd>/.codex/config.toml, but drops the whole project layer until you trust the project in its TUI, and skips any handler without a matching trusted_hash. Both are your own security decision about a directory, so Pheebs writes neither. A project-local Codex install stays inert until you grant that trust, and init and doctor both say so.

What gets written

For Claude Code, init adds hook entries and an env block to the settings file for its scope, .claude/settings.local.json by default or ~/.claude/settings.json with --global:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "pheebs hook prompt_submitted", "async": true }] }
    ],
    "PreCompact": [
      { "matcher": "auto", "hooks": [{ "type": "command", "command": "pheebs hook context_compacted --trigger-type auto", "async": true }] },
      { "matcher": "manual", "hooks": [{ "type": "command", "command": "pheebs hook context_compacted --trigger-type manual", "async": true }] }
    ]
  },
  "env": {
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://<your-pheebs-backend>/otel",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Basic ..."
  }
}

Hooks that support several triggers, like PreCompact, register one entry per matcher, which is why Claude Code has 15 entries across 14 hook types.

The env block points Claude Code's native OpenTelemetry export at the backend's OTLP proxy, authenticated with your token. The client never holds an observability credential of its own. To skip OTel setup entirely:

pheebs init --no-otel