CLI observability tool for Claude Code agents. Tracks what agents are doing outside defined permissions, logs bypass attempts, and maintains compressed audit trails for building deny-lists.

Install

npm install
npm run build

Usage

1. Initialize a permission manifest

npx . init permission-manifest.json

2. Start watching a project directory

npx . watch --manifest permission-manifest.json --dir ./my-project --agent-id "claude-agent-1"

This monitors file system changes and (optionally) Claude Code state files to detect permission violations in real time.

3. Generate a violation report

npx . report --dir ./cpo-audit

Or export as JSON:

npx . report --dir ./cpo-audit --json --output report.json

4. Log manual actions

npx . log --manifest permission-manifest.json --type file --action "fs.write" --target "src/main.ts" --agent-id "manual"

5. Check audit status

npx . status --dir ./cpo-audit

Permission Manifest

The manifest defines what agents are allowed to do. Rules are evaluated in order:

Type	Pattern	Action	Description
file	`src/*/.ts`	allow	Allow editing source files
file	`*/.env*`	deny	Deny access to env files
command	`git push`	warn	Warn on git push
command	`rm -rf /`	deny	Deny destructive rm
network	`localhost:*`	allow	Allow local servers
network	`api.openai.com`	warn	Warn on OpenAI API calls

Sensitive Patterns

Paths matching sensitive patterns (e.g., .env, secrets, token) are automatically flagged as bypass_attempt even if no explicit rule matches.

Audit Trail

JSONL format — one action per line, append-only
Companion summary JSON for quick analysis
Automatic rotation when size exceeds maxTrailSize (MB)

Risk Score

The violation report calculates a risk score (0-100) based on:

Violation density (percentage of denied actions)
Bypass attempt rate
Total violation count

Score	Label
0	SAFE
1-24	LOW
25-49	MEDIUM
50-74	HIGH
75-100	CRITICAL

Commands

Command	Description
`init [path]`	Create a default permission manifest
`watch`	Start file system watcher
`report`	Generate violation report from audit trail
`log`	Log a manual action
`validate`	Validate a permission manifest
`status`	Show audit directory status

License

MIT