Read Only

---
name: read-only
description: Add a curated set of read-only permission rules -- file reads, directory listings, content search (grep/glob), git inspection, and system checks -- to a Claude Code settings.json allowlist so safe reads stop triggering permission prompts. Local read-only by default; outbound reads (WebFetch, WebSearch, registry lookups) and secret-bearing reads (env dumps) are offered only as explicit opt-ins. Trigger when the user says "read-only", "/read-only", "pre-approve read operations", "allow all read-only commands", "stop asking me about ls/cat/grep", or asks to add safe read permissions to a settings file. Do not use for write or install permissions, or for mining transcripts to find which commands actually prompt most -- route those to a dedicated settings or transcript-analysis skill (e.g. update-config, fewer-permission-prompts) when one is installed.
---

# Read-Only

Add a known-safe catalog of read-only permission rules to a Claude Code settings file in one pass: merge into the existing JSON, never clobber, never touch `deny` or `ask`, and confirm exactly what was added.

## Step 1 -- Pick the target file

If the user named a scope, use it. Otherwise ask once, recommending the first option:

1. **User global** `~/.claude/settings.json` (Recommended) -- approve once, benefit in every project. Broadest convenience, broadest blast radius: the catalog is low-risk, not zero-risk (see the redirection caveat in Step 4), so users who work in sensitive repos may prefer option 3.
2. **Project shared** `.claude/settings.json` -- committed; teammates inherit it.
3. **Project personal** `.claude/settings.local.json` -- this machine, this repo only; smallest blast radius.

In a non-interactive context (no user available to answer), default to `.claude/settings.local.json` -- smallest blast radius.

## Step 2 -- The catalog

Rule syntax: bare `Tool` allows the whole tool; `Bash(cmd:*)` is a prefix match; `Bash(cmd)` is an exact match. Exact matches are used below wherever the command's *flags* can mutate (e.g. `git branch -d`).

### Core native tools (always add)

```
"Read", "Glob", "Grep"
```

These cover file reads, directory/pattern listings, and content search natively. If the user wants reads scoped (e.g. exclude secrets), offer path forms like `"Read(./src/**)"` instead of bare `"Read"`, and remind them `deny` rules such as `"Read(./.env)"` always win over `allow`.

### File and directory inspection (always add)

```
"Bash(ls:*)", "Bash(cat:*)", "Bash(head:*)", "Bash(tail:*)",
"Bash(wc:*)", "Bash(file:*)", "Bash(stat:*)", "Bash(tree:*)",
"Bash(du:*)", "Bash(df:*)", "Bash(diff:*)", "Bash(realpath:*)",
"Bash(dirname:*)", "Bash(basename:*)", "Bash(pwd)",
"Bash(shasum:*)", "Bash(md5:*)"
```

### Search (always add; `find` is opt-in)

```
"Bash(grep:*)", "Bash(rg:*)", "Bash(fd:*)", "Bash(ag:*)"
```

`Bash(find:*)` is **opt-in with a stated caveat**: `find` supports `-delete` and `-exec`, which mutate. A prefix rule cannot see mid-command flags, so allowing `find:*` allows those too. Offer it, name the risk in one line, and add it only if the user accepts.

### Git inspection (always add)

```
"Bash(git status:*)", "Bash(git log:*)", "Bash(git diff:*)",
"Bash(git show:*)", "Bash(git blame:*)", "Bash(git shortlog:*)",
"Bash(git describe:*)", "Bash(git ls-files:*)", "Bash(git rev-parse:*)",
"Bash(git grep:*)", "Bash(git reflog:*)", "Bash(git ls-tree:*)",
"Bash(git rev-list:*)", "Bash(git diff-tree:*)", "Bash(git merge-base:*)",
"Bash(git cat-file:*)", "Bash(git config --list)", "Bash(git config --get:*)",
"Bash(git config --global --get:*)", "Bash(git remote -v)",
"Bash(git stash list)", "Bash(git branch)", "Bash(git branch -a)",
"Bash(git branch -vv)", "Bash(git tag)", "Bash(git tag --list:*)",
"Bash(git worktree list)"
```

Deliberately exact (not `:*`) for `branch`, `tag`, `stash`, `remote`, `config`: their prefix forms reach mutating subcommands (`git branch -d`, `git tag v1`, `git stash pop`, `git remote add`, `git config user.name x`).

Prefix matching is strict about *flag order*: `Bash(git config --get:*)` does not match `git config --global --get user.name`, which is why the `--global --get` variant is its own rule. If a read-only git command still prompts later, the cause is usually a flag appearing before the matched prefix -- add that exact variant rather than widening to `git config:*`.

### System and environment inspection (always add)

```
"Bash(which:*)", "Bash(type:*)", "Bash(whoami)", "Bash(id)",
"Bash(uname:*)", "Bash(hostname)", "Bash(date)", "Bash(uptime)",
"Bash(ps:*)", "Bash(sw_vers)"
```

`date` and `hostname` are exact because their argument forms can mutate (set the clock, rename the host). `env` and `printenv` are deliberately *not* here -- they are read-only but secret-bearing; see the opt-in list below.

### Optional add-ons (offer, do not add silently)

The default catalog above is **local** read-only. Everything in this list crosses one of two extra lines -- it sends data *outbound* or it can expose *secrets* -- so each item is added only on explicit opt-in, with its risk named in one line when offered.

- **Environment variable reads**: `"Bash(env)"`, `"Bash(printenv:*)"` -- read-only but secret-bearing: the environment commonly holds API keys and credentials, and pre-approving the dump removes the permission gate that would otherwise flag an unexpected read.
- **Web reads**: `"WebFetch"`, `"WebSearch"` -- outbound: they send query/URL content to external services.
- **Package listings**: `"Bash(npm ls:*)"`, `"Bash(pip list)"`, `"Bash(pip show:*)"`, `"Bash(brew list:*)"`, `"Bash(composer show:*)"` (local); `"Bash(npm view:*)"` (outbound -- queries the npm registry).
- **Data inspection**: `"Bash(jq:*)"`, `"Bash(yq:*)"`, `"Bash(sort:*)"`, `"Bash(uniq:*)"`, `"Bash(cut:*)"`.
- **Project-specific read CLIs** the user mentions (e.g. wp-cli: `"Bash(wp post list:*)"`, `"Bash(wp option get:*)"`). Add only the read verbs (`list`, `get`), never the bare tool prefix.

Deliberately **excluded** from every tier: `echo`, `printf`, `sed`, `awk`, `tee`, `xargs`, pagers (`less`, `more` -- interactive). The first group writes trivially (redirection or `-i`); `xargs` executes arbitrary commands.

## Step 3 -- Merge and write

1. Read the target file. If it does not exist, start from `{}`. If it exists but is not valid JSON, stop and report -- do not "fix" a broken settings file as a side effect.
2. Add rules to the allowlist array the file *already uses*. The current schema is `permissions.allow`; if the file instead has a legacy or root-level allow key (e.g. `allowedTools`), append to that existing array rather than introducing a second list the harness may ignore. Only create `permissions.allow` fresh when no allowlist exists at all. Preserve every other key untouched, including `deny` and `ask`.
3. Append catalog rules **not already present**. Dedupe by exact string; also skip a rule when an existing broader rule obviously covers it (e.g. `"Bash(git:*)"` present means skip all git rules -- note this in the confirmation rather than narrowing their rule).
4. Settings files are plain JSON: no comments, no trailing commas. Validate before saving (`python3 -m json.tool` or `jq .`); write only if validation passes.

## Step 4 -- Confirm

One compact block: the file path, count added, count skipped as already covered, and any opt-in caveats accepted. Then state the one honest limitation of the whole approach:

> Prefix rules match the start of the command, so an allowed read can still write via shell redirection (`cat a > b` matches `Bash(cat:*)`). This set is low-risk, not zero-risk; keep `deny` rules on sensitive paths (e.g. `"Read(./.env)"`).

## When NOT to fire

- "Allow `npm install`" / "stop asking about `git push`" -- those are write/network permissions. Route to a general settings-configuration skill (e.g. **update-config**) if one is installed; otherwise decline and point the user at their settings file directly. Do not stretch this skill to cover them.
- "Why am I getting so many permission prompts?" with no rule list in mind -- they want their *actual* usage mined. Route to a transcript-analysis skill (e.g. **fewer-permission-prompts**) if one is installed; otherwise offer this skill's static catalog as the fallback.
- A single live permission dialog the user wants approved once -- that is the dialog's own "always allow" option, not a settings edit.

## Safety rules

- Never remove or rewrite existing rules, and never touch `deny`/`ask` -- `deny` wins over `allow` by design and may be load-bearing.
- Adding permissions is the *only* write this skill makes. No reformatting the rest of the file, no sorting their existing rules, no cleanup.