agents-config

One config for every AI coding agent you use, on every machine you use.

You tell Claude Code who you are. Then you tell Codex. Then you tell the next tool, and the next machine, and six months later you have five slightly different dotfiles that all claim to be the truth. This fixes that: you write down who you are and how you like to work once, in plain markdown, in one git repo — and agents apply renders it into each tool's native config on every machine.

Out of the box it renders for Claude Code (~/.claude/CLAUDE.md), Codex CLI (~/.codex/AGENTS.md), PI (~/.pi/agent/AGENTS.md), and Hermes/OpenClaw (~/.hermes/GLOBAL.md). Adding another tool is a few lines in agents.toml.

How it works

There are only three questions a preference can answer, so there are only three places it can live:

shared/core.md            true everywhere, for every agent
agents/<agent>/extra.md   true for one agent, on every machine
hosts/<host>/host.md      true for one machine, for every agent

agents apply concatenates the layers that apply to this machine and writes the result to each tool's config path. Skills in shared/skills/ get symlinked into each agent's skills directory. That's the whole trick — rendering is concatenation, skills are symlinks, sync is git pull and git push. No daemon, no database, one bash script you can read.

Rendered files carry a GENERATED header so nothing edits them by accident — and the bundled agent-config skill teaches your agents the same rule, so when you tell Claude "remember: never use emojis", it edits the repo instead of scribbling on its own config folder.

Get started

Don't fork this repo. Your agent config is personal — it belongs in a private repo, and GitHub forks of public repos stay public. Instead, init stamps out a fresh private-ready config repo that's yours from commit zero (it carries a full copy of the tooling, so you never need this repo again):

git clone https://github.com/OverseedAI/agents-config ~/projects/agents-config
~/projects/agents-config/apply.sh init ~/projects/my-agents-config

Then, in your new repo:

1. Edit shared/core.md — who you are, how agents should work with you — and delete the TEMPLATE-FILL-ME comment. (apply refuses to run while it's there, so you can't deploy the placeholder by accident.)
2. Push it somewhere private. init prints the exact gh repo create --private command.
3. Deploy:

cd ~/projects/my-agents-config
./apply.sh apply

The first run asks you to name this machine, renders configs for every agent CLI it finds (missing ones are skipped), links your skills, and installs the agents command at ~/.local/bin/agents. If ~/.local/bin isn't on your PATH, add it — or just alias it:

# in ~/.bashrc or ~/.zshrc — either line works
export PATH="$HOME/.local/bin:$PATH"
alias agents="$HOME/projects/my-agents-config/apply.sh"

Daily use

agents add "never use emojis"   # capture a preference → rendered + synced, one command
agents add -a codex "…"         # scope it to one agent;  -H laptop → one machine
agents edit                     # open core.md in $EDITOR, sync on close
agents sync                     # pull → re-render → commit → push
agents status                   # am I in sync? any drift?

agents help lists everything else — skills management, snapshots, doctor, dry runs. agents help <command> explains any one of them with examples.

Adding a machine

Clone your config repo there and run ./apply.sh apply. If the machine already has a hand-written CLAUDE.md or AGENTS.md, apply won't clobber it blind: the old file is salvaged to ~/.local/state/agents/drift/, and agents status nags you until you've diffed it and folded anything worth keeping into your host layer. For always-on machines, agents auto on sets up an hourly pull.

Shared secrets (optional)

API keys have the same problem your preferences did: one copy per machine, all slowly drifting. agents secrets versions one encrypted env file (secrets/shared.env.enc) in your config repo, using SOPS + age. Each machine holds its own age private key; only public keys are committed, so the encrypted file is safe to push. apply decrypts it to ~/.config/agents/secrets.env (chmod 600) on enrolled machines.

To get it running (needs sops and age — brew install sops age):

# 1. Give this machine a key (once per machine). It prints the public key:
age-keygen -o ~/.config/sops/age/keys.txt

# 2. Paste that public key into .sops.yaml in your config repo — there's a
#    commented placeholder line showing exactly where.

# 3. Create the encrypted file with a first secret:
printf 'export EXAMPLE_KEY=value\n' | sops encrypt --input-type binary \
  --output-type binary --filename-override secrets/shared.env.enc \
  /dev/stdin > secrets/shared.env.enc

# 4. Render it, then commit and push:
agents secrets apply
agents sync

From then on it's agents secrets edit to change values, agents secrets add-host <name> <age-pubkey> to enroll another machine (run age-keygen there, add its key from any already-enrolled machine), and agents secrets status when something looks off. In your own scripts and shell, load the secrets with source ~/.config/agents/secrets.env.

What it deliberately doesn't manage

Structured configs (settings.json, config.toml) mix your settings with runtime state the tools write themselves — deploying those from a repo would fight the tools, so they're observed instead: agents snapshot keeps redacted local copies for cross-machine comparison. Per-tool credentials (auth.json and friends) and runtime state (history, sessions, caches) stay out entirely.

Hacking on it

• New agent CLI: add an [agents.<name>] block to agents.toml.
• Changing the mechanism: tests/run.sh runs the full e2e suite in a sandboxed HOME — it never touches your real config.
• agents publish-check is a conservative preflight that fails on secret-shaped values, personal layers, emails, and home paths — run it before making any config repo public.