Initial MVP: Claude Permission Observability CLI tool

README.md

@@ -0,0 +1,103 @@
+# 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