Track AI coding tools

One command sets up Claude Code, Codex, Cursor and Gemini CLI to report usage to SuperPenguin, on laptops and for cloud agents.

SuperPenguin tracks how your team uses AI coding tools: which models they call, how many tokens they use, what it costs and how long it takes. One command sets this up for every supported tool on a machine. It gets the key it needs by signing you in through the browser, so nobody has to create or copy a key by hand.

The command

Run this in a terminal on macOS or Linux (on Windows, inside WSL):

curl -fsSL https://app.superpenguin.ai/install | sh

Run it again at any time. Every run checks each setting and repairs anything that changed, so running it twice does no harm. A second run reuses the machine's key while it still works, so it does not ask you to sign in again.

It needs curl, and jq, node or python3 to edit settings files (macOS 15 and later include jq). It never installs software.

What happens when you run it

Sign in. It prints a short code and opens SuperPenguin in your browser. You check the code, choose the organization and approve. SuperPenguin then gives this machine its own key, which can only send coding-tool usage. Signing in again on the same machine replaces that key. You can also paste a key instead.
Email. It asks which email to tag your usage with, defaulting to your SuperPenguin sign-in email.
Tools. It configures every supported tool it finds (below), keeping a backup of each file it changes, and lists other coding tools it found but cannot configure.
Session transcripts. It asks SuperPenguin whether your organization has turned on session transcripts. If it has, it sets them up and says so in one line. If not, it skips them without a message. See Session transcripts.
Cloud agents. Run inside a git repository, it offers once to set up that repository's cloud agents. See Cloud agents.

What it changes on each tool

Tool	What the installer changes
Claude Code (terminal, desktop app, VS Code and JetBrains extensions)	Adds telemetry settings to the `env` block of `~/.claude/settings.json`: usage metrics, events and traces sent to SuperPenguin.
Codex (CLI and desktop app)	Adds a marked `[otel]` block to `~/.codex/config.toml` (or `$CODEX_HOME`). The Codex desktop app reads it when it starts, so quit and reopen it once.
Cursor (IDE and `cursor-agent` CLI)	Adds hooks to `~/.cursor/hooks.json`: a `stop` hook that runs `~/.superpenguin/hooks/cursor-usage-hook.sh` after each agent turn, and `postToolUse`, `postToolUseFailure`, `subagentStop`, `sessionEnd` and `stop` hooks that run `~/.superpenguin/hooks/cursor-activity-hook.sh`. Their key is in `~/.superpenguin/cursor-usage.conf`, readable only by you.
Gemini CLI	Adds a `telemetry` block to `~/.gemini/settings.json` and turns Gemini CLI's prompt logging off.

Every other setting in these files is kept. If a file already sends OpenTelemetry to another service, the installer stops and leaves the file alone; --force replaces those settings for Claude Code (a backup is kept), and --skip-<tool> leaves a tool out.

GitHub Copilot CLI, Copilot in VS Code, Cline, Qwen Code and Factory Droid can only be configured through environment variables, and Windsurf, Kiro and Goose cannot export to SuperPenguin from your machine. The installer lists the ones it finds. SuperPenguin Desktop covers some of these from the Mac.

What is sent, and what is not

Sent:

Claude Code, Codex and Gemini CLI: each model request's model, token counts and cost, session and timing, and tool names and durations (for example, which MCP tool ran and how long it took). Claude Code and Codex also send traces of each prompt, model request and tool call.
Cursor: one record per agent turn with the model, the four token counts (input, output, cache read, cache write), the conversation, the turn's status, the Cursor version and account email, and the repository and branch name. Also each tool call's name (such as Shell, Read or an MCP tool), how long it took and whether it failed; when a subagent finishes, its type, status, duration and message and tool counts; and when a session ends, how long it lasted and why it ended. Never a tool's input or output, commands or file paths.
Every tool: the email you chose and a machine ID. The machine ID is a hash of your computer's ID, so the ID itself never leaves the machine. Claude Code and Codex also report the account you are signed in to them with.

Not sent: prompts, responses, file contents, commands and tool input or output. The installer never turns on a tool's content logging. If a tool sends content anyway, SuperPenguin drops it on arrival. The exception is session transcripts: when your organization turns them on, SuperPenguin also keeps content a tool sends.

Known gaps:

Cursor subagent tokens are not counted. Cursor's hooks report no subagent tokens and leave them out of the turn's counts, so a turn that used subagents shows fewer tokens than it used. The subagent records show which turns those are.
Cursor cloud agents send usage and tool activity, but not session transcripts yet.
Your Cursor spend still comes from your Cursor connection in SuperPenguin. The hook's per-turn data does not change it.
ChatGPT Work threads in the Codex desktop app run on OpenAI's servers, so their prompts and responses cannot be reported from your machine.

Session transcripts

Session transcripts let SuperPenguin explain an expensive session, for example one that kept retrying a failing tool call. They are off by default. An organization owner turns them on for the whole organization under Settings → AI coding → Coding session transcripts; there is no per-person setting.

Once they are on, the next run of the command on each machine sets them up for Claude Code, Codex and Cursor, and prints one line saying so. Codex asks you to trust the new hook once: open Codex and review it with /hooks. If an owner turns transcripts off again, the next run removes the transcript hooks.

To keep transcripts off on your machine, add --no-transcripts:

curl -fsSL https://app.superpenguin.ai/install | sh -s -- --no-transcripts

It removes transcript hooks an earlier run added. Pass it on every run, including in scripted rollouts, because a run without it follows your organization's setting again.

Coding session transcripts covers what a transcript contains, how long it is kept and how to delete it.

Cloud agents

Cursor cloud agents and Claude Code cloud environments run on their providers' servers and never read your laptop's settings. Run the command inside a git repository and it asks once:

Also set up cloud agents (Cursor cloud agents, Claude Code cloud environments) for web-app? This writes hook files to commit and creates a cloud key. [Y/n]

If you answer yes, the browser approval also creates a separate cloud key for that repository, named coding-telemetry cloud <repository>, which you can revoke under API keys. The installer then:

Writes files to commit. .cursor/hooks.json and the Cursor usage and activity hooks in .cursor/hooks/ for Cursor cloud agents, and, when your organization has transcripts on, transcript hooks in .claude/settings.json for Claude Code cloud sessions. No key is written into the repository. The hooks do nothing on laptops, so committing them is safe for the whole team.
Shows the cloud key once, on your terminal only. The installer's own output shows it masked, so logs never contain it. It is not saved on your machine.
Says exactly where to paste it:
- Cursor cloud agents: add it as the SUPERPENGUIN_API_KEY secret (type Runtime Secret) in the Cursor dashboard under Cloud Agents → Secrets. If CURSOR_API_KEY is set to your Cursor API key when you run the installer, it stores the secret for you instead, through Cursor's cloud agent API, as your personal secret limited to that repository. It does this only when the repository has an origin remote, so the secret never reaches your other cloud agents.
- Claude Code cloud environments: paste the variables it shows into the environment's Environment variables at claude.ai/code. Claude Code has no API for this, so this step stays a paste. When transcripts are on, also add the setup-script line it shows.
Network access. Allow app.superpenguin.ai in each cloud environment's network access.

If you answer no, it does not ask again for that repository. Run with --cloud-agents to set it up later, or --no-cloud-agents to never be asked. Codex cloud does not export usage, so it is not supported.

Check, remove and options

See what is set up, on this machine and for the repository you are in:

curl -fsSL https://app.superpenguin.ai/install | sh -s -- --status

Remove everything the installer added on this machine:

curl -fsSL https://app.superpenguin.ai/install | sh -s -- --uninstall

Repository files are shared with your team, so --uninstall leaves them alone unless you name the repository with --repo. Revoke cloud keys under API keys.

Option	What it does
`--status`	Show what is configured and change nothing.
`--dry-run`	Show what would change and write nothing. No key is created.
`--uninstall`	Remove the settings and hooks the installer added on this machine.
`--uninstall --repo DIR`	Also remove the hooks it wrote into the repository `DIR`.
`--login`	Sign in again for a new machine key, even when the current one works.
`--key KEY`	Use this key instead of signing in (or set `SUPERPENGUIN_API_KEY`).
`--email EMAIL`	Tag usage with this email.
`--yes`	Never ask anything, for scripted rollouts. It uses `--key` or the key already on the machine.
`--no-transcripts`	Keep session transcripts off on this machine.
`--with-transcripts`	Accepted for older commands; does nothing.
`--cloud-agents` / `--no-cloud-agents`	Set up this repository's cloud agents without asking, or never ask.
`--repo DIR`	The repository for cloud agents, instead of the one you are in.
`--skip-claude`, `--skip-codex`, `--skip-cursor`, `--skip-gemini`	Leave that tool alone.
`--no-traces`	Send logs and metrics only.
`--force`	Replace another service's telemetry settings in Claude Code's settings.

For a scripted rollout (MDM or dotfiles), pass the key and --yes:

curl -fsSL https://app.superpenguin.ai/install | SUPERPENGUIN_API_KEY=sp-YOUR_ORG_KEY sh -s -- --yes --email [email protected]

To set up Claude Code and Codex for a whole organization without running anything on each machine, use the organization key with managed settings under Settings → AI coding.