Dotfiles

Appearance

Agent Config Boundaries ​

Codex and Claude Code configuration is split between managed workstation defaults and project-local overrides. Keep that boundary explicit so repo-specific MCP servers, tokens, OAuth state, and session data do not leak into shared dotfiles.

Managed Global Config ​

The rendered global Codex config comes from home/dot_codex/config.toml.tmpl and applies to every supported host lane. Use it for shared defaults, trusted project paths, required profile shape, and MCP servers that are safe as global workstation capabilities.

The managed global MCP set is intentionally small:

  • openaiDeveloperDocs for OpenAI and Codex developer documentation.
  • context7 for current third-party package and framework documentation.
  • Disabled optional entries such as Playwright and Figma, with no static secrets.

Do not add repo-specific or token-scoped servers, such as GitHub MCP, to the global template. scripts/validate-codex-config.py rejects forbidden global MCP servers and static secret-bearing MCP fields.

The rendered global Claude Code config comes from home/dot_claude/settings.json.tmpl and home/dot_claude/CLAUDE.md.tmpl. Use those files for workstation-wide Claude behavior, read-deny boundaries, and global operating instructions only. Do not put env, mcpServers, API keys, OAuth material, or project-specific policy in the managed Claude templates.

Claude local state is runtime-owned and must stay ignored, including ~/.claude/settings.local.json, ~/.claude/.env, ~/.claude/.credentials.json, projects, sessions, todos, cache, logs, state, shell snapshots, IDE state, and SQLite files.

Project-Local Config ​

Repo-local MCP entries and token env files belong in ignored files under the project root:

text
.codex/config.toml
.codex/.env
.claude/.env

Codex supports project-scoped .codex/config.toml files for trusted projects. Project-local config is the right place for optional servers that are useful only while working in this repository. Keep required = false unless losing that server should block Codex startup for this project.

Store credentials only in ignored local env files. codex-env loads shared ~/.config/agents/.env first and then the nearest project .codex/.env, so a project token can override or supply a variable without entering tracked dotfiles.

Claude Code should launch through claude-env. It loads the shared ~/.config/agents/.env first and then the nearest project .claude/.env, bounded by the Git root. Project-local Claude settings that Claude writes, such as .claude/settings.local.json, stay ignored and are not managed by chezmoi.

Never put real API keys, bearer tokens, PATs, OAuth credentials, or session state in tracked TOML or Markdown examples. Use bearer_token_env_var or env_http_headers when an MCP server needs credentials.

Anthropic And Claude Docs MCP ​

Research checked on June 14, 2026 against the current Claude Code CLI and official Claude Code documentation confirmed the managed settings, permissions, and CLI flag surface used here. The official Claude Code documentation MCP endpoint remains suitable for project-local Codex research:

toml
[mcp_servers.claudeCodeDocs]
enabled = true
required = false
url = "https://code.claude.com/docs/mcp"
startup_timeout_sec = 10
tool_timeout_sec = 120

This is suitable as an optional project-local Codex MCP server when debugging Claude Code behavior. It is not a general Anthropic API or SDK documentation server. Do not add it to the managed global Codex template unless a separate issue records a broader workstation decision.

The endpoint is public and does not need an API key. If a future authenticated Anthropic MCP server is adopted, put the token name in .codex/config.toml and the token value in .codex/.env, for example:

toml
[mcp_servers.exampleAnthropicServer]
enabled = true
required = false
url = "https://example.invalid/mcp"
bearer_token_env_var = "ANTHROPIC_MCP_TOKEN"
startup_timeout_sec = 10
tool_timeout_sec = 120
sh
ANTHROPIC_MCP_TOKEN=replace-me-in-local-env-only

Do not use untrusted third-party "Anthropic docs" MCP servers by default. A new third-party server needs a separate queue item that records its source, maintenance status, auth model, security tradeoffs, and why Context7 or official docs are not enough.

Lookup Policy ​

Use these lookup paths for Anthropic and Claude work:

  • Claude Code behavior, hooks, MCP setup, settings, Agent SDK, and CLI details: use the optional claudeCodeDocs MCP server when it is configured, or web search against official code.claude.com / docs.anthropic.com pages.
  • Anthropic SDK and library APIs: use Context7 for official anthropic-sdk-* package docs, then confirm unclear behavior against official Anthropic documentation.
  • Anthropic API behavior, model availability, release notes, pricing, deprecations, and Claude.ai product behavior: use current official Anthropic or Claude documentation through web search. The Claude Code docs MCP does not cover the full API surface.
  • OpenAI, Codex, Responses API, Agents SDK, and OpenAI MCP behavior: use the OpenAI developer docs MCP.

Checks ​

After changing managed Codex config, run:

sh
python3 scripts/validate-codex-config.py

After changing agent launchers, Claude templates, editor tasks, shell aliases, or host boundaries, run the source-only smoke test:

sh
scripts/smoke-test.sh --source-only

For docs-only updates to these boundaries, run the configured docs build or docs check and confirm ignored local agent files stay ignored:

sh
pnpm docs:build
git check-ignore -v .codex/config.toml .codex/.env .codex/.env.local .claude/.env .claude/settings.local.json

References: