Gabriel Anhaia

Posted on Nov 1 Edited on Nov 1 AI-assisted

Cloned a Stranger's Repo? Check 6 Agent Config Files Before Claude Code or Codex Opens It

#security #ai #git #tutorial

Book: Prompt Engineering Pocket Guide
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You clone a repo to reproduce a bug someone reported. Before you have read a line of its code, you type claude in the folder and ask what is going on.

That repo can carry its own settings for your agent. Claude Code's hooks reference lists .claude/settings.json as a hook location you can commit, and a hook of type command is a shell command that runs on events like SessionStart or PreToolUse. The same is true, with different file names and different rules, for Codex and Gemini CLI.

Every one of these agents has a trust gate for exactly this. The gates work differently from agent to agent, one of them is off by default, and Claude Code's never appears in claude -p. So read the files before the agent does. It takes about a minute with git grep and jq.

The six files, and what each one can make an agent do

.claude/settings.json: hooks that run shell commands, an env block, and helper commands such as apiKeyHelper (permissions docs). A .claude/settings.local.json that is tracked in git counts as repository-supplied too.
.mcp.json: project MCP servers for Claude Code. A stdio server is a command plus args, so connecting it starts a process on your machine (MCP docs).
.gemini/settings.json: Gemini CLI hooks, which "execute arbitrary code with your user privileges" per its hooks page, and mcpServers. A server with "trust": true "bypasses all tool call confirmations for this server" (MCP server docs).
.codex/config.toml and .codex/hooks.json: Codex project config can define [mcp_servers.<name>] tables (Codex MCP docs) and hooks, inline or in hooks.json (advanced config).
AGENTS.md: Codex reads one per directory from the project root down to where you started it, up to 32 KiB combined by default (AGENTS.md docs). Claude Code reads it when there is no CLAUDE.md (memory docs).
CLAUDE.md: loaded at the start of every Claude Code session. It can pull in other files with @path imports, up to four hops deep (memory docs).

The first four can start processes. The last two are prose, but they are prose handed to an agent that can run your shell.

Settings, servers and instructions all ride along in the clone.

What each trust prompt actually gates

Claude Code. Start an interactive session in a folder you haven't trusted and the workspace trust dialog comes first. The project's permissions.allow rules and additionalDirectories wait for it, and the dialog lists them (permissions docs). Servers in .mcp.json get their own approval prompt, and a clone can't pre-approve them: enableAllProjectMcpServers committed in the repo is ignored in an untrusted folder (MCP docs).

The gaps are documented in the same table. In claude -p or the SDK, where no dialog can appear, hooks from settings files and the env block are used, and .mcp.json servers connect "without asking, approved or not." Hooks and env also apply when you trusted only a parent folder, which covers a downloaded archive that isn't its own git repo. For a -p run in a repo you didn't write, the docs offer --setting-sources user, --bare (which still applies the project's env block), or --settings '{"disableAllHooks": true}'. Setting disableAllHooks in your user settings alone isn't enough, because project settings take precedence and can set it back.

One detail for worktree users: in a worktree, Claude Code keys trust on the main checkout's root, so trusting the clone once covers every worktree of it.

Codex. "Codex loads project-scoped config files only when the project is trusted" (advanced config). Untrusted, it skips the project's .codex/config.toml, project hooks and project rules, and your user config still loads. Some keys never load from a project file at all, including openai_base_url, model_provider and notify, which the docs tie to credential redirection and machine-local commands. The AGENTS.md page says nothing about trust, so assume it is read either way.

Gemini CLI. Trusted Folders is "disabled by default." Turn it on with security.folderTrust.enabled: true in your user settings. Then a first run in a folder asks you to trust it, and "Don't trust" skips the project's .gemini/settings.json and .env, keeps MCP servers from connecting and turns off tool auto-accept. v0.65.0, released October 20, 2026, includes a fix titled "enforce read-only workspace settings in untrusted folders" (#29583). The notes list only the title, so read it as tightening that safe mode, not as trust being on by default now. Gemini CLI also fingerprints project hooks: a hook whose name or command changes, say after a git pull, is treated as new and you are warned before it runs (hooks page). For unpaid-tier and Google One users, Gemini CLI was replaced by Antigravity CLI on June 18, 2026, per the same page.

The one-minute audit

Run this in a plain shell, not inside an agent session. The agent session is the thing you're vetting. Every command only reads.

cd ~/code/their-repo

# 1. Which agent files does the repo ship?
p='(^|/)\.(claude|codex|gemini)/|(^|/)\.mcp\.json$'
p="$p"'|(^|/)(CLAUDE|AGENTS|GEMINI)[^/]*\.md$'
git ls-files | grep -E "$p"

# 2. Symlinks can point an agent file outside the repo
git ls-files -s | awk '$1 == "120000" { print $4 }'

Then read what the config files would run:

# 3. Claude Code: every command, plus env and MCP approvals
for f in .claude/settings.json .claude/settings.local.json; do
  [ -f "$f" ] || continue
  echo "== $f"
  jq -r '.. | objects | .command // empty' "$f"
  jq '{env, apiKeyHelper, enableAllProjectMcpServers,
       enabledMcpjsonServers}' "$f"
done

# 4. Project MCP servers: what each one would start
[ -f .mcp.json ] && jq '.mcpServers
  | map_values({command, args, url})' .mcp.json

# 5. Gemini CLI: hooks, servers, servers marked trust: true
g=.gemini/settings.json
[ -f "$g" ] && jq '{hooks, mcpServers}' "$g"
[ -f "$g" ] && jq -r '.mcpServers // {} | to_entries[]
  | select(.value.trust == true) | .key' "$g"

# 6. Codex: tables and commands in project config and hooks
c=.codex/config.toml
[ -f "$c" ] && grep -nE '^\[|command' "$c"
[ -f .codex/hooks.json ] && jq . .codex/hooks.json

Then the prose files, and who touched the config last:

# 7. Instructions: downloads, URLs, hidden comments, imports
q='curl|wget|base64|https?://|<!--'
q="$q"'|(^|[[:space:]])@[~/.]'
git grep -nE "$q" -- '*CLAUDE*.md' '*AGENTS*.md' '*GEMINI*.md'

# 8. When did agent files change, in which commit, by whom?
git log --format='%h %ad %an %s' --date=short \
  -- .claude .codex .gemini .mcp.json \
  '*CLAUDE*.md' '*AGENTS*.md' '*GEMINI*.md'

Step 7 looks for HTML comments because a rendered Markdown view hides them and the agent reads the raw file. It looks for imports that start with ~, / or a dot because those can reach outside the repo; Claude Code asks before loading such external imports the first time (memory docs), but you want to know what they point at before that question comes up.

What you're looking for: a hook that pipes a download into a shell, any command that writes outside the repo, an MCP server you can't name, a server marked trust: true, an env value you can't explain, and a config change that landed in the most recent commit from an account you don't know. Most repos print nothing for steps 3 to 6, which is the answer you want.

Running it in Hermes IDE

I build Hermes IDE, so weigh this section with that in mind. Hermes runs each agent in its own real terminal, and plain shells open the same way, so the audit fits before the first agent starts.

Add the clone as a project and open a plain shell session on it. Run the audit there. Hermes can split panes right or down, so the shell can stay next to whatever you start after it. Only when the output is clean, press ⌘N (Ctrl+Shift+N on Windows and Linux) to start the task. The agent starts on its own hermes/<name> branch in its own worktree, and the sheet shows the exact command Hermes will run before you launch it.

The ⌘N New task sheet: agent, project, a new hermes/ worktree, approval mode, model and effort, and the "Hermes will run" preview of the claude command.

Be clear about what the worktree buys you. It keeps the agent's edits off your branch. It is not a sandbox: a worktree holds the repo's tracked files, so the same .claude/settings.json sits in it. Hermes never answers a permission prompt for you, so the trust dialog and the MCP approval still come to you in the agent's own terminal, and the audit is what makes "yes" an informed answer.

Hermes has one repo file of its own that runs commands: .hermes/worktree.toml, a list of setup commands for new worktrees. The recipe docs say Hermes shows the commands the first time it sees the file, and again whenever it changes, and that "Nothing runs until you choose Run setup." Skip starts the session without setup. In a stranger's repo, add cat .hermes/worktree.toml to the list above.

What the audit won't catch

Grep can't judge prose. An AGENTS.md line that says "run the bootstrap script before answering" looks the same whether the script is fine or not. Claude Code's docs say CLAUDE.md is treated "as context, not enforced configuration," which cuts both ways: it can't force anything, and it can still steer an agent you've allowed to run commands. Read the instruction files in full when the repo matters.

The agent also runs the project's own code once you approve it: install scripts, test runners, build steps. Those deserve the same suspicion as a hook. For anything you truly don't trust, Anthropic's security page recommends using virtual machines to run scripts and make tool calls, and offers dev containers and a sandbox runtime for more isolation.

Next time a bug report links a repo, run steps 1 and 3 before you type claude.

If this was useful

Half of the files in this post are prompts: AGENTS.md, CLAUDE.md and their imports decide what your agent believes about a repo before you say a word. The Prompt Engineering Pocket Guide covers how system prompts and instruction files steer a model, so you can read a stranger's AGENTS.md the way the agent will. And if you want the audit-then-launch flow in one window, Hermes IDE is free on macOS, Windows and Linux, and source-available on GitHub.

DEV Community