Three separate topics: what was deliberately left out of this repository, the security properties of the configuration itself, and how each component fails.
This repository was assembled by auditing a live installation and classifying
every item. It is not a copy of ~/.claude.
| Source | Why |
|---|---|
~/.claude/projects/** |
Conversation transcripts (JSONL). Contain full source code, credentials that appeared in output, and private project detail. |
~/.claude/projects/**/memory/*.md |
Per-project memory notes — private architecture, vendor details, business logic. Used as a source for the reasoning in these docs; never copied. |
~/.claude/history.jsonl |
Prompt history. |
~/.claude/sessions/, session-env/, shell-snapshots/, paste-cache/, file-history/ |
Live session state, pasted content, file snapshots. |
~/.claude/telemetry/, cache/, downloads/ |
Generated, machine-local. |
~/.claude/backups/, *.backup-*, .last-* |
Point-in-time copies of the above. |
~/.claude.json |
Per-project harness state, including project paths, and user- and local-scope MCP servers, with any API key in their headers. |
~/.claude/.ponytail-active |
Live mode flag. Publishing it would ship a mode. |
~/.claude/plugins/ (caches, installed_plugins.json, known_marketplaces.json) |
Third-party plugin code plus absolute install paths and commit SHAs. Plugins are named in config/settings.example.json and installed by their own marketplace. |
~/.codex/auth.json |
Credentials. Never read, never copied. |
~/.codex/*.sqlite* (logs_, state_, thread_history_, memories_, goals_, queue_) |
Databases containing conversation history, memories and logs. |
~/.codex/.codex-global-state.json, installation_id, session_index.jsonl, sessions/, attachments/, cache/, models_cache.json |
Machine identifiers and live state. |
~/.codex/rules/default.rules |
A machine-specific command allowlist referencing absolute bootstrap paths under /private/tmp. Useless elsewhere and a bad pattern to copy. |
SSH keys, GitHub tokens, .env files |
Never read. gh auth status output was redacted before it was ever displayed. |
| Source | Why |
|---|---|
~/.claude/hooks/gitnexus/** (5 files) |
Vendored hook code from a tool licensed PolyForm Noncommercial 1.0.0. Redistributing it from an MIT repository would be a licence violation. It also contained the only hard-coded absolute machine path found in the whole audit. |
~/.claude/skills/gitnexus-* (8 skills) |
Same tool, same licence. Installed by the tool's own setup command; not ours to redistribute. |
~/.codex/hooks.json + ~/.codex/hooks/ |
Contained only that tool's hooks. Excluded for the same reason. |
~/.claude/plugins/cache/** |
Third-party plugin source (Superpowers, Ponytail, official plugins). Install them from their own marketplaces. |
The corresponding settings entries were removed from
config/settings.example.json too, so the published configuration does not
reference files it does not ship.
| Source | Published as | What changed |
|---|---|---|
~/.claude/settings.json |
config/settings.example.json |
Absolute /Users/<name>/ paths → $HOME; third-party hook entries and the associated env var removed. |
~/.config/ponytail/config.json |
config/ponytail-config.example.json |
Unchanged (it is one key), published as a template because the value is the policy. |
~/.codex/config.toml |
config/codex/config.example.toml |
Heavily reduced. Removed: bundled-plugin registrations, MCP server commands with absolute app paths, desktop UI preferences, a local marketplace path, and a per-project trust entry naming a private repository. Kept: model, reasoning effort, approval policy, sandbox mode, output token limit, agent concurrency, network policy. |
~/.claude/CLAUDE.md |
examples/CLAUDE.example.md |
Unchanged — audited and found to contain only ~-relative paths. |
<code-dir>/CLAUDE.md |
examples/CLAUDE.directory.example.md |
Unchanged — same audit result. ~/github remains as the directory name; it is a placeholder for wherever you keep code. |
~/.codex/AGENTS.md |
examples/codex-AGENTS.example.md |
Unchanged — audited, no machine-specific content. |
All seven hooks, bin/run-captured, seven judge agents, seven path-scoped
rules, ten skills, and seven Codex agent definitions. Every one was scanned for
absolute paths, usernames, email addresses, hostnames, tokens and project names.
They use ~-relative paths throughout and contain none of those.
$HOME, ~/github, YOUR_USERNAME, YOUR_REPOSITORY, YOUR_API_KEY.
block-destructive-iac.sh, block-git-no-verify.sh/.py and
local-ci-gate.sh/.py are the only hooks that block anything. (The one other
block is permissions.deny in settings.json, covered under trust boundaries
below.) All three are narrow by design:
- IaC guard denies
terraform/tofuapply,destroy,import,taint,untaint,force-unlock, andstate mv|rm|push|replace-provider— including path-qualified binaries, global flags like-chdir=, and occurrences anywhere in a compound command. Read-only operations (init,plan,validate,fmt,show,output,graph,state list|show|pull) are never blocked. - No-verify guard denies hook bypasses on
commit/push/merge/rebase/am/cherry-pick/revert, plus-c core.hooksPath=and settingcore.hooksPath.--get/--unset/--liston that key are allowed. - Local-CI gate denies
git pushand theghcommands that open or update a PR or start a workflow until every required check of the validation plan recorded for the published content has passed. A trivial check recorded as the only evidence no longer passes it: the plan is derived bylocal-ci auto, not chosen, and a required check cannot be relabelled unsupported. A repository's.local-ci.jsoncan add checks or exclude a discovered one with a reason, but only as committed on its base branch: the change under validation cannot edit what validates it. It decides from a file under~/.cache/claude-hooks/local-ci/; a forged record there would pass it, and so would a plan recorded on a machine made to look as if the tools were missing. It stops a careless push, not a deliberate one. The opt-in pre-push hook enforces only whileCLAUDECODEis set, so a command that unsets it is not stopped either. It reads the pushed commits from git's object store only, so no repository-configured filter runs before approval.
All three say, in the denial message, what they are and how to remove them. A guard you cannot identify or disable is a trap, not a safety feature.
Known limits, stated honestly:
- They are not a sandbox. They match command text. A sufficiently indirect invocation (a shell function, a script file, a wrapper that reads the command from a variable) will not match. They exist to stop the obvious mistake, not a determined bypass.
- The IaC guard does not know about
pulumi,cdk deploy,kubectl delete,awsCLI mutations, orhelm uninstall. Extend it if you use those. - The no-verify guard fails open on an unparseable command. The local-CI
gate fails open when
local-cior the scanner it borrows is missing, or the gate times out, and says so in one line.
A workflow is code from the repository, and act runs it in containers on your
Docker engine. local-ci act treats it as untrusted:
- the act process gets an allowlisted environment:
PATH,HOME, locale, Docker connection and proxy variables.GITHUB_TOKEN,GH_TOKEN, cloud and registry credentials are not passed; - an empty
GITHUB_TOKENsecret, and a throwawayHOME,XDG_CONFIG_HOMEandGH_CONFIG_DIR. Without a token act runsgh auth tokenand hands the workflow your own GitHub token. That was found in review and reproduced: with both token variables unset, a probe step saw a 40-charactersecrets.GITHUB_TOKEN; with the empty secret it sees none. (A dummy token was tried first: GitHub then rejected the clone of every public action.); --secret-file,--env-fileand--var-filepoint at an empty file, because act otherwise reads.secrets,.envand.varsfrom the repository;- no actrc: a repository
.actrcor a user-level actrc with content makes it refuse. act applies them to every run, and a cloned repository's could run its steps directly on the host (-P label=-self-hosted), mount it (--bind) or serve files from it. Parsing them to allow "safe" flags was tried and rejected in review: act expands$VARSin actrc lines, so what a parser sees is not what act runs. A user-level actrc cannot be hidden with a throwawayHOMEeither: on macOS act 0.2.97 resolved its config directory under the real~/Library/Application Supportregardless; - a secret-looking file ignored only through global or
.git/infoexcludes makes it refuse, because act copies the work tree by the repository's.gitignorealone; --container-daemon-socket -: job containers do not get the Docker socket (which is root on the host). With--container-options-policy restrict(act 0.2.97 has it) act also refuses workflow-set host mounts and options; with an older act, jobs that set them, and jobs needing those, are skipped.--docker-socketis an explicit opt-in for trusted workflows, and even then it is refused unless the daemon holds no container or volume act did not create: a job with the socket can reuse or delete everything on the daemon, and a compose file with a pinned project name would adopt the developer's own containers and database volumes;- a job that uses Docker is recognised when a step names it and when a step
reaches it through a Makefile target (prerequisites,
$(MAKE)calls, variables) or a repository script, followed transitively. The match is broad on purpose: a false positive leaves one job to remote CI, a miss runs it; - jobs never run on act's default host network. Measured with act 0.2.97 and
Docker Desktop on an arm64 Mac: on the host network a job opened the TCP port
of the developer's published dev database at
127.0.0.1and athost.docker.internal. Each run now creates its own bridge network (removed afterwards) and pointshost.docker.internalandgateway.docker.internalat the job container; there, the same probe found both closed and the internet reachable. Docker Desktop's host-gateway address (192.168.65.254) still answered: a workflow that names that internal address on purpose can reach host ports. So didhost.docker.internalfrom a job with its owncontainer:image, because act gives such a container only the workflow's options, not--container-options(measured the same way);localhostwas closed there too. Neither name exists on GitHub's Linux runners, so only a workflow written to reach the developer's machine uses them. That is a deliberate act by the repository's own code, whichautoalready runs on the host as its local checks (below). Jobs withservices:are not run, since they expect the host network; - the socket check covers every job, not only those recognised as Docker
users:
--docker-socketmounts it into all of them, so all are refused on a daemon that holds anything act did not create (itsact-toolcachevolume and hash-named job containers), and the check is repeated just before act starts; - deploy, release and publish jobs, jobs with a deployment environment or write
permissions, steps that push, publish, sync files out or call a cloud CLI,
and any job that needs one of those (act runs a job's
needs:too) are never run; - act's default
.gitignorehandling keeps ignored files (such as.env) out of the copied workspace.
The classification reads names, steps and keys. A workflow can hide a deploy
behind an innocent name and a script; local-ci act --list and
local-ci auto --plan-only show what will run before anything does, but the
automatic flow does not stop to ask. The isolation above is what limits the
damage when it does: no credentials, no socket, no host mounts. Mounting the
Docker socket gives a job root on the machine, so --docker-socket is the
user's decision, never the agent's; the plan says so where it applies.
local-ci auto runs the check commands the repository defines — npm run
scripts, Makefile targets, scripts/verify*, pre-commit run, uv run
(which installs dependencies), terraform init (which fetches providers) — on
the host, with the user's environment, and without act's isolation. A
discovered command that starts Docker through a Makefile target or a script
is the exception: on the developer's daemon a pinned compose project adopts
their containers and down -v deletes their volumes, so it is reported
unsupported unless the repository declares it in .local-ci.json. That is the
same trust as running the repository's tests by hand, and it is now automatic:
the Stop hook asks for it after any session that changed the repository. A
repository you would not run make test in is one you should not have the agent
edit with this hook installed (or set LOCAL_CI_AUTO=0); allowlisting
local-ci auto in the permission settings approves every command it discovers.
act jobs are the isolated part: workflow code runs only in containers, never on
the host.
skill-install-guard.sh/.py blocks nothing outright. It returns ask, so a
skill or plugin install, update or removal, or a write into a skill directory,
waits for the user's answer in the permission prompt. A third-party skill is
persistent instructions loaded into later sessions, and the skills CLI
installs one without asking when an agent runs it: it detects Claude Code and
goes non-interactive, -g links the skill into every detected agent's
directory, and a blocked write still printed "Done!" with exit 0
(benchmarks §10).
Known limits:
- The same as the deny-guards: it matches command text. A path built at run
time (a variable, a glob,
$(…)), a script file, an interpreter (python -c,node -e, or a here-doc fed to one),jqrewritingsettings.json, or a download tool it does not know is not caught, and it fails open on a parse error. - Text is data, as it is to the shell. A here-doc body, a comment or a quoted
string that mentions
skills add(a PR body, a commit message, a document) is not asked about. A here-doc fed to a shell is asked about, and so are$(…)and backticks outside single quotes. The first version tokenized here-doc bodies as commands and asked before agh pr create. That command is now a row in the decision table. An adversarial review found 20 shell forms it missed (line continuations, comments, loops,xargs,find -delete,cdthen a relative path,cp -r skills ~/.claude/, and others) plus settings edits and letter case; all are now covered and in the decision table (benchmarks §10), which says how many forms were tried, not that none remain. - An approved prompt is an approval. The guard records nothing and cannot tell a considered yes from a reflexive one.
skills useinstalls nothing, but what it prints is still third-party instructions in context. The policy inCLAUDE.mdasks for official sources and a read before following; nothing enforces that.
- Credentials never enter prompts, logs, indexes, or delegated packets.
- Terraform state,
state pullandshowoutput contain secrets and must never be pasted into context, a review packet, or a subagent prompt (rules/infrastructure.md). - The graph bootstrap strips LLM API keys from the environment before invoking the graph tool, so a build cannot make a paid API call even if the tool would otherwise try.
- Review packets are explicitly required to have secrets stripped from diffs,
logs and config before dispatch (
skills/adversarial-jury/packet-template.md). - The security judge is told never to retrieve a secret value as proof, and never to write a working exploit.
Repository text, web pages, package metadata and tool output are treated as evidence, never as instructions. Every judge agent is told this explicitly in its own prompt, because a judge reads attacker-influenceable content (diffs, logs) with an instruction-shaped mind.
The one known defect in the upstream stack, reproduced directly.
What it is. The plugin's active mode lives in a single file under the Claude
config directory. It is machine-global and shared by every concurrent session.
Typing /ponytail-review writes review into it, and while set, the plugin's
subagent hook injects the "delete code" persona into subagents — including
reviewers whose purpose is the opposite lens, in that session and any other
session running at the same time.
Why it matters. A simplification persona reaching a security or correctness reviewer inverts what that reviewer is for. Because the file is shared, a review started in one terminal can quietly alter a judge in another. Nothing fails loudly; the effect is a bias.
Three independent containment layers. Do not remove one assuming another covers it:
PONYTAIL_SUBAGENT_MATCHERin settings — a never-matching sentinel (^ponytail-subagents-disabled$) that stops the ruleset reaching any subagent regardless of flag state.⚠️ An invalid regex fails open and injects, so any replacement must be a valid regex that matches nothing.hooks/ponytail-guard.shwired toStopandSessionEnd, so an interrupted or failed review still cleans up.clearremoves only areviewflag and leaves a deliberately-setlite/full/ultraalone;forceclears unconditionally.- The plugin's own
SessionStarthook, which clears the flag when the configured default isoff.
The general lesson — prefer stateless mechanisms; where state is unavoidable, assume it leaks and contain it in layers — is why the dead-code audit was designed with no state at all.
- Hooks execute arbitrary local code on every matching tool call. Read every
hook in
hooks/before installing it. That is not a formality: a hook is the highest-privilege extension point here. - Plugins and marketplaces are third-party code that loads into every
session.
config/settings.example.jsonnames six plugins from three marketplaces. Evaluate them yourself; being listed here is not an audit. - Remote MCP servers receive your queries. The screen-reference servers
(Refero, Mobbin) and 21st.dev's component-research server are at user scope.
Every query leaves the machine. With 21st.dev at user scope, substantial
frontend work in any repository sends product and section descriptions to it
unasked, because
frontend-qualitymakes that research a step; disable the server for a project that must not send them. A keyed server's key sits in plain text in~/.claude.json.permissions.denyinsettings.jsonblocks 21st.dev's generation, publishing and account-write tools, includingrecord_inspiration_feedback, which would send accept and reject signals under the key. It matches by server and tool name, so a server connected under another name, or a renamed tool, is not blocked. - Skills and agents are instructions, not code. They cannot execute anything on their own, but they do shape what the model does with tools it already has.
- The installer writes only under
$HOME/.claude(or$CLAUDE_CONFIG_DIR) and backs up anything it would overwrite.
| Component | Fails how | Consequence | Mitigation |
|---|---|---|---|
| Deny-hooks | Fail open on unparseable input | A destructive command could pass | Narrow patterns, fast-path guard, denial names itself |
| Deny-hooks | False positive on an innocent command | Legitimate work blocked | shlex parsing; -n in a quoted message is not a flag; removal instructions in the message |
| Local-CI gate | Misses a push in a script, or fails open | Unvalidated work reaches remote CI | Opt-in pre-push hook covers every agent git push; CLAUDE.md policy |
| Local-CI gate | Stale or forged evidence | A push passes without a real check | Evidence keyed by content, so stale never matches; forging needs a deliberate write to the cache |
local-ci act |
Misclassifies a deploy job as runnable | A workflow step runs locally with no secrets and no Docker socket | Name, step, environment and permission checks; --list first |
local-ci act |
Environment failure looks like a test failure, or the reverse | Wrong signal | Unsupported only when no step failed; the log path is printed |
local-ci auto |
Treats a job as covered by a local check when it is not | A workflow-only behaviour is not run locally | Equivalence only for a plain job whose every command is a required local command line; remote CI still runs it |
Stop hook (local-ci-auto) |
Holds a stop the user did not want validated, or content changes on every run | Extra turns | At most once per content state and three times in a row per user turn; never for a turn that changed nothing; LOCAL_CI_AUTO=0 |
| Skill-install guard | Fails open, or misses an indirect write | A skill is installed without a prompt | The CLAUDE.md policy; the guard covers the CLI, the file tools and common shell writes |
| Skill-install guard | Asks on a hand edit of an installed skill | One extra prompt | Intended: that is a persistent change too. Reads and skills find/use never ask |
| Advisory hooks | Fail open, silently | A hint is missed | Nothing depends on the hint |
| Advisory hooks | Fire too often | Nagging, wasted tokens | Once per session per class; state reset on compact/clear |
read-budget-advisor |
State shared across agents | Wrong "you already read this" hints | Keyed by session and agent id |
run-captured |
Capture file not writable | Command runs uncaptured | Explicit fail-open path, message on stderr |
run-captured |
Summariser throws | Result could be hidden | Falls back to a raw tail plus exit code |
run-captured |
One enormous single line | Summarised in memory | Documented limit |
run-captured |
Used on a server or a prompt | Hangs | Documented: not for interactive or long-running commands |
| Graph bootstrap | Build fails or times out | No graph | Fails open, deletes the partial output it created, caches the failure for 24 h |
| Graph bootstrap | Recursion | Infinite loop | Env guard, command-name check, per-repo lock file |
| Graph bootstrap | Repo too large | Long stall | Hard budget, skip above a file-count ceiling |
| Ponytail flag | Leaks to subagents / other sessions | Wrong persona in a reviewer | Three containment layers (above) |
| Semantic triggers | Model does not notice them | Review silently skipped | The reporting requirement — a missing report is visible |
| Reporting requirement | Model claims a review it did not run | Undetectable from the transcript alone | Unmitigated. Findings must cite file and line, which makes fabrication checkable, but nothing enforces it |
| Judges | All agree and are all wrong | False confidence | Evidence ladder; jury-arbiter never counts votes; "a clean jury is not proof" is written into the skill |
| Judges | Hallucinate a finding | Wasted fix effort | Every finding needs a failure scenario and a location; unsupported claims are rejected |
| Path-scoped rules | Glob does not match a project's layout | Rule never loads | Check the paths: frontmatter against your tree |
| Installer | Overwrites a customised file | Local changes lost | Dry-run default, backup before every overwrite, refuses to merge settings |
The semantic triggers and the reporting requirement are not enforced by anything. A model that does not evaluate the triggers, or that reports a review it did not perform, produces a transcript indistinguishable from a correct one apart from the content of the findings themselves.
This is accepted deliberately — see why-this-setup.md for why a hook cannot do this job — but it is a real limitation, not a solved problem. The partial mitigation is that findings must carry file and line, and rejections must carry reasons, both of which a human can check against the diff.