# AI use cases for Numbat (perplexityai/numbat)

Repo: [perplexityai/numbat](https://github.com/perplexityai/numbat) | Use cases: 3 | Page: https://dedupedai.com/use-cases/perplexityai-numbat/

numbat is a Go command-line tool that watches AI agent activity on a laptop or workstation, detects risky behavior with local rules, can optionally block some actions before they run, and rebuilds past sessions from on-disk artifacts.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Audit past agent sessions without changing any config: https://dedupedai.com/use-cases/perplexityai-numbat/audit-past-agent-sessions-read-only/
- Monitor live Codex activity into a local record file: https://dedupedai.com/use-cases/perplexityai-numbat/monitor-codex-sessions-live/
- Block a risky Codex action with a custom deny rule: https://dedupedai.com/use-cases/perplexityai-numbat/enforce-custom-deny-rule-before-action/

## How to audit past agent sessions without changing any config with Numbat

Repo: [perplexityai/numbat](https://github.com/perplexityai/numbat) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Scan existing agent session artifacts on a machine to list agents and surface findings.

**Who it is for:** A security engineer asked to review what AI coding agents did on a developer laptop after a suspected leak.

**The problem:** Agent sessions leave artifacts on disk, but nobody has a normalized view of what the agents read, ran, or sent.

**The outcome:** A list of discovered agents and a findings stream from past sessions, with secrets redacted, and no hooks or agent settings changed.

### Steps

1. Download a Numbat release for your OS and check it against the published SHA-256 checksums.
2. Run `numbat agents` to see which agents Numbat can discover on this machine.
3. Run `numbat scan --agent codex` to limit discovery to one agent, or `numbat scan` to scan all discovered parser-backed agents.
4. Run `numbat scan --emit all` if you also need events and indicators, not only findings.
5. Run `numbat help scan` to check the flags for output modes before sharing results. (inferred, check the README)

### Prompt to paste into your agent

```text
Use the repo perplexityai/numbat. Run `numbat agents` and then `numbat scan --agent <agent-name>` on this machine, and save the NDJSON output to a file. Report the number of findings and their rule_id values. Verify that the output contains no complete raw transcript and that secret values are redacted.
```

### Caveat

Reconstruction only covers what the agent persisted to disk, and a finding is a rule match, not proof that an action completed or that the machine was compromised.

Risk, credentials: Scan output can still contain sensitive endpoint and agent context, so store and share the results as confidential.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/perplexityai-numbat/audit-past-agent-sessions-read-only/

## How to monitor live Codex activity into a local record file with Numbat

Repo: [perplexityai/numbat](https://github.com/perplexityai/numbat) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Install a monitor-only Codex hook that writes events and findings to an NDJSON file.

**Who it is for:** A platform operator who wants continuous visibility into a Codex user's activity on a shared workstation.

**The problem:** Past-session scans show history only after the fact, and operators need to see activity as it happens.

**The outcome:** Live Codex events, findings, and indicators written to ~/.numbat/records.ndjson, with hooks running in monitor-only mode.

### Steps

1. Install Numbat, then run `numbat hook install --agent codex --emit all`.
2. Run `numbat hook status --agent codex` to confirm the configuration is in place.
3. Open `/hooks` in the Codex CLI, or Settings > Hooks in the Codex app, and review and trust the hook definition.
4. Run a short Codex task and check that new lines appear in ~/.numbat/records.ndjson.
5. After each Numbat upgrade, rerun `numbat hook install --agent codex --emit all` with the same options and review trust again.

### Prompt to paste into your agent

```text
Use the repo perplexityai/numbat. Run `numbat hook install --agent codex --emit all` and then `numbat hook status --agent codex` on <target-machine>. Report the status output and the record_type values seen in ~/.numbat/records.ndjson after one short Codex task. Verify that the hook status output reports the Codex hook as installed, and remember that status checks configuration only, not delivery.
```

### Caveat

Hook status verifies configuration only, not execution or delivery, so confirm that new records actually appear in the output file.

Risk, credentials: The live record file captures agent activity from a real user session, so restrict file permissions and review who can read it.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/perplexityai-numbat/monitor-codex-sessions-live/

## How to block a risky Codex action with a custom deny rule with Numbat

Repo: [perplexityai/numbat](https://github.com/perplexityai/numbat) | Difficulty: Advanced | Time: 1 hour | Basis: From the README

Copy a shipped rule, mark it enforce: true, and install it on a Codex pre-action hook.

**Who it is for:** A security lead who has tested a detection in monitor mode and now wants a Codex pre-action block for one behavior.

**The problem:** Shipped rules only monitor, so a confirmed high-risk action such as writing SSH authorized keys still runs unless an operator adds a blocking policy.

**The outcome:** A controlled operator rule directory where the chosen detection denies matching Codex actions, with enforcement decisions written to the record stream.

### Steps

1. Copy the complete shipped YAML for the target rule from the rules directory into a new operator folder, such as ./numbat-policy.
2. Keep the same rule id, add `enforce: true`, and bump the rule version.
3. Run `numbat rules check --rules-dir ./numbat-policy` and fix any validation errors.
4. Run `numbat hook install --agent codex --emit all --rules-dir ./numbat-policy --enforce`. (inferred, check the README)
5. Review and trust the updated Codex hook in `/hooks` or Settings > Hooks, then test with a harmless match and confirm an enforcement record appears.

### Prompt to paste into your agent

```text
Use the repo perplexityai/numbat. Copy the shipped YAML for <rule-id> from rules/ into ./numbat-policy, set enforce: true and a new version, then run `numbat rules check --rules-dir ./numbat-policy`. Report whether validation passes and which rule ids are active. Verify that the enforcement record uses mode "enforce" only for the rule you marked, and that all other shipped rules remain monitor-only.
```

### Caveat

Enforcement applies only to supported synchronous pre-action hooks and only to rules marked enforce: true, so check the coverage matrix before relying on a block.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/perplexityai-numbat/enforce-custom-deny-rule-before-action/