claude-wrapper CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

A Bash wrapper around the Claude Code CLI (claude) that intercepts invocations to inject git identity, GitHub tokens, 1Password secrets, SSH key isolation, and automatic remote-control session naming before delegating to the real claude binary. Installed by symlinking bin/claude-wrapper to ~/.local/bin/claude so it shadows the real binary in $PATH.

Commands

Run tests

bash tests/test-wrapper.sh
bash tests/test-gh-token-permissions.sh
bash tests/test-remote-session.sh

There is no test runner script — run individual test files directly. No npm test or make test.

Lint

shellcheck --external-sources lib/*.sh bin/claude-wrapper tests/*.sh

Use --external-sources because lib files source each other via variables (${WRAPPER_LIB}/logging.sh), and plain shellcheck emits false SC1091 warnings.

Debug mode

CLAUDE_DEBUG=true claude

Enables verbose DEBUG: output to stderr from all modules.

Architecture

Execution flow (bin/claude-wrapper)

The wrapper is a single orchestrator that sources modules in dependency order, then execs the real binary:

1. Resolve own path — realpath to handle symlinks
2. Source libs — logging.sh → permissions.sh → path-security.sh → launch-dir-check.sh → git-identity.sh → credentials.sh → secrets-loader.sh → binary-discovery.sh → pre-launch.sh → remote-session.sh. Sourcing credentials.sh has the side effect of fetching OP_SERVICE_ACCOUNT_TOKEN from the macOS Keychain and GH_TOKEN from the 1Password Automation vault (see below).
3. Check launch directory — check_launch_dir warns (non-blocking) if CWD is exactly $HOME or $HOME/Developer, since neither is a git repo and both carry an unrelated accumulated MCP server surface in ~/.claude/.claude.json
4. Find real claude binary — scans $PATH for claude, skipping itself (the wrapper)
5. Validate binary — ownership and permission checks on the discovered binary
6. Initialize secrets loader — init_secrets_loader discovers per-project secrets files and authenticates if needed
7. Build remote-control args — build_remote_control_args computes --remote-control <session-name> for interactive sessions (applied later, at exec)
8. Inject 1Password secrets — if secrets are available, inject_secrets runs op inject to resolve op://Automation/... references from per-project .claude/secrets.op; authentication uses OP_SERVICE_ACCOUNT_TOKEN (no TouchID prompt)
9. Run pre-launch hook — if secrets are available, run_pre_launch_hook runs .claude/pre-launch.sh from the git root if it exists and passes security validation
10. exec — replaces the wrapper process with the real binary, applying the remote-control args from step 7