Codex Repo Sync

codex-repo-sync is a Codex managed lifecycle plugin that fetches the current Git repository whenever a Codex session starts or resumes. It safely fast-forwards a clean branch that is strictly behind its own upstream, then gives the active Codex task a structured repository report and mandatory integration instructions.

The hook deliberately uses the already-running Codex task as the judgment layer. It does not start a nested Codex process.

Behavior

Repository state	Hook behavior
Outside Git	Exit without output
Clean and strictly behind current upstream	Fetch and fast-forward with git merge --ff-only
Current feature branch is missing commits from the remote default branch	Ask the active Codex task to inspect and merge the default branch before task edits
Dirty, ahead, divergent, detached, or missing upstream	Preserve the checkout and ask the active Codex task to reconcile it
Fetch or fast-forward failure	Continue the session with a warning and require Codex to diagnose before editing

The plugin never stashes, resets, cleans, rebases, switches branches, creates merge commits, force-updates, or discards work. A non-fast-forward integration is always performed by the active Codex task under the repository's own instructions.

Install

The preferred public installation surface is the ctx9 launcher:

ctx9 install codex-repo-sync
ctx9 doctor codex-repo-sync

The launcher verifies the published release checksum before invoking the repository-owned installer. Direct source checkout installation remains supported:

python3 scripts/install.py

For an extracted release artifact, pin the public Git marketplace to the same release:

python3 scripts/install.py \
  --marketplace-source ContextNine/codex-repo-sync \
  --ref v0.1.2
python3 scripts/install.py --verify --json

The installer performs the complete installation. On the first run, macOS may show one administrator-authentication dialog because /etc/codex/requirements.toml is protected system policy. There is no /hooks review step: Codex treats the SessionStart hook as managed and trusted by policy. Later updates replace the per-user managed hook automatically and normally need no administrator prompt.

When a user asks an agent to install or update this plugin, the agent must run python3 scripts/install.py itself and finish the installation. It must not pause to ask the user to review or trust the hook in /hooks. Start a new Codex thread afterward so the local runtime reloads policy and plugin state.

The default personal-fleet profile places the executable in ~/.local/share/codex/managed-hooks/ so repository updates can refresh it without repeated elevation. The system policy remains root-owned. This provides Codex's managed/trusted behavior, but not enterprise tamper resistance: an enterprise deployment should make both the policy and executable root- or MDM-owned.

Remove the plugin and all state it owns with ctx9 uninstall codex-repo-sync or python3 scripts/install.py --uninstall. Other Codex policy is preserved.

Start a new task in a Git repository after installation. The hook runs for startup and resume, but not for compact, so it does not change repository state during mid-turn context compaction.

Fleet distribution

Matt's development checkout lives at ~/Code/ctx9/codex-repo-sync, but neither public installation nor runtime depends on that path, a private Vault, or a CTX9 workspace checkout.

Fleet development checkouts still use each machine's own Git transport and machine-local SSH identity. Public release installation does not require private GitHub access.

GitHub website login, Codex login, gh login, and Git's noninteractive authentication are separate. The workspace reconciler deliberately disables prompts, so its real acceptance test is a noninteractive git ls-remote or fetch in the same SSH-launched environment—not whether a browser or interactive terminal appears signed in.

Validate

python3 -m unittest discover -s tests -v
python3 scripts/check.py
python3 scripts/install.py --verify --json

Set CODEX_REPO_SYNC_SKIP=1 for a one-process bypass. Set CODEX_REPO_SYNC_TIMEOUT_SECONDS to change the Git command timeout from its default of 45 seconds.

Release and installation details live in docs/.