OpenSync Conditional

OpenSync Conditional prevents automatic OpenSync reporting outside explicitly approved work directories.

It wraps the hooks installed by claude-code-sync and codex-sync. A hook reaches the original sync client only when the event's physical cwd is an allowed root or one of its descendants.

Behavior

• Supports Claude Code and OpenAI Codex CLI hooks.
• Supports one or more allowed work roots.
• Uses the cwd carried by the hook event instead of trusting the wrapper process directory.
• Resolves physical paths before matching.
• Fails closed when JSON is malformed, cwd is missing, a path cannot be resolved, or no root matches.
• Preserves hook arguments and stdin byte-for-byte after a request is allowed.
• Preserves an existing Codex Computer Use notifier chain.

For a root such as /home/user/work:

Event path	Result
/home/user/work	Allowed
/home/user/work/project	Allowed
/home/user/work-private	Blocked
Symlink inside work resolving outside	Blocked
Symlink outside resolving inside work	Allowed

Requirements

• Bash 3.2 or newer
• Node.js 18 or newer
• jq
• Existing claude-code-sync and/or codex-sync hooks

Run the upstream setup command first if the sync hooks are not installed:

claude-code-sync setup
codex-sync setup

Install

git clone git@github.com:KeArcus/OpenSyncConditional.git
cd OpenSyncConditional
./install.sh --root "$HOME/work"

Allow multiple work trees by repeating --root:

./install.sh \
  --root "$HOME/work" \
  --root "$HOME/client-projects"

Passing / as a root intentionally allows every physical directory. Paths containing newline or carriage-return characters are rejected to avoid shell path ambiguity.

Configure only one client when needed:

./install.sh --claude-only --root "$HOME/work"
./install.sh --codex-only --root "$HOME/work"

The installer:

1. Resolves each allowed root to a physical absolute path.
2. Installs the wrapper under ${XDG_DATA_HOME:-$HOME/.local/share}/opensync-conditional/bin.
3. Creates owner-only local backups of the client configuration files.
4. Wraps matching Claude Code and Codex OpenSync hooks.
5. Leaves unrelated hooks and notifier commands unchanged.

Restart active Claude Code and Codex sessions after installation so they reload their configuration.

Re-running the installer updates the allowed roots and is idempotent.

Verify

Inspect the configured Claude commands:

jq -r '.hooks[][] | .hooks[]?.command' "$HOME/.claude/settings.json"

Inspect the Codex notify line:

grep '^notify' "$HOME/.codex/config.toml"

Run the repository tests:

./tests/test.sh

Uninstall

./uninstall.sh

Client-specific removal is also supported:

./uninstall.sh --claude-only
./uninstall.sh --codex-only

Client-specific removal preserves the shared wrapper because the other client may still depend on it. Run ./uninstall.sh without a client filter after both clients are unwrapped to remove the installed wrapper.

Uninstalling removes the conditional wrapper and restores the original claude-code-sync and codex-sync hook commands. This means automatic OpenSync reporting becomes unconditional again. To disable OpenSync entirely, remove or disable the upstream sync hooks instead.

Privacy And Security

The wrapper does not read OpenSync credentials, prompt content, or tool results. For Claude Code, it temporarily buffers the hook JSON only to read cwd; the file is created with owner-only permissions and removed on success, failure, or interruption.

Configuration backups remain local and are created with owner-only permissions. They are never copied into this repository.

This tool controls automatic hook execution only. It does not:

• Delete data that was already uploaded.
• Block direct manual commands such as codex-sync sync or connectivity tests.
• Control other telemetry or reporting clients.
• Replace the access controls of the OpenSync server.

The Codex installer currently expects the top-level notify value to be a single-line array using double-quoted strings. It exits without modifying the file when that format is not recognized.

The installer also refuses to modify symlinked Claude or Codex configuration files because replacing a symlink would break dotfile-managed setups. Point --claude-config or --codex-config at the real file when you intentionally want it modified.

Development

./tests/test.sh
./scripts/scan-secrets.sh

The test suite covers path boundaries, symlinks, multiple roots, stdin and argument preservation, temporary-file cleanup, safe configuration updates, backups, idempotency, and uninstall behavior.

License

MIT