Cloned a Stranger's Repo? Check 6 Agent Config Files Before Claude Code or Codex Opens It
- 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
1. .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.
2. .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).
3. .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).
4. .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).
5. 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).
6. 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.
!A cardboard box labelled as a cloned repo, opened under a large magnifier, with small gears, plugs and a folded note hidden among the files
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 Hermes New task sheet with a refund-endpoint task typed, chips for Claude Code, the orders-api project, a new hermes/ worktree, Accept edits, model and effort, and a preview of the claude command Hermes will run
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.
1 reaction · 1 comment
Mentions
Cloned a Stranger's Repo? Check 6 Agent Config Files Before Claude Code or Codex Opens It - 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 1. .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. 2. .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). 3. .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). 4. .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). 5. 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). 6. 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. !A cardboard box labelled as a cloned repo, opened under a large magnifier, with small gears, plugs and a folded note hidden among the files 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 Hermes New task sheet with a refund-endpoint task typed, chips for Claude Code, the orders-api project, a new hermes/ worktree, Accept edits, model and effort, and a preview of the claude command Hermes will run 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. 
Free GitHub tool: pick a value out of JSON with jq jq is a free, MIT-licensed command-line JSON processor. It is handy when an API or tool gives you structured JSON and you only need one field. On macOS with Homebrew, install it with `brew install jq`. Try this harmless example: `echo '{"name":"Mark","active":true}' | jq -r '.name'` The result is `Mark`. Here `.name` selects the field and `-r` prints the string without JSON quotation marks. jq runs locally; this use needs no account, paid API or subscription. Official repository and licence: jqlang/jq Manual: jqlang.org
jq turns a wall of JSON into something you can read Pipe your API response through it and spot the problem in seconds jqlang/jq
رد الـ API راجعلك JSON سطر واحد طويل ومش عارف تقرا منه حاجة؟ جرّب jq 🧩 🛠️ «أدوات وحاجات تقنية» | الجزء 15 الأداة: jq إيه هي؟ (من الموقع الرسمي) • command-line JSON processor خفيف ومرن • زي sed بس للـ JSON: تقطّع وتفلتر وتعمل map وتحوّل الداتا بنفس سهولة sed و awk و grep مع النص • مكتوبة بـ C، ومن غير أي runtime dependencies: binary واحد تنزّله وتشغّله • رخصتها MIT، وآخر إصدار 1.8.2 أوامر هتستخدمها كل يوم: • تعرض رد الـ API مترتّب ومقروء: curl -s $URL | jq '.' • تطلّع field واحد من كل عنصر في الـ array: jq '.[].name' data.json • تفلتر بشرط، و -r بتطلّع نص من غير علامات تنصيص: jq -r '.[] | select(.status=="down") | .name' data.json • تغيّر شكل الداتا وتاخد الحقول اللي محتاجها بس: jq -c 'map({name, ms})' data.json • تعدّ العناصر: jq 'length' data.json ولو عايز تجرّب من غير ما تنزّل حاجة، فيه playground أونلاين على الموقع الرسمي (Try online). رأيي: jq من الأدوات اللي بتوفّر وقت كل يوم، خصوصًا مع curl وفي الـ CI scripts. ابدأ بـ '.' و select، والباقي هييجي لوحده. 📚 المصادر: • jq — الموقع الرسمي: jqlang.org • jq — Manual: jqlang.org • jq — Playground: play.jqlang.org • jq — GitHub: jqlang/jq إنت بتقرا الـ JSON في الـ terminal إزاي: jq ولا python -m json.tool ولا بتفتحه في الـ editor؟ قولّي في الكومنتات 👇 #jq #JSON #CLI #DevTools #Productivity #SoftwareEngineering #برمجة #أدوات_وحاجات_تقنية
jq: a free tool for reading JSON in the terminal JSON files can be hard to scan when they grow. jq reads and filters them in the terminal. On a Mac with Homebrew already installed, run: brew install jq In a project that has a package.json file, try: jq ".version" package.json That prints the version field. If the field is missing, jq returns null. This is a read-only example. jq is free and open source under MIT. Its README and release downloads are here: jqlang/jq
Like sed, but for JSON A tiny C-based CLI lets you slice, filter and transform JSON right from your shell. 🍒 Built by the jqlang team jqlang/jq #opensource #cprogramming
jq: the sed-style tool for JSON in your terminal A tiny C-based CLI lets you slice, filter and transform JSON right from your shell. Grab a single field from a massive file with one short filter, and use prebuilt standalone binaries with zero runtime dependencies. Built by the jqlang team: jqlang/jq