https://github.com/casoon/ai-agent-config
Shareable baseline configuration for Claude Code and Codex — global instructions, subagents, and skills in a single tree, symlinked into each tool's config dir.
https://github.com/casoon/ai-agent-config
agent-config ai-agents anthropic claude-code codex developer-tools dotfiles prompt-engineering skills subagents
Last synced: 19 days ago
JSON representation
Shareable baseline configuration for Claude Code and Codex — global instructions, subagents, and skills in a single tree, symlinked into each tool's config dir.
- Host: GitHub
- URL: https://github.com/casoon/ai-agent-config
- Owner: casoon
- License: mit
- Created: 2026-04-21T08:21:27.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-20T14:05:37.000Z (23 days ago)
- Last Synced: 2026-05-20T15:36:06.446Z (23 days ago)
- Topics: agent-config, ai-agents, anthropic, claude-code, codex, developer-tools, dotfiles, prompt-engineering, skills, subagents
- Language: Shell
- Size: 69.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ai-agent-config
Shareable baseline configuration for Claude Code and Codex.
The repo holds a single neutral tree. At install time, each tool-specific
link script symlinks the shared files into the tool's config directory
(`~/.claude/` resp. `~/.codex/`) under the names that tool expects.
> **Status: example, being validated in practice.**
> This repo is a first cut at sharing a global AI-assistant configuration
> across tools (Claude Code, Codex, eventually Mistral Vibe). I am currently
> using it on my own machine to see whether the approach holds up — where
> the rough edges are, what needs to be simplified, and which parts are
> actually worth sharing. Expect breaking changes. Feedback and issues are
> welcome.
## Intended use
This repo is a **template**, not a ready-to-link personal config. Running
`install/link-all.sh` directly from a clone of this repository will
replace your existing `~/.claude/CLAUDE.md`, `~/.claude/skills/`,
`~/.codex/AGENTS.md`, `~/.codex/config.toml`, and `~/.codex/skills/` with
the generic content here. Existing non-symlink targets are moved to
`.bak`, so nothing is lost, but your real personal config stops
being active until you restore it.
**Recommended workflow:**
1. Fork or clone this repo into a **private** copy.
2. In the private copy, manually merge your existing files from
`~/.claude/` and `~/.codex/` into `GLOBAL.md`, `skills/`, and
`codex-config.toml`.
3. Run `install/link-all.sh` from the **private** copy only.
4. Pull updates from this template into the private copy via
`git merge` or cherry-pick as needed.
## Layout
```
./
├── GLOBAL.md # global instructions (→ CLAUDE.md / AGENTS.md)
├── agents/ # subagent sources (Markdown + YAML frontmatter)
├── codex-agents/ # generated from agents/ — do not edit by hand
├── skills/ # reusable skills (one folder with SKILL.md each)
├── codex-config.toml # Codex-only runtime profiles
├── scripts/
│ └── render-codex-agents.py
├── .githooks/
│ └── pre-commit # regenerates codex-agents/ on commit
└── install/
├── link-claude.sh
├── link-codex.sh
└── link-all.sh
```
## Install
```sh
./install/link-all.sh
```
The scripts create symlinks under `~/.claude/` and `~/.codex/`:
| Source | Claude target | Codex target |
| ----------------------- | ------------------------ | ------------------------- |
| `GLOBAL.md` | `~/.claude/CLAUDE.md` | `~/.codex/AGENTS.md` |
| `agents/` | `~/.claude/agents` | — (uses `codex-agents/`) |
| `codex-agents/` | — | `~/.codex/agents` |
| `skills/` | `~/.claude/skills` | `~/.codex/skills` |
| `codex-config.toml` | — | `~/.codex/config.toml` |
If a target path exists and is not already a symlink, it is moved to
`.bak` before the new symlink is created. Already-existing symlinks
are replaced silently.
## Supported platforms
The install scripts use plain portable Bash (`ln -sfn`, `mkdir -p`, `mv`)
and do not depend on macOS-specific tooling.
| Platform | Status |
| ------------- | ----------------------------------------------------------- |
| **macOS** | Tested. |
| **Linux** | Expected to work — not actively tested. Please open an issue if something breaks. |
| **Windows** | Not supported natively. Use **WSL2** (Ubuntu / Debian) — from inside WSL the Linux path applies. |
Requirements on any platform: `bash`, `python3` (for the codex-agent
renderer), and `git`. `nosecrets` is optional but recommended — see
below.
## Single source of truth
`agents/*.md` is the **only** place to edit agent prompts.
`codex-agents/*.toml` is generated and should never be edited directly:
```sh
python3 scripts/render-codex-agents.py
```
This is run automatically on commit via `.githooks/pre-commit`. Enable the
hook once per clone:
```sh
git config core.hooksPath .githooks
```
### Pre-commit hook
`.githooks/pre-commit` does two things on every commit:
1. Regenerates `codex-agents/*.toml` from `agents/*.md` and stages the
result, so the Codex-side prompts can never drift out of sync with
the Markdown sources.
2. Runs [`nosecrets`](https://github.com/casoon/nosecrets) against the
staged files and aborts the commit on findings.
If `nosecrets` is not installed, the hook prints a visible error and
**continues** — the commit is not blocked, but nothing was scanned.
Install one-off per machine:
```sh
# curl (macOS / Linux, installs a prebuilt binary)
curl -fsSL https://raw.githubusercontent.com/casoon/nosecrets/main/install.sh | sh
# or via npm
npm install -g @casoon/nosecrets
# or via cargo
cargo install nosecrets-cli
```
## Memory scope
This repo manages the **global** layer of Claude Code's memory system — the
per-user `CLAUDE.md` (and Codex's `AGENTS.md`), plus reusable skills and
subagent prompts. It deliberately does **not** cover:
- **Project memory** — each project's own `CLAUDE.md` lives in that
project's repo, not here.
- **Conversational memory** — Claude Code's per-session auto-memory under
`~/.claude/projects/…` is machine-local, often personal, and must never
be committed to a shared baseline.
## Private additions
`GLOBAL.md` ends with a marked "private section". Personal specifics —
preferred package managers, daily languages, commit conventions, project
quirks — belong there and should live in a **private fork** of this repo,
not in the shared baseline.
## Change workflow
- Edit `GLOBAL.md`, `agents/*.md`, or `skills/*/SKILL.md` — symlinks make
the change immediately live for Claude. For Codex, the pre-commit hook
regenerates `codex-agents/` before the change is committed.
- Keep the global instruction file short. Stack-specific knowledge belongs
in skills; role prompts belong in agents.
## License
[MIT](LICENSE) — do whatever you like with it, attribution appreciated but
not required.