agentwhy

https://github.com/karolkozer/agentwhy
Admin
Command-line tool that reads the conversations Claude Code, Codex and GitHub Copilot save on the...
Tokens:11,455
Snippets:69
Trust Score:7.5
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- The npm package is @agentwhy/cli, run with `npx @agentwhy/cli`; the command it installs is `agentwhy`. The npm package `agent-why` is a different project.
- agentwhy needs Node.js 22 or newer.
- Off a terminal (a script, a pipe, CI) name the command, such as `agentwhy check` or `agentwhy start`: a bare `agentwhy` there is a usage error with exit code 2.
- Use `agentwhy doctor --input <session-dir>` to inspect a session record: it prints the structure, never the content. Printing raw transcript lines can expose live secrets.
- agentwhy does not protect files on its own. `agentwhy init` adds deny rules and the `refuse` hook; `refuse` reads the command line, so a path held in a variable or built while a command runs can pass it.

================
CODE SNIPPETS
================
### Terminal finding output example

Source: https://github.com/karolkozer/agentwhy/blob/main/README.md

Example terminal output showing how agentwhy reports a session's actions, including a helper that reached a private file and refused another. Read top to bottom: the agent started a helper, tried to open .env.local (refused), a search reached .env.development and carried the secret, and the helper handed it back.

```text
  the session itself · 4 actions · 1 file reached · wrote the value into files
  └─ Agent 1 · Explore · 2 actions · 1 file reached · 1 refused · gave the value back

  Agent 1 · Explore, asked to "Find why the webhook returns 500"
    ● apps/web/.env.development  in a result  reached
    ○ apps/web/.env.local        named        refused
    ↩ its answer to the session itself carried a value from apps/web/.env.development
```

--------------------------------

### Run agentwhy CLI with npx

Source: https://github.com/karolkozer/agentwhy/blob/main/README.md

One command to start agentwhy in your project. It runs locally on your computer and sends nothing anywhere. A browser page opens showing findings.

```bash
npx @agentwhy/cli
```

--------------------------------

### Example hook output line: Stop says: agentwhy · ROTATE

Source: https://github.com/karolkozer/agentwhy/blob/main/docs/reference.md

Shows the exact line agentwhy writes into the conversation when a protected value is detected. The 'Stop says:' prefix is Claude Code's label for a hook that runs when the agent stops; the rest is agentwhy's message indicating a key from a protected file reached the chat.

```text
  └ Stop says: agentwhy · ROTATE: a value from a protected file is in this conversation. 1 file reached.
```

--------------------------------

### AgentWhy CLI commands overview

Source: https://github.com/karolkozer/agentwhy/blob/main/README.md

Lists the primary AgentWhy CLI commands. Run `npx @agentwhy/cli` to view all conversations in one page; use `check` for a terminal summary, `report --open` to open the newest conversation in a browser, `init` to protect the project and add a chat notice, `protect <path>` to keep a file from your AI across projects, and `notify` to see what you are told when a turn ends.

```bash
npx @agentwhy/cli                  # every conversation in one page, start here
npx @agentwhy/cli check            # the short answer, in the terminal
npx @agentwhy/cli report --open    # the newest conversation, in the browser
npx @agentwhy/cli init             # protect this project and add the chat notice
npx @agentwhy/cli protect <path>   # keep a file from your AI in every project on this computer
npx @agentwhy/cli notify           # what you are told when a turn ends, and where
```

--------------------------------

### Add custom protected paths with init --protect

Source: https://github.com/karolkozer/agentwhy/blob/main/README.md

Adds your own private file patterns to the default list (`.env*`, `*.env`, `.npmrc`, `secrets/`, `.ssh/`, `id_rsa*`). Use this to protect additional paths like `config/*.pem`.

```bash
npx @agentwhy/cli init --protect "config/*.pem"
```

--------------------------------

### Initialize protection with agentwhy init

Source: https://github.com/karolkozer/agentwhy/blob/main/README.md

Adds rules to Claude Code (and Codex if used) to refuse obvious reads and adds a one-line notice when a secret enters the conversation. Shows exactly what it will write and asks first.

```bash
npx @agentwhy/cli init
```

--------------------------------

### AgentWhy CLI commands

Source: https://github.com/karolkozer/agentwhy/blob/main/docs/reference.md

Lists all available agentwhy CLI commands and their purposes. Run without a command in a non-terminal context results in a usage error with exit code 2.

```bash
npx @agentwhy/cli                                # every session on one page, the same as `start`
npx @agentwhy/cli menu                           # a list of the few things to do here; pick one, it runs
npx @agentwhy/cli check                          # what to act on in the last 7 days of sessions
npx @agentwhy/cli start                          # every session on one page, with a report for each
npx @agentwhy/cli report --open                  # the newest session, in the browser
npx @agentwhy/cli report --input <session-dir>   # one session, on stdout; a Codex session file or folder too
npx @agentwhy/cli report --input <id> --open --quiet  # open one session's report, saying only where it is
npx @agentwhy/cli doctor --input <session-dir>   # the record's structure, never its content
npx @agentwhy/cli init                           # set this project up, or undo it
npx @agentwhy/cli init --update                  # move this project's hooks to this version
npx @agentwhy/cli notify                         # what you are told when a turn ends, and when
```

--------------------------------

### Protect a path with agentwhy protect

Source: https://github.com/karolkozer/agentwhy/blob/main/README.md

Protects a specific path (e.g., SSH keys or cloud logins) from AI access across Claude Code's file tools and shell commands. The rule names the place, not just a name. Measured on a Mac in Claude Code's terminal; VS Code, desktop apps, and Windows are not measured yet.

```bash
npx @agentwhy/cli protect "~/.ssh/**"
```
Tokens:
Raw