~/.agents/ - global AI coding agent config

Note: this repo is a depersonalized example snapshot of my private ~/.agents repo, published alongside the blog post How to configure your local coding AI agents once. It is not actively maintained.

Single source of truth for personal global agent configuration across Claude Code, Codex, and GitHub Copilot CLI. Everything an agent reads at the user-level lives here and is exposed to each tool through a symlink, an import, or because the tool already reads ~/.agents/ natively.

This repo is for the global, machine-personal layer. It is NOT for per-project agent config (those AGENTS.md / CLAUDE.md files live in each project repo).

Background: How to configure your local coding AI agents once.

Layout

~/.agents/
├── README.md                         # this file
├── AGENTS.md                         # the actual global agent context
├── CLAUDE.md                         # one-liner: @AGENTS.md (compat for Claude Code)
├── skills/                           # personal skills (Claude + Codex + Copilot CLI)
│   ├── api2cli/
│   └── jira-acli/
├── settings/
│   └── claude.settings.template.json # sanitized Claude settings (no machine paths)
├── scripts/
│   ├── setup-symlinks.sh             # wires Claude + Codex at this folder
│   └── strip-claude-settings.sh      # regenerates the settings template
└── .backups/                         # auto-created by setup-symlinks.sh

How each tool reads from here

Tool	What it reads	How
Claude Code	~/.claude/CLAUDE.md and ~/.claude/skills/	symlinks created by setup-symlinks.sh
Codex	~/.codex/AGENTS.md and ~/.codex/skills/	symlinks created by setup-symlinks.sh
Copilot CLI	~/.agents/skills/	native, no symlink needed (see Copilot configuration basics)

CLAUDE.md is a one-liner containing @AGENTS.md. Claude Code does not read AGENTS.md natively yet (tracked at anthropics/claude-code#6235). The @ import is Anthropic's documented workaround.

First-time setup on a new machine

1. Clone this repo to ~/.agents/.

2. Inspect scripts/setup-symlinks.sh. It is idempotent and backs up any pre-existing real files to ~/.agents/.backups/<timestamp>/ before replacing them with symlinks.

3. Run it:

   ~/.agents/scripts/setup-symlinks.sh

4. Apply the Claude settings template:

   # If you have no ~/.claude/settings.json yet:
   cp ~/.agents/settings/claude.settings.template.json ~/.claude/settings.json
   # If you already have one, merge the entries by hand or with jq.

   The template is intentionally not symlinked because the live ~/.claude/settings.json accumulates machine-specific entries (absolute paths, additionalDirectories) that should not be committed.

TODO

• Set up the git remote on a private GitHub repo and push, so a fresh machine can clone it.
• Decide whether to handle ~/.codex/config.toml (model and reasoning prefs are portable; trusted-project paths and bundled-marketplace paths are not).

Day-to-day

• Edit global preferences: edit AGENTS.md, commit. All three agents pick it up on the next session.
• Add a personal skill: drop the folder under skills/, commit.
• Refresh the settings template after tweaking your live settings: run scripts/strip-claude-settings.sh. It re-reads ~/.claude/settings.json, strips any rule that references $HOME, ~/, or /Users/, drops permissions.additionalDirectories, and writes the result to settings/claude.settings.template.json.

What is intentionally not here

• Codex config.toml: contains a mix of portable prefs (model, reasoning) and per-machine state (trusted projects, bundled-marketplace cache paths). Skipping for now.
• Codex ~/.codex/memories/: already its own git repo, runtime-written.
• MCP server configs: format differs between Claude (.mcp.json), Codex (TOML), and Copilot (.vscode/mcp.json with the servers top-level key). Cannot be symlinked across all three. Maintain separately per tool for now.
• Runtime state: sessions/, projects/, logs/, auth.json, cache/. Never portable.