agents

Personal configuration for my coding agents (Claude Code and Codex) — the prompt files, settings, hooks, and statusline I want to carry from machine to machine. The companion repo skills holds reusable capabilities; this repo holds the config and guardrails around them.

install.sh puts it all in place: prompt files are symlinked from here, while the config that the agent apps rewrite at runtime (settings.json, codex-config.toml) is deep-merged, so reinstalling never clobbers machine-local state.

What it changes on your machine

./install.sh links or merges these (preview first with --dry-run):

Destination	Source	How
~/.claude/CLAUDE.md, ~/.claude/AGENTS.md	CLAUDE.md, AGENTS.md	symlink
~/.claude/settings.json	settings.json	deep-merge (jq)
~/.claude/hooks/git-commit-gate.py	hooks/	symlink
~/.claude/plugins/claude-hud/config.json	claude-hud/config.json	symlink
~/.claude/tools/claude-hud	pinned clone + claude-hud/customizations.patch	clone + patch
~/.codex/AGENTS.md	AGENTS.md	symlink
~/.codex/config.toml	codex-config.toml	deep-merge (tomlq)

settings.json and config.toml are merged, never symlinked: the apps write machine-local state into them (themes, plugin/MCP registration, project trust), so install merges in only the shared keys and leaves the rest alone. Reinstall is idempotent.

Setup

./install.sh --dry-run   # preview; changes nothing
./install.sh --deps      # link/merge config and install the brew dependencies

Verify by re-running --dry-run: it should report the rails already present with no changes. Uninstall with ./install.sh --uninstall (removes the symlinks and the claude-hud clone; the merged config files are left in place).

Flags: --claude / --codex (one target only), --deps, --copy (copy symlink targets instead of linking — merged files and claude-hud are unaffected), --force (overwrite a foreign file, backing it up to .bak), --uninstall, --dry-run.

Dependencies (not vendored here)

• rtk — rtk-ai, a CLI proxy that cuts token use. settings.json's PreToolUse hook runs rtk hook claude, and CLAUDE.md imports RTK.md (installed by rtk itself, not this repo). brew install rtk; without it the hook errors on every Bash call.
• jq and python-yq (tomlq) — the JSON/TOML merges. python3 — the commit-gate hook. node — the claude-hud statusline.

--deps installs the brew formulae (rtk, jq, python-yq); python3 and node are expected to be present already (warned about, not installed).

Troubleshooting

• Every Bash call is blocked — rtk or python3 is missing; the PreToolUse hook errors without them.
• Statusline is blank — node isn't on PATH; the claude-hud command needs it.
• claude-hud install fails loudly — customizations.patch no longer applies to the pinned commit (upstream drift). Bump CLAUDE_HUD_COMMIT in install.sh, then re-roll: git -C ~/.claude/tools/claude-hud diff > claude-hud/customizations.patch.
• A merge is refused — the live settings.json / config.toml isn't valid JSON/TOML, or jq/tomlq is missing (run --deps).

Components

• Dotfiles — CLAUDE.md, AGENTS.md, settings.json, codex-config.toml. AGENTS.md is the vendor-neutral prompt, symlinked to both agents; CLAUDE.md imports it for Claude. Skills that shell out to external agent CLIs (e.g. council → codex) need those listed in settings.json sandbox.excludedCommands so they run without a permission prompt.
• Statusline — claude-hud/ vendors claude-hud as a pin + patch rather than a committed copy: config.json (symlinked) and customizations.patch against a pinned commit. install.sh clones the commit and applies the patch — idempotent, and it fails loudly if the patch stops applying. The patch targets claude-hud's compiled dist/, so an upstream release can require a re-roll. claude-hud is MIT-licensed; see NOTICE.

Relationship to other repos

• skills — consumed one-way: this harness drives those skills; the skills never depend on it. The subagent definitions in agents/ reference skills by name (scrutinize, karpathy-guidelines, etc.) — install the skills repo for full effect; without them the agents still work but lose the methodology anchors.
• blut-setup — separate; it makes a blank machine feel like mine (shell/git/OS). This repo is agent-specific, so not every machine needs it.

Planned: a runtimes/ directory for host-specific loop adapters — driving workflows under Anthropic's ralph-wiggum plugin rather than rebuilding one. Not in the repo yet.