agent-friction

Telemetry and observability for AI coding agents — find what slows them down: turn waste, instruction tax, skill/rule bloat, and whether a change actually helped.

Philosophy: measure first → diagnose patterns → change skills/rules/code only when evidence keeps pointing at the same friction.

Install

npm install agent-friction
# or globally
npm install -g agent-friction

Quick start

In your project root:

npx agent-friction init

This writes agent-friction.config.json, installs the skill under .agents/skills/agent-friction, and creates relative symlinks into:

• .cursor/skills/agent-friction
• .claude/skills/agent-friction
• .codex/skills/agent-friction

So each harness sees the skill, but only .agents holds the real files.

init also wires hooks (idempotent merge — keeps your existing hooks):

• .cursor/hooks.json — stop, sessionStart, postToolUse, afterShellExecution, sessionEnd
• .claude/settings.json — Stop, SessionStart, PostToolUse, SessionEnd
• .codex/hooks.json — same nested events as Claude

Hooks write to .cursor/agent-friction/ and never inject into the model.

npm install alone does not touch your repo — run init once per consumer project.

CLI

agent-friction latest                    # last auto-generated turn report
agent-friction surface --days=30         # instruction tax + skill usage + epochs
agent-friction watch --browser           # live dashboard
agent-friction compare --days=30         # baseline before/after
agent-friction task <session-uuid>       # full turn audit
agent-friction aggregate --days=7        # cross-session rollup
agent-friction rediscovery               # repeated pre-edit file clusters
agent-friction hook run-on-stop          # harness hook entrypoint

Options: --json, --repo=PATH, --transcripts=PATH, --live-blast

Disable auto-run: AGENT_FRICTION_AUTO=0 or touch .cursor/agent-friction/off

Config

agent-friction.config.json in the consumer repo:

| Key | Default | | --- | ------- | | dataDir | .cursor/agent-friction | | skillRoots | [".agents/skills"] | | ruleRoots | [".cursor/rules"] | | contracts | AGENTS.md, CLAUDE.md, GEMINI.md, PRODUCT.md | | hookConfigs | .cursor/hooks.json, .claude/settings.json, .codex/hooks.json | | skillInstallPath | .agents/skills/agent-friction | | skillMirrors | .cursor/skills, .claude/skills, .codex/skills |

Publish (maintainer)

npm test
npm publish --dry-run
npm login
npm publish

License

MIT