claude-config

Shared instructions and curated skills for Claude Code and Codex. Most skills are vendored under stable local names; a few are written here. Installations copy files, with no symlinks or automatic updates.

Install and check

Requires uv and Git. uv supplies Python 3.11+, and the startup hooks run cc.py through it.

uv run --script cc.py install --target all
uv run --script cc.py check --target all --local-only
uv run --script cc.py vendor [name ...]

--target accepts claude, codex, or all; it defaults to claude for existing commands and hooks. vendor updates the shared sources for both.

Content	Claude Code	Codex
Global instructions	~/.claude/CLAUDE.md	~/.codex/AGENTS.md
Skills	~/.claude/skills/	~/.agents/skills/
Rules (rules/ and sources)	~/.claude/rules/	appended to ~/.codex/AGENTS.md
Settings	~/.claude/settings.json	~/.codex/config.toml
Startup drift check	inside settings	~/.codex/hooks.json
Bash guard (hooks/heredoc_guard.py)	inside settings	—
Model guard (hooks/model_guard.py)	inside settings	—
Usage-limit continue (hooks/usage_limit_continue.py)	inside settings, opt-in	—

The guard refuses two kinds of Bash command:

• A heredoc whose delimiter is unquoted and whose body holds a backtick or $(. The shell runs those spans, so Markdown fed to gh that way runs the commands its code spans name. The refusal says to quote the delimiter (<<'EOF').
• On Windows only, a command with a double backslash. There the Bash tool turns every \\ into \, in a heredoc as well as in quotes and arguments, which silently corrupts string literals, regexes and paths. The refusal points to the Write and Edit tools instead.

A shell pre-check starts the guard only for a command with << or \\.

Claude Code does not continue a task on its own after a usage limit resets in the sessions that claude remote-control serves. To make those sessions continue on a machine, turn the hook on in the machine config and install. The hook waits until the reset and wakes the session. It skips a reset more than 24 hours away, such as a weekly limit. It runs in every session on that machine, and stays quiet when the session has moved on by the time it wakes. So a terminal session that you stopped with Esc during Claude Code's own wait still continues 2 minutes after the reset. Wait for a usage limit to reset

CLAUDE_CONFIG_DIR and CODEX_HOME override the respective configuration roots. CODEX_SKILLS_DIR overrides this installer's Codex skill destination for testing or a custom layout; it does not configure Codex discovery. Use a directory Codex already scans. Changing CODEX_HOME does not move ~/.agents/skills/.

Each destination has its own ownership manifest. Installation removes only obsolete paths in that manifest and leaves unrelated files alone. Existing files at managed instruction and skill paths are replaced. Claude's existing manifest remains valid.

check reports repository, installed-file, attribution, and upstream drift. In a fork with a remote named upstream, it also reports commits on that remote's branch that are not merged yet. It applies no updates; --daily throttles each runtime separately to once per calendar day, and --local-only skips network checks. Startup hooks run the check with the appropriate target. After installing Codex, review and trust its hook with /hooks; Codex requires review again when the hook changes. Codex hook documentation

Machine config

Settings that differ between machines live in ~/.config/claude-config/config.toml ($XDG_CONFIG_HOME/claude-config/config.toml when that is set), outside the repo. A source can be a private repo, and naming it here would publish it. With no file, nothing changes.

[review]
default = "subagent"            # copilot, subagent, claude or codex

[vars]
share_scratch = "/data/claude"  # fills {{share_scratch}} in rule files

[vault]
inputs = ["calendar", "github"]  # outside inputs the vault brief and wrap read

[hooks]
usage_limit_continue = true     # opt-in Claude hooks, off by default

[models.claude]
min_effort = "medium"             # no choice goes below this ...
max_effort = "xhigh"              # ... or above this, which also caps Claude's maxEffortLevel

[models.claude.limits]
haiku = { max_effort = "medium" } # per-model bounds inside those

[models.claude.tasks.review]
default = "sonnet@medium"
allowed = ["opus@high"]

[models.codex.tasks.review]
default = "default@medium"        # default: the model in Codex's own config

[[sources]]
repo = "git@github.com:<owner>/<my-rules>.git"
rules = "all"
skills = "all"

[[sources]]
repo = "git@github.com:<owner>/<colleague-config>.git"
ref = "main"                    # optional, defaults to the remote's default branch
skills = ["some-skill", "another-skill"]

• review.default adds a line to both runtimes' global instructions. issue-to-pr and review-loop take it as their reviewer when no --reviewer is given.
• A source is a repo with rules/ and skills/<name>/SKILL.md folders. It installs only what rules and skills pick, each "all" or a list of names; a rule's name is its path under rules/ without .md. A source that picks nothing or has neither folder is an error, and so is a name the source lacks or a file or skill that two places provide. install clones or fetches each source into .cache/. Source skills install as they are, without this repo's patches.
• [vault] inputs lists the outside inputs the vault brief and wrap read on this machine. The vault template's vault-rules.md names the inputs they know.
• [hooks] turns on Claude hooks that most machines don't need. Each installs into settings.json only when set to true. The one hook so far is usage_limit_continue, described under Install and check.
• [models] sets, per runtime and per task kind (explore, audit, implement, review, design, judgment), the model and effort a subagent starts on (default) and the other choices an agent picks from, stronger or smaller, by how complex, consequential or open-ended the work is (allowed). Each is model@effort; Claude takes the aliases opus, sonnet, haiku and fable. A task's models list restricts its choices; the built-in design and judgment take only opus, and keep that when the config changes their default. Built-in defaults fill every task kind and bound the config leaves out, and a choice outside its bounds is an error.
• Install renders the result as a Models section in both runtimes' instructions: the prose and task kinds come from instructions/models.md, and cc.py fills in the table, the bounds and the cross-model line, with the other runtime's review entry for review-loop --reviewer claude|codex. A subagent that fits no kind inherits its parent's model and effort. On Claude, max_effort becomes maxEffortLevel in settings.json, which caps every request including the main session's, and hooks/model_guard.py refuses an Agent call whose model or effort is outside the table. CLAUDE_CODE_EFFORT_LEVEL in the environment overrides every Claude effort.
• {{name}} in a Markdown rule becomes the [vars] value of that name, or none when it is not set.
• Claude Code gets the rules in ~/.claude/rules/. Codex has no path-scoped rules, so each rule is appended to AGENTS.md with its frontmatter shown as written, and a line saying it applies only to files matching the paths globs there.
• check reads the cached clones, so --local-only stays offline. Without it, check also reports a source with commits the cache lacks.

Vault

The skills under skills/vault/ keep a private markdown vault of projects, tasks, and research notes in its own git repo at $VAULT_DIR (default ~/vault). Ask Claude to set up a vault: the setup-vault skill creates one from the template in skills/vault/setup-vault/assets/vault/, whose rules fix the note formats every vault skill reads. The same skill updates an existing vault when the template changes.

Instructions and settings

Edit instructions/shared.md for common policy and instructions/claude.md or instructions/codex.md for runtime-specific guidance. Installation combines them into the appropriate global instruction file. The root AGENTS.md governs this repository; root CLAUDE.md points to it.

settings/codex.toml supplies managed root-level Codex settings. Currently it adds CLAUDE.md to project_doc_fallback_filenames, preserving existing fallback names and their order. Codex uses that fallback only when the same directory has no applicable AGENTS.override.md or AGENTS.md. Instruction discovery

The Codex settings merge preserves unrelated settings, tables, and comments. Its hook merge preserves other handlers. Models, permissions, and MCP settings remain machine-local. Claude's settings.json is managed as before, except its installed model, effort level, and model settings take precedence.

Claude-only rules/ files are copied into the Claude rules directory; other files there remain machine-local. For Codex, the installed instructions ask the agent to read $CODEX_HOME/local-instructions.md if present (default ~/.codex/local-instructions.md). That file is not managed. Write file scopes as explicit conditions there; Claude paths: rules are not converted.

Owned remotes

Outside the vault, every push and every write on a remote needs your approval in the turn it happens. To let agents push feature branches and open, update, and answer issues and PRs on your own repos without that, list those repos in ~/.claude/rules/owned-remotes.md for Claude and ~/.codex/owned-remotes.md for Codex. No other file counts, so a list an agent happens to read elsewhere grants nothing. You edit these files by hand: agents are told never to touch them, and Claude's settings deny Edit on rules/owned-remotes.md. The installer does not manage either file. Merging and pushing to the default branch still need approval each time. The entry format and the full rules are under "Owned remotes" in instructions/shared.md.

Claude's auto mode trusts only the current repo's remotes by default, so install also adds the list to autoMode.environment in settings.json. It leaves out (private) entries: the classifier cannot check a repo's visibility, so it would trust public repos under them too. Auto mode still blocks writes to those repos from any other repo you work in. Re-run install after you edit owned-remotes.md; until then, check reports settings.json drift. Auto mode configuration

Claude permission rules

Write Bash permission rules in space form — Bash(uv run pytest *), not Bash(uv run pytest:*). The VSCode extension (observed on 2.1.195) silently fails to match the colon form when the prefix is more than one word: every matching command still prompts, and adding more colon rules changes nothing. The standalone CLI matches both, so the forms are not interchangeable in practice. Space form is also what the permission dialog writes when you pick "Yes, don't ask again".

Read and Edit path patterns without an anchor match only under the current working directory: Edit(**) does not cover /mnt, and Read(**/.env) does not deny a .env elsewhere. Use // for absolute paths and ~/ for home-relative ones. A bare Read rule matches every read. Claude Code never checks Write(...) path rules; Edit rules govern writes. Read and Edit rules

Editing and updating skills

Edit shared skills under skills/, then reinstall the desired target. A folder there without a SKILL.md, such as skills/vault/, only groups skills in this repo: installation places each skill in it at the top level. For a vendored skill, also record the edit in the appropriate patch so re-vendoring preserves it. Patches use paths relative to the skill directory:

1. sources.tsv: upstream directory, revision, and pristine content hash.
2. support-sources.tsv: additional upstream files needed by a skill, including the pstack Codex mapping. The first column is the destination under skills/.
3. patches/content/<name>.patch: workflow and editorial customizations.
4. patches/compat/shared/<name>.patch: portability changes used by both agents.
5. patches/compat/{claude,codex}/<name>.patch: runtime-specific additions or edits.

vendor applies steps 1–4 into the checked-in shared skill tree and verifies both target patch sets before publishing the batch. install and check apply step 5 in temporary directories. A failed patch stops the operation; installation renders both requested targets before writing either one.

Codex patches move explicit-only invocation policy into agents/openai.yaml, remove Claude-specific frontmatter, and preserve argument hints in the body. reflect and review-loop receive separate runtime guides. Codex reflection uses an explicitly supplied readable current-session transcript or a labeled conversation digest; it does not run Claude's transcript parser. The review loop requires a fresh independent reviewer and reports when that is unavailable. Codex skill metadata

Pstack remains sourced from michael-denyer/pstack-claude. Its supporting Codex mapping is pinned, attributed, patched, and drift-checked along with the skills.

Verification

uv run --no-project --python '>=3.11' python -m unittest discover -s tests -v

Tests use temporary installation roots and cover both targets, repeated installs, configuration preservation, drift, owned-file cleanup, patch failures, and legacy Claude manifests. The pinned-source reproduction test also runs when the upstream commits are present in .cache/; otherwise it reports a skip. When Codex is installed and supports debug prompt-input, a local discovery test checks global instructions, the project fallback, and invocation policy without running a model.

License

MIT, in LICENSE. Vendored licenses are reproduced under licenses/. vendor rebuilds NOTICE.md from both source tables and license notes; check reports missing licenses or a stale notice. Per-source prose belongs in licenses/<slug>.note.md.