ClankerLog CLI

Privacy-friendly command-line clanks for coding-agent activity.

clankerlog.ai

No code. No prompts. No secrets. Just clanks.

Contents

• Quick Start
• Project Setup
• Agent Hooks
• Useful Options
• Doctor
• Privacy
• Development

Quick Start

This is the easiest path: install the CLI, save your API key, allow one project, preview the payload, then connect Codex hooks for automatic clanks.

npm install -g clankerlog

clankerlog login

cd /path/to/project
clankerlog init

Preview the payload without sending it:

clankerlog ping --dry-run --agent codex --model gpt-5.5

Connect the Codex Stop hook:

clankerlog hooks install codex

Then run /hooks in Codex if command approval is required. That is the whole golden path. The CLI infers stack tags from project files when you do not pass --stack, and clankerlog init defaults the public project name to the folder name.

Project Setup

Projects are denied by default. Run one of these from a project folder before it can send clanks:

clankerlog init

Use allow when you only want to add the current folder to the allow-list and skip the project-local .clankerlog.json setup:

clankerlog allow

You can override the public project name when needed. The same --name option also works with allow.

clankerlog init --name my-public-project

Add explicit stack tags only if inference is not enough:

clankerlog init --stack typescript,pnpm

Agent Hooks

For day-to-day use, wire ClankerLog into your coding agent's hook system so clanks are sent automatically after agent activity. Pick the agent you use and run its installer.

Codex

Install the Codex Stop hook:

clankerlog hooks install codex

After installing, run /hooks in Codex if command approval is required.

Claude Code

Install the Claude Code Stop hook with the model name ClankerLog should report:

clankerlog hooks install claude --model claude-sonnet-4.5

Cursor

Install the Cursor stop hook:

clankerlog hooks install cursor

Hermes

Install the Hermes shell hook:

clankerlog hooks install hermes

Topchester

Install the Topchester Stop hook:

clankerlog hooks install topchester

OpenClaw

Install the global OpenClaw message:sent hook:

clankerlog hooks install openclaw

This writes a managed hook directory at ~/.openclaw/hooks/clankerlog/ with HOOK.md and handler.ts. The generated handler sends clanks only for successful outbound messages, calls clankerlog hook openclaw message-sent, and does not read or forward message content. If OpenClaw does not enable the hook automatically, run:

openclaw hooks enable clankerlog

Opencode

Install the global Opencode session.idle plugin:

clankerlog hooks install opencode

This writes ~/.config/opencode/plugins/clankerlog.ts. Restart Opencode after installing so it loads the plugin.

Pi

Install the Pi agent_end extension:

clankerlog hooks install pi

This writes ~/.pi/agent/extensions/clankerlog.ts. If Pi is already running, run /reload after installing.

Managing Hooks

Supported agent names are codex, claude, cursor, hermes, topchester, opencode, openclaw, and pi.

Preview an install without writing files:

clankerlog hooks install codex --dry-run

Check or remove an installed hook:

clankerlog hooks status <agent>
clankerlog hooks uninstall <agent>

Hook commands read the agent hook JSON payload from stdin, use the workspace path from the hook payload, and ignore assistant messages, message content, and transcript paths. Hook commands support --dry-run for local payload inspection.

See docs/integrations.md for the fuller manual install runbook, local development commands, and integration notes.

Useful Options

Non-interactive login:

clankerlog login --api-key clk_live_...

Explicit stack tags for a one-off clank:

clankerlog ping --agent codex --model gpt-5.5 --stack typescript,pnpm

Dev or local endpoint:

clankerlog ping \
  --agent codex \
  --model gpt-5.5 \
  --endpoint https://ingest.dev.clankerlog.ai/v1/clanks

Environment overrides:

CLANKERLOG_API_KEY
CLANKERLOG_INGEST_URL
CLANKERLOG_AGENT
CLANKERLOG_MODEL
CLANKERLOG_STACK

Use CLANKERLOG_AGENT for generic integrations that call clankerlog ping directly. Agent-specific hooks like clankerlog hook codex stop infer their default agent name.

Doctor

clankerlog doctor

doctor reports config status, redacted auth status, endpoint, an authenticated API check when an API key is configured, allowed projects, current project allow-list state, and project-local config. It does not send a clank.

Privacy

The CLI sends a small event with project display name, agent name, model name, stack tags, and timestamp. It does not read or send source files, prompts, transcripts, diffs, terminal output, secret-looking environment values, or file contents. Stack detection uses filenames only.

Example payload:

{
  "type": "clank",
  "project": {
    "display_name": "my-project"
  },
  "agent": "codex",
  "model": "gpt-5.5",
  "stack": ["typescript", "pnpm"],
  "timestamp": "2026-05-18T15:30:00.000Z"
}

Projects are denied by default. Run clankerlog init or clankerlog allow inside a folder before clankerlog ping can send from it.

Development

This repo uses mise for the local toolchain and pnpm for package management.

~/.local/bin/clankerlog-dev is the local development shim; it runs src/cli.ts through this checkout so local testing always uses fresh source instead of the last built bin/clankerlog.js.

mise install
pnpm install
mise run local-ci

Useful scripts:

pnpm run build
pnpm run check
pnpm run test
pnpm run format