unclaude

An AI sanitizer and setup script with a TUI and CLI.

Why?

Do you make VSCode your commit author? Do you write "sent from my dell xps" in your PRs?

If not, then maybe you don't want AI agents leaving their dirty footprints all over your git history. This package will clean those up. Tested on Claude Code Web.

I also added support for a few tools I consider broadly useful for AI-enabled projects; these are all opt-in.

Quick start

# ───────── Install ──────────

# Launch the TUI anywhere
npx @buffbirb/unclaude@latest

# Run in CLI mode; recommended for cloud pre-session scripts
npx @buffbirb/unclaude@latest install --git-user "Your Name" --git-email "[email protected]"

# Certain features (clangd on linux, apple container) may require sudo
# Don't use this in cloud pre-session scripts
sudo -v && npx @buffbirb/unclaude@latest

# ───────── Extras ───────────

# Run opencode with token compression
headroom-start opencode

# Run opencode in sandbox with --dangerously-skip-permissions
sbx opencode

# Run claude in sandbox with --dangerously-skip-permissions and headroom token compression
headroom-start sbx claude

Presets

Local environments are very simple to set up, but cloud environments employ a lot of tricks to make their attributions stick:

• system prompt overrides CLAUDE.md
• container/env-level git config overrides settings.json
• tracked files are reverted between the pre-install script and session start, potentially scrubbing .claude/* and .gitignore
• GitHub PRs use MCP, most likely remote, which is not interceptable

This script offers three preset solutions:

• Local preset — minimal setup for local repos; no commits.
• Hybrid preset — setup for local and managed environments; agent hooks and pr workflow are installed and committed.
• Cloud preset — pre-session setup for managed environments; .git/hooks are written directly, but a pr workflow must be committed beforehand.

The preset is auto-detected from the CLAUDE_CODE_REMOTE env var (cloud if set, local otherwise). Hybrid must be selected manually with --preset hybrid in CLI mode or key 2 in the TUI.

Features

| Feature | What it does | |---|---| | Stop Telemetry | Exports CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 in ~/.airc | | Set git config user.name / user.email | Runs git config --global user.name/user.email so cloud agents commit under your identity | | Agent JSON config for git commits | Sets attribution: { commit: '', pr: '' } in Claude Code settings.json | | Agent SessionStart hook for git commits | Registers a Claude Code SessionStart hook that installs a bash commit-msg hook in .git/hooks (and sets local git identity) at the start of every session | | Git commit-msg hook (.git/hooks) | Writes a commit-msg hook directly to .git/hooks/ — survives harness resets that revert tracked files | | Git branch rename (immediate + hook) | Renames the current claude/* or claude-* branch immediately, and installs a pre-push hook in .git/hooks/ that intercepts any claude/* push, rewrites it to the stripped name on the remote, and aborts the original push | | GitHub Action for PR body | Writes a workflow that strips Claude attribution from PR bodies on opened/edited | | LSP | Enables ENABLE_LSP_TOOL in Claude Code settings; installs LSP plugins for C++, Swift, Python, TypeScript, Go, and Rust; installs system language servers (OS-aware); enables LSP in OpenCode config | | Headroom | Installs headroom via uv; writes a headroom-start wrapper script to ~/.local/bin/ that starts the proxy and execs its arguments (e.g. headroom-start claude) | | Apple Container Sandbox | Downloads and installs the Apple container CLI from apple/container if missing, then writes an sbx wrapper script to ~/.local/bin/ that runs Claude or OpenCode inside an Apple Container, transparently forwarding the host's headroom proxy to the container (macOS only) | | OpenSpec | Installs @fission-ai/openspec globally via npm; optionally runs openspec init in the current directory |

Feature matrix

| Feature | Agents | Scope | Local default | Hybrid default | Cloud default | |---|---|---|---|---|---| | Stop Telemetry | Claude Code | Global | ✓ | ✓ | ✓ | | Set git config user.name / user.email | Claude Code, OpenCode | Global | | | ✓ | | Agent config for git commits | Claude Code | Global, Project | ✓ | ✓ | ✓ | | Agent SessionStart hook for git commits | Claude Code | Global, Project | | ✓ | | | Git commit-msg hook (.git/hooks) | Claude Code, OpenCode | Project | | | ✓ | | Git branch rename (immediate + pre-push) | Claude Code, OpenCode | Project | | ✓ | ✓ | | GitHub Action for PR body | Claude Code, OpenCode | Project | | ✓ | | | LSP | Claude Code, OpenCode | Global | | | | | Headroom | Claude Code, OpenCode | Global | | | | | Apple Container Sandbox | Claude Code, OpenCode | Global | | | | | OpenSpec | Claude Code, OpenCode | Global (install), Project (init) | | | |

Personalization

If you select certain features, a second screen asks whether to personalize the setup to your identity.

| Field | Purpose | |---|---| | Git user | Your user.name (prefilled from git config --global user.name). Used by Set git config user.name / user.email and Agent SessionStart hook for git commits. | | Git email | Your user.email (prefilled from git config --global user.email). Used by Set git config user.name / user.email and Agent SessionStart hook for git commits. | | Branch prefix | Prepended to renamed claude/* branches (e.g., username/foo). Used by Git branch rename (immediate + pre-push). |

This is most useful in managed cloud environments (e.g., Claude Code Web) where the AI does not have access to your local git configuration. By embedding your identity, commits and branch metadata are authored under your name rather than an AI-generated default.

Note: Commits will still show as unverified on GitHub / GitLab because most cloud providers do not offer a secure place to store a GPG or SSH signing key.

Git Settings

Currently only .gitignore is amended with a section covering generated attribution-related files.

Optional Tools

LSP Install Details

When the LSP feature is selected, the system language servers are installed. If Claude is selected, plugins are installed (not needed for OpenCode).

| Language | Claude Plugin | System LSP Install (OS-aware) | |---|---|---| | C++ | clangd-lsp | macOS: brew install llvm + add $(brew --prefix llvm)/bin to ~/.airc PATH; Linux: apt install clangd → fallback dnf install clang-tools-extra → fallback pacman -S clang; Windows: winget install LLVM.LLVM | | Swift | swift-lsp | No system install needed (Xcode toolchain assumed) | | Python | pyright-lsp | npm install -g pyright | | TypeScript | typescript-lsp | npm install -g typescript-language-server typescript | | Go | gopls-lsp | go install golang.org/x/tools/gopls@latest | | Rust | rust-analyzer-lsp | rustup component add rust-analyzer |

Headroom helper

headroom-start <command> starts the headroom proxy if it isn't already running, then execs its arguments. On each invocation it:

• Starts the proxy if needed — checks port 8787 with lsof; if nothing is there, launches headroom proxy --port 8787 in the background with HEADROOM_CODE_AWARE_ENABLED=1 and HEADROOM_HOST=0.0.0.0, then waits briefly for it to bind.
• Sets LLM base URLs — exports ANTHROPIC_BASE_URL=http://localhost:8787 and OPENAI_BASE_URL=http://localhost:8787/v1 so any agent started after it automatically routes through the proxy.
• Execs the rest of the command — replaces itself with "$@", so headroom-start claude is equivalent to running claude directly, just with the proxy in front.

If called with no arguments it just starts the proxy and sets the env vars, which is useful when sourced in a pre-session script.

Sandbox (macOS only)

sbx claude / sbx opencode runs the agent inside an Apple Container. On each launch it:

• Fetches the image — pulls the latest sandbox image from GHCR if a newer version is available; falls back to the locally cached image when offline.
• Skips the directory trust warning — the working directory is bind-mounted into the container at /workspace, so the agent starts there without prompting.
• Skips the permissions warning — --dangerously-skip-permissions is passed automatically; you never see the interactive prompt.
• Copies Anthropic auth from the host — forwards ANTHROPIC_API_KEY if set, otherwise extracts your OAuth token from the macOS Keychain so you don't need to log in again inside the container.
• Copies GitHub auth from the host — forwards a GitHub token so gh and git push work without a separate gh auth login inside the container (see below for how the token is scoped).

The sandbox image is based on node:22-bookworm-slim and comes with git, curl, sudo, jq, python3, gh, and the agent CLI pre-installed. git is pre-configured to use the forwarded token for HTTPS operations and to rewrite SSH remotes to HTTPS, so the agent can clone and push without an SSH key.

GitHub auth inside the sandbox (macOS only)

The sandbox runs the agent with --dangerously-skip-permissions, so any GitHub token forwarded into it can be used unattended. To keep the blast radius minimal, sbx can mint a short-lived, single-repo token from a GitHub App instead of forwarding your full gh login.

# One-time setup after install step:
npx @buffbirb/unclaude container-gh-app

Follow the instructions and set up a GitHub app. The process is mostly automatic.

How it works on each sbx claude launch:

1. sbx reads the working directory's origin remote to determine owner/repo.
2. It signs a JWT with the App's private key read straight from the macOS Keychain (the key never enters the container) and mints an installation token scoped to only that repo, with contents / pull_requests / workflows / issues = write. There is no administration permission, so the token cannot delete repositories or touch any other repo.
3. That ~1-hour token is forwarded as GITHUB_TOKEN / GH_TOKEN. gh and git push over HTTPS both use it (SSH github.com remotes are auto-rewritten to HTTPS inside the image).

The token lasts up to 1 hour and cannot be refreshed from inside the container (the key stays on the host). For a session longer than an hour, re-run sbx to mint a fresh one.

Headroom inside the sandbox (macOS only)

If headroom is already running on the host when sbx launches, the container's LLM base URL is automatically pointed at it:

• Claude → ANTHROPIC_BASE_URL=http://<host>:8787
• OpenCode → additionally OPENAI_BASE_URL=http://<host>:8787/v1

The host address is derived from Apple Container's bridge network (192.168.64.0/24 by default; the host is its .1 address). headroom-start binds to 0.0.0.0 so it's reachable from the container.

Headroom is a transparent proxy — it forwards the client's real credentials upstream and injects none of its own. The container still needs genuine Anthropic credentials, forwarded by sbx in priority order:

1. ANTHROPIC_API_KEY from the host environment
2. OAuth access token extracted from the macOS Keychain (Claude Code-credentials entry) → forwarded as CLAUDE_CODE_OAUTH_TOKEN

If headroom is not running at launch time, the container talks to the Anthropic API directly using those same credentials.

CLI arguments

Running with no arguments launches the interactive TUI. Pass a subcommand for non-interactive use:

unclaude install   [--preset <name>] [--agents <list>] [--scopes <list>] [--features <list>] [--no-gitignore]
                   [--git-user <name>] [--git-email <email>] [--branch-prefix <prefix>]
unclaude uninstall [--preset <name>] [--agents <list>] [--scopes <list>] [--features <list>] [--no-gitignore]
                   [--git-user <name>] [--git-email <email>]

Each list option takes a comma-separated value. Omitting --scopes or --agents defaults to all valid values; omitting --features uses the preset's defaults.

| Option | Description | |---|---| | --preset | local, hybrid, cloud (default: cloud if CLAUDE_CODE_REMOTE is set, else local; hybrid must be selected manually) | | --agents | claudeCode, openCode | | --scopes | global, project | | --features | stopTelemetry, setGitCreds, stripCommitJSON, stripCommitAgentHook, stripCommitHook, renameBranchGit, stripPrWorkflow, lsp, headroom, openspec | | --no-gitignore | Skip adding generated project-scope files to .gitignore (default: adds them) | | --git-user | Your user.name — used by setGitCreds and stripCommitAgentHook. On uninstall, only unsets global config when the current value matches. | | --git-email | Your user.email — used by the same features as --git-user. On uninstall, only unsets global config when the current value matches. | | --branch-prefix | Prefix for renamed claude/* branches (e.g. username) |

Development

npm install
npm run dev      # run (tsx, no build step)
npm run build    # compile → dist/
npm publish      # builds automatically via prepublishOnly

Requires Node ≥ 18 and tsx (npm install handles dev dependencies).