- Work in the main loop by default. Use sub-agents only for independent work that runs in parallel, broad read-only searches where only the conclusion matters, or a review that must not see your reasoning.
- Split work by context, not by step: give each sub-agent a self-contained piece, and never split one chain of dependent steps across agents.
- Use cheaper capable models for sub-agents and stronger models only when the task needs them; prefer a model pinned in an agent definition over a per-call choice.
- Make repository edits in dedicated Git worktrees and task branches, with separate worktrees for concurrent writers.
- Every tool, library, standard or project named in a reply carries its URL, where one exists.
Last active
November 1, 2026 07:43
-
-
Save HackingGate/193a98e2b40c5dcfebdd3ed00039e8af to your computer and use it in GitHub Desktop.
Multiple agents, cheaper sub-agents, and Git worktrees for Claude Code and Codex
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Shared preferences for Claude Code and Codex | |
| The preferences are to work in the main loop by default, use sub-agents only for independent parallel work, broad read-only searches or an independent review, split work by context rather than by step, select cheaper capable models for sub-agents, and make repository edits in dedicated Git worktrees and task branches. AGENTS.md is installed into a managed block in Codex's global instructions at ~/.codex/AGENTS.md (or $CODEX_HOME/AGENTS.md). The same preferences are installed into a managed block in Claude Code's ~/.claude/CLAUDE.md (or $CLAUDE_CONFIG_DIR/CLAUDE.md). Neither file imports the other, so each tool reads only its own instructions; personal lines outside a block stay where they are. | |
| Install with Python 3.11+ and uv: | |
| gh gist clone 193a98e2b40c5dcfebdd3ed00039e8af agent-preferences | |
| cd agent-preferences | |
| uv run install.py --source-dir . | |
| Running uv run install.py without --source-dir fetches the latest files. The installer backs up changed files and preserves personal instructions and model settings. Restart Codex and Claude Code sessions after installation. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # Merge these entries into ~/.codex/config.toml. | |
| [features] | |
| multi_agent = true |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # /// script | |
| # requires-python = ">=3.11" | |
| # dependencies = ["tomlkit>=0.13,<1"] | |
| # /// | |
| """Install agent preferences for Codex and Claude Code, preserving models.""" | |
| import argparse | |
| import os | |
| import re | |
| import stat | |
| import tempfile | |
| from collections.abc import Mapping | |
| from datetime import datetime, timezone | |
| from pathlib import Path | |
| from urllib.request import urlopen | |
| import tomlkit | |
| SOURCE = "https://gist.githubusercontent.com/HackingGate/193a98e2b40c5dcfebdd3ed00039e8af/raw" | |
| BEGIN = "<!-- BEGIN HackingGate shared agent preferences -->" | |
| END = "<!-- END HackingGate shared agent preferences -->" | |
| LEGACY_CLAUDE_RULES = ( | |
| '- Do the work through sub-agents. The main session plans, delegates and reviews.', | |
| '- Leave the sub-agent model unset: omit `model` and let Claude Code pick.', | |
| '- Explicitly select sub-agent models according to the shared model-selection policy, using supported model names or aliases.', | |
| '- Split independent pieces into separate sub-agents and launch them in one message.', | |
| '- An implementing sub-agent does not run the full gate; the main session hands that to a separate sub-agent afterwards.', | |
| '- One or two read-only commands may run in the main session.', | |
| '- For writing sub-agents, request `isolation: "worktree"` when supported; otherwise create a Git worktree explicitly and assign its absolute path.', | |
| ) | |
| LEGACY = ( | |
| "Use the main agent as the orchestrator. Proactively delegate independent,\n" | |
| "bounded work to sub-agents when doing so can save time or improve quality.\n" | |
| "Coordinate their work, integrate their results, and verify the final outcome.\n" | |
| "Keep short tasks and dependent steps with the main agent." | |
| ) | |
| def fetch(name, source_dir=None): | |
| if source_dir is not None: | |
| return (source_dir / name).read_text(encoding="utf-8") | |
| with urlopen(f"{SOURCE}/{name}", timeout=30) as response: | |
| return response.read().decode("utf-8") | |
| def merge(target, updates): | |
| for key, value in updates.items(): | |
| if key.startswith("model"): | |
| raise ValueError(f"Source must not change model settings: {key!r}") | |
| if isinstance(value, Mapping): | |
| if key not in target: | |
| target[key] = tomlkit.table() | |
| if not isinstance(target[key], Mapping): | |
| raise ValueError(f"Expected a TOML table for {key!r}") | |
| merge(target[key], value) | |
| else: | |
| target[key] = value | |
| def managed_preferences(old, preferences, migrate=False, obsolete_lines=()): | |
| if migrate and old.strip() in (LEGACY, "# Global Codex preferences\n\n" + LEGACY): | |
| old = "" | |
| if old.count(BEGIN) != old.count(END) or old.count(BEGIN) > 1: | |
| raise ValueError("Malformed or duplicate shared-preferences markers") | |
| block = f"{BEGIN}\n{preferences}\n{END}" | |
| if BEGIN in old: | |
| start, end = old.index(BEGIN), old.index(END) | |
| if end < start: | |
| raise ValueError("Reversed shared-preferences markers") | |
| old = old[:start] + block + old[end + len(END):] | |
| else: | |
| old = (old.rstrip() + "\n\n" if old.strip() else "") + block + "\n" | |
| if migrate or obsolete_lines: | |
| # Remove only exact shipped instructions outside the managed block. | |
| start, end = old.index(BEGIN), old.index(END) + len(END) | |
| def clean(text): | |
| if migrate: | |
| text = re.sub(r"(?m)^" + re.escape(LEGACY) + r"(?:\n|$)", "", text) | |
| text = re.sub(r"(?m)^# Global Codex preferences$", "# Global agent preferences", text) | |
| return "".join(line for line in text.splitlines(keepends=True) if line.rstrip("\r\n") not in obsolete_lines) | |
| old = clean(old[:start]) + old[start:end] + clean(old[end:]) | |
| return old | |
| def read_destination(path): | |
| # Follow a symlink deliberately; replacing the resolved target keeps it intact. | |
| actual = path.resolve(strict=False) | |
| if actual.exists() and not actual.is_file(): | |
| raise ValueError(f"Destination is not a regular file: {path}") | |
| return actual, actual.read_text(encoding="utf-8") if actual.exists() else "" | |
| def write_plan(plan): | |
| stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ") | |
| for display, path, old, new in plan: | |
| if old == new: | |
| continue | |
| path.parent.mkdir(parents=True, exist_ok=True) | |
| mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else 0o600 | |
| if path.exists(): | |
| backup = path.with_name(f"{path.name}.{stamp}.bak") | |
| with open(backup, "x", encoding="utf-8", opener=lambda name, flags: os.open(name, flags, 0o600)) as handle: | |
| handle.write(old) | |
| fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent) | |
| try: | |
| with os.fdopen(fd, "w", encoding="utf-8") as handle: | |
| handle.write(new) | |
| handle.flush() | |
| os.fsync(handle.fileno()) | |
| os.fchmod(handle.fileno(), mode) | |
| os.replace(temporary, path) | |
| finally: | |
| if os.path.exists(temporary): | |
| os.unlink(temporary) | |
| print(f"Updated {display}") | |
| def install(destination, claude_destination=None, source_dir=None): | |
| if claude_destination is None: | |
| claude_destination = Path(os.environ.get("CLAUDE_CONFIG_DIR", str(Path.home() / ".claude"))) | |
| # Fetch, parse, validate, and compute every output before touching settings. | |
| preferences = fetch("AGENTS.md", source_dir).strip() | |
| if not preferences: | |
| raise ValueError("AGENTS.md must be nonempty") | |
| if BEGIN in preferences or END in preferences: | |
| raise ValueError("Source instructions must not contain managed-block markers") | |
| # Each tool gets its own copy of the preferences; neither file depends on the other. | |
| claude_preferences = preferences | |
| updates = tomlkit.parse(fetch("config.toml", source_dir)) | |
| config_path = destination / "config.toml" | |
| actual_config, old_config = read_destination(config_path) | |
| config = tomlkit.parse(old_config) | |
| merge(config, updates) | |
| new_config = tomlkit.dumps(config) | |
| tomlkit.parse(new_config) | |
| plan = [(config_path, actual_config, old_config, new_config)] | |
| for path, content, migrate, obsolete_lines in [ | |
| (destination / "AGENTS.md", preferences, True, ()), | |
| (claude_destination / "CLAUDE.md", claude_preferences, False, LEGACY_CLAUDE_RULES), | |
| ]: | |
| actual, old = read_destination(path) | |
| plan.append((path, actual, old, managed_preferences(old, content, migrate, obsolete_lines))) | |
| override_path = destination / "AGENTS.override.md" | |
| actual_override, old_override = read_destination(override_path) | |
| if old_override.strip(): | |
| plan.append((override_path, actual_override, old_override, managed_preferences(old_override, preferences, True))) | |
| actual_paths = [entry[1] for entry in plan] | |
| if len(actual_paths) != len(set(actual_paths)): | |
| raise ValueError("Multiple settings destinations resolve to the same file") | |
| write_plan(plan) | |
| print("Model configuration preserved. Restart Codex and Claude Code to load the settings.") | |
| if __name__ == "__main__": | |
| parser = argparse.ArgumentParser(description=__doc__) | |
| parser.add_argument("--source-dir", type=Path, help="Read gist files from a local directory (offline deployment)") | |
| args = parser.parse_args() | |
| install(Path(os.environ.get("CODEX_HOME", str(Path.home() / ".codex"))), source_dir=args.source_dir) |
Author
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Requires uv.
Merges the settings into
~/.codex/config.tomland adds the delegation preferences to~/.codex/AGENTS.md(or$CODEX_HOME). Preserves the selected model and existing configuration, backs up changed files, and can be run again safely. Restart Codex and start a new CLI session afterwards.