Skip to content

Instantly share code, notes, and snippets.

@HackingGate
Last active November 1, 2026 07:43
Show Gist options
  • Select an option

  • Save HackingGate/193a98e2b40c5dcfebdd3ed00039e8af to your computer and use it in GitHub Desktop.

Select an option

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
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.

Global agent preferences

  • 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.
# Merge these entries into ~/.codex/config.toml.
[features]
multi_agent = true
# /// 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)
@HackingGate

Copy link
Copy Markdown
Author

Requires uv.

uv run --no-project --script https://gist.githubusercontent.com/HackingGate/193a98e2b40c5dcfebdd3ed00039e8af/raw/install.py

Merges the settings into ~/.codex/config.toml and 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment