docs
Pheebs docs
What Pheebs is, what it stores, and how to run it.
Pheebs sits inside your AI coding agent on a hook. Every time something happens in a session (a prompt goes in, a tool runs, a model changes, the context compacts) it writes one line of JSON describing the shape of that moment, and nothing about its contents.
It exists because nobody has settled what "using AI well" actually looks like. Adoption numbers are easy and say almost nothing. Pheebs is measures what is really happening inside AI sessions, how often, and in what patterns.
Quickstart
Install from npm, then register the hooks:
# install
npm install -g pheebs
# interactive: pick your agents, then hooks and OpenTelemetry are registered
pheebs init
# check the wiring
pheebs doctorThat is the whole setup. Pheebs fires in the background during your sessions and nothing changes about how you work. Read your own data at any time. It is plain text:
tail -qn 20 "$(ls -t ~/.pheebs/logs/*.jsonl | head -1)"Where to go next
init, per-repo config, and what gets written to your agent's settings. What it captures Every hook, every event, and every field, for Claude Code, Cursor, and Codex. Privacy What leaves and doesn't leave your machine and in which scenarios. The AI Proficiency Model Defines the practices and signals that matter when working with AI agents. CLI and config Commands, settings, environment variables, and where each lives on disk. Backend contract The four routes any Pheebs backend has to answer, and why each behaves as it does. Which agents work
| Agent | Status | Hook entries |
|---|---|---|
| Claude Code | Fully supported | 15 entries across 14 hook types |
| Cursor | Supported | 13 entries across 13 hook types |
| Codex | Fully supported | 10 entries across 10 hook types |
Fully supported means hooks plus OpenTelemetry. Supported means hooks only. All three share the same log format and the same remote transport. The ai_tool field identifies the source.
Requirements
- Node.js 18 or newer.
- A git repository, for automatic codebase and developer detection.
- Claude Code, Cursor, or Codex with hooks support.
