claude-wrapper: Instructions file for Claude Code

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
bash tests/test-machine-settings.sh
bash tests/test-claude-wrapper-lite.sh

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

Lint

shellcheck -S info lib/*.sh bin/claude-wrapper bin/claude-wrapper-lite tests/*.sh tests/lib/*.sh

CI (standards-check) runs shellcheck with the canonical config from smartwatermelon/github-workflows (standards/shellcheckrc: external-sources=true, source-path=SCRIPTDIR, disable=SC2310). To match CI locally, add --rcfile <path to that file>. Lib and test files source each other through variable paths (${WRAPPER_LIB}/logging.sh, ${TEST_DIR}/lib/op-guard.sh), which shellcheck cannot resolve unless external sourcing is enabled — without it, the # shellcheck source=... directives at those call sites are ignored and each one raises a false SC1091.

This repo has no .shellcheckrc of its own. A plain local run reads ~/.shellcheckrc instead, which CI never sees, so use --rcfile when the result must match CI — see PR #122.

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 → machine-settings.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. Locate caffeinate — hardcoded to /usr/bin/caffeinate, checked for executability; hard-fails if absent
5. Find real claude binary — scans $PATH for claude, skipping itself (the wrapper)
6. Validate binary — ownership and permission checks on the discovered binary
7. Initialize secrets loader — init_secrets_loader discovers per-project secrets files and authenticates if needed
8. Build injected args — build_remote_control_args computes --remote-control <session-name>, then build_machine_settings_args adds --settings <machine file>, both for interactive sessions only (applied later, at exec)
9. 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)
10. 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
11. exec — replaces the wrapper process with caffeinate -is <claude>, applying the injected args from step 8