Permission suggestions

hansard permissions suggest checks the shell commands your agents ran against your Claude Code Bash(...) allow rules. It shows how many commands your current rules would have approved automatically, which frequent commands they miss, and which rules would cover them. Use it to cut down on permission prompts with rules based on what you actually run. Permission suggestions are available only from the CLI.

CLI: hansard permissions suggest

Get suggestions from the CLI

Archived shell commandsFrom every harness, the last 90 days by default

ReplayAgainst your Claude Code Bash allow rules

Suggested rulesFrequent commands your rules do not cover yet

Run the command from your project folder, so it also reads that project’s Claude Code settings:

cd ~/code/app
hansard permissions suggest

By default, Hansard checks every archived shell command from the last 90 days, from every harness. Commands from Codex and other harnesses count too, so the suggestions reflect how you work across agents.

To focus on one project, one harness, or a different period:

hansard permissions suggest --repo github.com/example/app
hansard permissions suggest --provider claude_code --since all
hansard permissions suggest --min-count 20

Option	Default	Effect
`--settings <path>`	See below	Claude Code settings file to read rules from. Repeat it to read several files.
`--provider <harness>`	All harnesses	Only commands from that harness. Accepts the same names as `hansard history`.
`--since <window>`	`90d`	How far back to look, such as `30d`, or `all`.
`--repo <repo-or-path>`	All projects	Only commands from that repository, scope, or path.
`--min-count <n>`	`5`	Suggest a rule only for commands used at least this many times.
`--json`		Print coverage, uncovered commands, suggestions, and commands to review as JSON.

Without --settings, Hansard reads these files when they exist:

~/.claude/settings.json
~/.claude/settings.local.json
.claude/settings.json in the current folder
.claude/settings.local.json in the current folder

Sessions from machine status probes, such as usage trackers, and Codex internal action assessments are left out.

Read the output

The report has up to four sections:

Section	What it shows
Coverage	How many sessions were checked, how many shell calls and command segments your rules would approve, and how many `Bash(...)` rules were found.
Top Uncovered Commands	The 20 most frequent commands no rule covers, with a count and the shortest example.
Suggested Rules	A `Bash(<command>:*)` rule for each uncovered command used at least `--min-count` times.
Used Often But Not Suggested (Review Manually)	Frequent commands Hansard does not suggest a rule for, with the reason.

A report for a small project might look like this:

Coverage
  ✓ Sessions scanned   42
  ✓ Coverage           310/1204 calls (25.7%) would be auto-allowed; 402/1650 segments
  ✓ Rules loaded       6 Bash(...) rules
Top Uncovered Commands
  ✓ npm test           188, npm test
  ✓ rg                 140, rg TODO
  ✓ git diff           97, git diff
Suggested Rules
  "Bash(npm test:*)"
  "Bash(rg:*)"
  "Bash(git diff:*)"
Used Often But Not Suggested (Review Manually)
  ✓ rm                 12, deny-suggest head, rm -rf dist

Hansard splits each shell call into its separate commands, for example at &&, ;, and pipes. A call counts as approved only when a rule covers every command in it. A rule such as Bash(git diff:*) covers a command that starts with git diff followed by a space or nothing else.

Commands go to manual review for these reasons:

Reason	Commands
`deny-suggest head`	Commands that can destroy data or stop processes: `rm`, `sudo`, `dd`, `mkfs`, `shutdown`, `reboot`, `kill`, `pkill`, and `killall`.
`shell builtin`	Shell keywords such as `exit`, `read`, and `true`, which never run as a command on their own.
`unresolvable variable head`	Commands that start with a variable, such as `$EDITOR`, whose real command is unknown.

When the report says some shell calls had no recoverable command text, those records came from harnesses or older sessions that did not save the command. They count as calls but not as approved.

Add rules to Claude Code

Choose where the rules apply. Use ~/.claude/settings.json for every project, or .claude/settings.json in the repository to share them with the project.

Add the rules you want to the permissions.allow list:

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(rg:*)",
      "Bash(git diff:*)"
    ]
  }
}

Run hansard permissions suggest again. The new rules appear under Rules loaded, and their commands leave Top Uncovered Commands.

Hansard never edits your Claude Code settings. See Claude Code settings for the full permission rule syntax.