What Is Beads Stealth Mode and When to Use It: A Complete Guide

Beads stealth mode is a "flush-only" configuration that suppresses all Git operations while still generating AI-optimized workflow context, making it ideal for CI/CD pipelines, automation scripts, and collaborative environments where repository modification is restricted or unwanted.

Beads stealth mode provides a lightweight, side-effect-free way to leverage the gastownhall/beads AI context engine without touching your repository's Git history. When enabled, the tool skips commits, pushes, and remote checks while still delivering the structured markdown context that Claude, Gemini, and other AI assistants require. Whether you're running automated workflows or working in shared repositories, understanding when and how to activate this mode ensures you get the benefits of Beads without the Git overhead.

How Beads Stealth Mode Works

Stealth mode operates as a controlled bypass of Beads' Git workflow layer. The implementation evaluates two input sources to determine behavior: the --stealth command-line flag and the no-git-ops configuration key.

In cmd/bd/prime.go, the core logic resolves the mode at lines 86-89:

stealthMode := primeStealthMode || config.GetBool("no-git-ops")

When stealthMode evaluates to true, the application passes this boolean to outputPrimeContext (lines 120-125), which omits Git-operation wording and workflow suggestions from the generated markdown.

Flag and Configuration

Users can trigger stealth mode transiently or permanently. The transient method uses the --stealth boolean flag defined in cmd/bd/prime.go at lines 30-33. For persistent behavior across sessions, the no-git-ops config key allows you to set the default once:

bd config set no-git-ops true

This configuration is checked on every bd prime invocation, ensuring CI environments and automation scripts maintain consistent behavior without flag repetition.

Git-Level Invisibility

Beyond suppressing Git commands, stealth mode configures your repository to hide Beads-specific files from collaborators. The cmd/bd/init_stealth.go file handles this by manipulating .git/info/exclude rather than the tracked .gitignore file.

Running bd init --stealth executes the exclusion logic starting at line 46, appending patterns defined at lines 14-21:

# Beads stealth mode (added by bd init --stealth)

.beads/
.claude/settings.local.json

Because these entries live in .git/info/exclude, they apply only to your local clone, keeping Beads metadata invisible to others while remaining uncommitted.

AI Context Without Side Effects

The primary function of bd prime—generating structured context for AI tools—remains fully operational in stealth mode. The difference lies solely in the output format: rather than suggesting commit messages or push operations, the tool delivers pure repository context suitable for ingestion by Claude, Gemini, or other LLM-based coding assistants.

When to Use Beads Stealth Mode

Stealth mode excels in four specific operational contexts where Git mutations are undesirable or impossible.

• CI/CD pipelines: Runners often lack write permissions or remote push access. Stealth mode eliminates permission errors by ensuring no Git commands are emitted, allowing the pipeline to extract context for AI analysis without authentication failures.

• Automation and bots: Code-generation scripts that must remain read-only can safely invoke bd prime --stealth. This guarantees a pure, side-effect-free output that feeds into AI prompts without risking repository contamination.

• Collaborative repositories: When working in shared codebases where you don't want to expose Beads configuration files (.beads/, Claude settings) to teammates, stealth mode keeps these files local-only via .git/info/exclude exclusions.

• Testing environments: Throw-away clones and ephemeral test workspaces benefit from the no-git-ops config, keeping test suites fast and deterministic by skipping remote checks and commit operations.

How to Enable Beads Stealth Mode

Activation methods vary by use case, ranging from one-off commands to permanent IDE integrations.

One-off Command Execution

For ad-hoc usage where you need context without Git side effects:

bd prime --stealth

This invocation sets stealthMode to true for the current execution only, as implemented in the flag parsing logic at cmd/bd/prime.go.

Persistent Configuration

To make stealth the default for a workspace or environment:

bd config set no-git-ops true

After execution, any subsequent bd prime call (including those triggered by hooks) behaves as if --stealth were passed, referencing this configuration value at runtime.

IDE Integration Setup

When installing hooks for AI assistants, append the --stealth flag to ensure the integration remains non-mutative. For Claude Code:

bd setup claude --stealth

The installer in cmd/bd/setup/claude.go (lines 40-44) detects this argument and writes the hook command as bd prime --stealth rather than the default. The same pattern applies to Gemini integration via cmd/bd/setup/gemini.go.

Repository Initialization

To establish local-only exclusions for Beads files:

bd init --stealth

As documented in docs/SETUP.md at lines 58-60, this command configures your repository's exclude patterns without modifying tracked files, ensuring your Beads setup remains invisible to collaborators.

Summary

• Beads stealth mode is a flush-only operational state controlled by the --stealth flag or no-git-ops configuration key in cmd/bd/prime.go.
• The mode suppresses Git commits, pushes, and remote checks while preserving AI context generation, passing the stealthMode boolean to outputPrimeContext.
• Local file hiding is achieved via cmd/bd/init_stealth.go manipulating .git/info/exclude to keep .beads/ and Claude settings unshared.
• Primary use cases include CI/CD pipelines, read-only automation scripts, collaborative repositories requiring privacy, and testing environments.
• Integration hooks for Claude and Gemini respect the --stealth argument, ensuring AI tools receive context without triggering repository mutations.

Frequently Asked Questions

Does Stealth mode prevent Beads from reading Git history?

No. Stealth mode only suppresses write operations and workflow suggestions. Beads continues to read your repository structure, file contents, and Git history to generate comprehensive AI context; it simply avoids emitting commits, pushes, or remote synchronization commands.

Can I use Stealth mode in CI/CD pipelines?

Yes. This is a primary design target for the feature. Because stealth mode guarantees no Git commands are executed, you avoid permission errors in read-only runners while still extracting AI-optimized context for code review, documentation generation, or automated refactoring tasks.

How does Stealth mode affect Claude Code or Gemini integration?

When installed with bd setup claude --stealth (or the Gemini equivalent), the hook commands automatically include the --stealth flag. This ensures Claude Code, Gemini, or other integrated tools receive the full repository context via bd prime without triggering side effects in your working tree or remote repository.

Is Stealth mode reversible?

Yes. If you enabled it via configuration, run bd config set no-git-ops false to restore default Git-integrated behavior. For one-off usage, simply omit the --stealth flag on subsequent commands. The .git/info/exclude modifications made by bd init --stealth can be manually removed from that file if you wish to stop hiding Beads files locally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}