# Claude Permission Observability (cpo)

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

```bash
npm install
npm run build
```

## Usage

### 1. Initialize a permission manifest

```bash
npx . init permission-manifest.json
```

### 2. Start watching a project directory

```bash
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

```bash
npx . report --dir ./cpo-audit
```

Or export as JSON:

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

### 4. Log manual actions

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

### 5. Check audit status

```bash
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