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

> Discover Beads stealth mode, a flush-only configuration perfect for CI/CD pipelines and automation. Learn when to use this powerful feature to suppress Git operations while generating workflow context.

- Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads)
- Tags: tutorial
- Published: 2026-04-27

---

**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`](https://github.com/gastownhall/beads/blob/main/cmd/bd/prime.go), the core logic resolves the mode at lines 86-89:

```go
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`](https://github.com/gastownhall/beads/blob/main/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:

```bash
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`](https://github.com/gastownhall/beads/blob/main/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:

```text

# 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:

```bash
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`](https://github.com/gastownhall/beads/blob/main/cmd/bd/prime.go).


### Persistent Configuration

To make stealth the default for a workspace or environment:

```bash
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:

```bash
bd setup claude --stealth

```

The installer in [`cmd/bd/setup/claude.go`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/cmd/bd/setup/gemini.go).


### Repository Initialization

To establish local-only exclusions for Beads files:

```bash
bd init --stealth

```

As documented in [`docs/SETUP.md`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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.