If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/chriswalz/bit shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 3y ago

• 13 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Stale — last commit 3y ago
• ⚠ Single-maintainer risk — top contributor 86% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live chriswalz/bit repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/chriswalz/bit.

What it runs against: a local clone of chriswalz/bit — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in chriswalz/bit | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1201 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of chriswalz/bit. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/chriswalz/bit.git
#   cd bit
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of chriswalz/bit and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "chriswalz/bit(\\.git)?\\b" \\
  && ok "origin remote is chriswalz/bit" \\
  || miss "origin remote is not chriswalz/bit (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "cmd/bit_cmd.go" \\
  && ok "cmd/bit_cmd.go" \\
  || miss "missing critical file: cmd/bit_cmd.go"
test -f "cmd/complete.go" \\
  && ok "cmd/complete.go" \\
  || miss "missing critical file: cmd/complete.go"
test -f "cmd/suggestion_tree.go" \\
  && ok "cmd/suggestion_tree.go" \\
  || miss "missing critical file: cmd/suggestion_tree.go"
test -f "cmd/git.go" \\
  && ok "cmd/git.go" \\
  || miss "missing critical file: cmd/git.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1201 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1171d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/chriswalz/bit"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Bit is a modernized Git CLI wrapper written in Go that layers intuitive defaults, command/flag suggestions, and interactive autocompletion on top of native Git. It adds features like automatic branch fast-forwarding (bit sync), GitHub PR integration (bit pr), git-extras commands (bit release, bit info), and proactive suggestions while remaining fully compatible with Git—you can always fall back to raw git commands. Monolithic CLI structure: cmd/ contains all command implementations (bit_cmd.go orchestrates routing, with subcommands like sync.go, pr.go, release.go), gitextras/ wraps git-extras functionality, main.go bootstraps the Cobra CLI framework, and a suggestion engine (suggestion_tree.go, complete.go) generates interactive hints at runtime.

Git power users and development teams who want a friendlier CLI experience without abandoning Git itself. Developers who frequently switch branches, manage PRs, and want intelligent suggestions and autocompletion for filenames and branch names rather than memorizing Git flag syntax.

Actively developed and experimental; the README explicitly labels it as 'experimental' with recent additions (PR support, update command, interactive prompts via BIT_INTERACTIVE=true). Single-maintainer (chriswalz), has CI/CD (GoReleaser config, CodeQL analysis), and is distributed as a single statically-compiled binary via Homebrew/MacPorts, indicating production deployment readiness despite experimental status.

Moderate risk: single maintainer (chriswalz) with no visible team, thin test coverage (only cmd_test.go visible), and heavy reliance on shell integration for completion (scripts/parse_zsh_output_and_generate_suggestions_tree.go suggests shell-specific brittleness). Dependency on external tools (GitHub CLI for bit pr) creates operational coupling; Go 1.16+ minimum may become stale.

Recent focus on UX improvements: GitHub PR viewing/checking out (bit pr), simpler updates (bit update with self-update logic in update.go), expanded suggestions (~10x more per README), theme customization (BIT_THEME env var), and interactive mode support. Shell completion parsing suggests active work on shell integration.

git clone https://github.com/chriswalz/bit.git
cd bit
go mod download
go build -o bit .
./bit --help

Daily commands:

go build -o bit . && ./bit --help
# Or with debug output:
go run . --debug status
# Run tests:
go test ./...
# Run integration tests:
bash integration_tests.sh

• main.go — Application entry point that initializes the CLI and routes commands to the cmd package.
• cmd/bit_cmd.go — Core command dispatcher and root command definitions; all git subcommands are routed through here.
• cmd/complete.go — Implements intelligent command/flag suggestions and autocompletion logic, the primary UX differentiator.
• cmd/suggestion_tree.go — Builds and manages the suggestion hierarchy for flags and subcommands; critical for the suggestion feature.
• cmd/git.go — Git wrapper and execution layer that interfaces with the actual git binary; foundation for all git operations.
• go.mod — Defines all external dependencies including survey, go-prompt, and GitHub API client; required for reproducible builds.

Add a new Git subcommand wrapper

1. Create a public function in cmd/git_sub_cmds.go following the pattern Bit<CommandName>(args ...string) that wraps git.<Command>() calls (cmd/git_sub_cmds.go)
2. Register the command in cmd/bit_cmd.go by adding a case to the main command router and setting up flags via cobra/pflag (cmd/bit_cmd.go)
3. Add flag definitions and suggestions to cmd/flags_man_pages.go to enable intelligent suggestion support (cmd/flags_man_pages.go)
4. Add test cases in cmd/cmd_test.go to validate the wrapper behavior (cmd/cmd_test.go)

Add a new suggestion/autocompletion feature

1. Define the suggestion logic and data structure in cmd/suggestion_tree.go, extending the Tree or Node types as needed (cmd/suggestion_tree.go)
2. Integrate the suggestion lookup into cmd/complete.go by adding a case to the suggestion matching logic (cmd/complete.go)
3. If flags are involved, add their documentation to cmd/flags_man_pages.go to populate suggestions (cmd/flags_man_pages.go)
4. Test with interactive prompts using github.com/c-bata/go-prompt or github.com/AlecAivazis/survey/v2 integrations already in place (cmd/util.go)

Add a new GitHub-integrated command

1. Create a new command file (e.g., cmd/newfeature.go) that uses the GitHub API client from cmd/gh.go (cmd/gh.go)
2. Implement GitHub API calls using the google/go-github/v32 client already configured in cmd/gh.go (cmd/gh.go)
3. Register the command in cmd/bit_cmd.go and add it to the suggestion tree in cmd/suggestion_tree.go (cmd/bit_cmd.go)
4. Add tests in cmd/cmd_test.go that mock GitHub API responses (cmd/cmd_test.go)

Add a new git-extras utility command

1. Create a new file in gitextras/ (e.g., git-custom.go) following the pattern of existing git-* files (gitextras/git-info.go)
2. Implement the command using git execution wrappers from cmd/git.go and data parsing logic (cmd/git.go)
3. Register the command as a subcommand in cmd/bit_cmd.go and ensure it appears in help text (cmd/bit_cmd.go)
4. Add integration test coverage in integration_tests.sh (integration_tests.sh)

• Go 1.16 — Fast compilation, single binary distribution, excellent cross-platform support for CLI tools; aligns with modern git tooling (git itself is C but Go is standard for modern wrappers).
• github.com/c-bata/go-prompt — Provides real-time, interactive command suggestions with autocomplete in the terminal; essential for the primary UX differentiator (flag suggestions).
• github.com/AlecAivazis/survey/v2 — Interactive CLI form library for prompting users to select from suggestions or provide input; improves UX over raw git defaults.
• github.com/google/go-github/v32 — Type-safe GitHub API client for PR integration, release automation, and GitHub-aware commands.
• github.com/chriswalz/complete/v3 — Shell completion scaffolding for bash/zsh; allows bit to integrate with system shell completions.

• Wrapper around git binary instead of reimplementing git operations

  • Why: Git is battle-tested and widely understood; reimplementing would incur massive maintenance burden and risk correctness.
  • Consequence: Bit inherits all git's behavior but cannot deeply optimize specific operations; depends on git binary being installed and in PATH.

• Build suggestion tree statically via script (parse_zsh_output_and_generate_suggestions_tree.go) rather than dynamically at runtime

  • Why: Avoids parsing git help every time; reduces startup latency.
  • Consequence: Suggestions may lag behind new git versions until regenerated; maintainer must periodically run the parsing script.

• GitHub-specific features (PR integration, gh command) rather than abstraction over multiple git hosts

  • Why: GitHub is the dominant platform; tightly integrating GitHub features creates a compelling, cohesive UX.
  • Consequence: Limited support for GitLab, Bitbucket, or Gitea; not universal across all git hosting platforms.

• Interactive terminal UX (survey, go-prompt) instead of stateless flags

  • Why: Reduces cognitive load on users by guiding them through options; improves discoverability of git features.
  • Consequence: Requires interactive terminal; scripting with bit is less suitable than direct git calls; may conflict with piped input.

• Does not reimplement git core functionality (merge, rebase, pack, etc.); remains a wrapper and UI layer.
• Does not support non-GitHub git hosts (GitLab, Bitbucket, etc.) in PR and release automation; GitHub-centric by design.
• Does not provide offline functionality; requires git binary in PATH and internet for GitHub API calls.
• Does not handle SSH key management, credential storage, or authentication beyond what git natively provides.

Shell integration fragility: Suggestion generation relies on parsing zsh output (scripts/parse_zsh_output_and_generate_suggestions_tree.go), making it brittle across zsh versions and potentially non-functional on other shells. GitHub CLI dependency: bit pr silently fails if GitHub CLI is not installed; no fallback. Environment variables: BIT_INTERACTIVE=true must be explicitly set for interactive mode; default non-interactive behavior may surprise users. Incomplete theme support: Only BIT_THEME=inverted and BIT_THEME=monochrome documented; other themes may not exist. Test sparsity: Only cmd_test.go visible; most business logic untested, risking regressions. Git version assumption: Uses git command parsing that may break on older/newer Git versions.

• CLI Framework (Cobra) — Bit's entire command structure is built on Cobra (spf13/cobra); understanding its command/flag registration, subcommand routing, and plugin model is essential to extending bit
• Suggestion Trees / Trie-based Completion — The suggestion_tree.go file implements a tree of possible commands/flags that grows as you type; this data structure powers bit's core UX differentiation and is generated offline from zsh output
• Interactive CLI Prompts (Survey Pattern) — Bit uses github.com/AlecAivazis/survey for interactive prompts and go-prompt for real-time suggestion rendering; understanding this pattern is needed to enhance interactive mode (BIT_INTERACTIVE=true)
• Git Command Wrapping / Shell Command Execution — Bit's entire value comes from wrapping Git CLI (cmd/git.go executes git subprocesses and parses output); understanding how to safely shell out, parse JSON/text Git output, and handle errors is foundational
• GitHub API Integration (OAuth Token Management) — The bit pr command uses google/go-github/v32 client; you need to understand how it authenticates with GitHub, handles tokens, and manages API rate limits
• Single-Binary Distribution & Go Release Engineering — Bit is distributed as a static binary via .goreleaser.yml (GoReleaser config); understanding cross-platform compilation, binary packaging, and semantic versioning is needed for release workflows
• Fuzzy Search / Edit Distance (Levensthein for suggestions) — Bit likely uses lithammer/fuzzysearch (a dependency) to rank and filter suggestions as the user types; understanding fuzzy matching helps debug suggestion ranking and quality

• github/hub — Similar Git CLI wrapper that adds GitHub-specific commands; predecessor to modern GitHub CLI and conceptual inspiration for bit's PR integration
• jesseduffield/lazygit — Alternative modern Git CLI with TUI; solves similar UX problems but via interactive terminal UI rather than suggestions
• cli/cli — Official GitHub CLI (gh); bit's bit pr feature depends on this tool for PR operations
• tj/git-extras — Collection of shell-based Git extensions; bit wraps commands from this repo (release, info, effort, summary)
• dandavison/delta — Modern diff viewer for Git that complements bit; both target developers frustrated with vanilla Git UX

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for cmd/cmd_test.go and expand test coverage for Git subcommands

The repo has minimal test coverage - only cmd/cmd_test.go exists but the test file is empty or minimal. Given that cmd/git_sub_cmds.go, cmd/git.go, cmd/gh.go, and cmd/pr.go contain critical Git workflow logic, adding unit tests for these modules would significantly improve reliability. This is especially important for a Git CLI tool where user data integrity depends on correct command execution.

• [ ] Create tests in cmd/cmd_test.go for git_sub_cmds.go functions (branch creation, switching, merging patterns)
• [ ] Add tests for cmd/git.go to verify Git command wrapping and error handling
• [ ] Add tests for cmd/pr.go to validate GitHub PR creation/management logic with mocked GitHub API calls
• [ ] Use github.com/stretchr/testify (already in go.mod) for assertions
• [ ] Target minimum 60%+ code coverage for cmd/ package

Add GitHub Actions workflow for automated testing and linting on pull requests

While .github/workflows/codeql-analysis.yml exists for security scanning, there is no CI workflow for running tests, building binaries, or linting Go code on every PR. This is critical for maintaining code quality in an open-source Go project. The repo already has .goreleaser.yml for releases, indicating release automation is planned.

• [ ] Create .github/workflows/test.yml that runs 'go test ./...' on push and PR events
• [ ] Add Go linting step using golangci-lint action to check code quality per CONTRIBUTING.md standards
• [ ] Add 'go build' step to verify the binary compiles on Linux, macOS, and Windows matrices
• [ ] Configure the workflow to enforce test passage before PR merge by adding branch protection rules

Complete and document the gitextras/ module with tests and CLI integration

The gitextras/ directory contains 4 unintegrated utility modules (git-effort.go, git-info.go, git-release.go, git-summary.go) that appear to extend Git functionality but have no visible test files or cmd/ integration points. These are valuable Git extras but are orphaned. Adding tests and integrating them into the bit CLI would expand the tool's capabilities and provide clear examples for contributors.

• [ ] Create gitextras/gitextras_test.go with unit tests for each git-*.go module (effort, info, release, summary functions)
• [ ] Add gitextras command integration in cmd/git_sub_cmds.go or create cmd/gitextras.go to expose these commands via 'bit effort', 'bit info', etc.
• [ ] Document the new gitextras commands in README.md with usage examples
• [ ] Ensure github.com/thoas/go-funk (already in go.mod) is leveraged where applicable in gitextras modules

• Add unit tests for cmd/git.go functions (parseGitOutput, runGitCommand, etc.) that currently lack coverage; this foundation test would prevent regressions in the core Git wrapper
• Document the suggestion tree generation process and environment setup in CONTRIBUTING.md; currently scripts/parse_zsh_output_and_generate_suggestions_tree.go is undocumented and unclear how maintainers regenerate suggestions
• Implement fallback/graceful degradation when GitHub CLI is not installed for bit pr instead of silently failing; add a clear error message and link to installation docs

The codebase has significant security concerns primarily related to outdated dependencies and Go version. The project uses Go 1.16 (end-of-life) and multiple outdated third-party libraries that no longer receive security patches. The most critical issues are: (1) unsupported Go runtime, (2) outdated github.com/google/go-

• High · Outdated Go Version — go.mod. The project targets Go 1.16, which was released in February 2021 and is no longer supported. This version lacks security patches and bug fixes from newer releases. Go 1.16 reached end-of-life in December 2021. Fix: Update to a currently supported Go version (1.21 or later). Modify 'go 1.16' to 'go 1.21' or newer in go.mod and test thoroughly.
• High · Vulnerable Dependency: github.com/google/go-github/v32 — go.mod. The project uses github.com/google/go-github/v32 v32.1.0, which is an outdated major version. Newer versions (v45+) contain security fixes and improvements. Using outdated library versions exposes the application to known vulnerabilities. Fix: Upgrade to the latest stable version of github.com/google/go-github (v57+). Review the changelog for breaking changes before upgrading.
• High · Outdated Cobra Framework — go.mod. The project uses github.com/spf13/cobra v1.1.3 (released November 2020). This is significantly outdated and may contain security vulnerabilities and bugs fixed in later versions. Fix: Upgrade to the latest stable version of Cobra (v1.7+). Test CLI functionality thoroughly after upgrading.
• Medium · Multiple Outdated Dependencies — go.mod. Several dependencies are outdated or deprecated, including github.com/c-bata/go-prompt v0.2.5, github.com/lithammer/fuzzysearch v1.1.1, and github.com/thoas/go-funk v0.7.0. These versions may lack security patches. Fix: Run 'go get -u' to update all dependencies. Review and test changes, particularly for packages handling user input or external data.
• Medium · Transitive Dependency Concerns — go.mod. The project includes transitive dependencies marked as 'indirect' (e.g., github.com/bradfitz/iter, github.com/c4milo/unpackit) which may be outdated. These are not directly managed and could introduce vulnerabilities. Fix: Run 'go mod tidy' and 'go mod graph' to analyze the dependency tree. Remove unused indirect dependencies and update others.
• Medium · Insecure HTTP Usage in Update Mechanism — go.mod, cmd/update.go. The project includes github.com/tj/go-update v2.2.4+incompatible, which handles software updates. This dependency may use insecure HTTP for downloads. Verify that update mechanisms use HTTPS and validate checksums. Fix: Review update.go to ensure all downloads use HTTPS and include signature/checksum verification. Consider using signed releases or content-addressable storage.
• Low · Unpackit Dependency in Build Chain — go.mod. The indirect dependency github.com/c4milo/unpackit handles archive extraction. Archive operations can be vulnerable to path traversal attacks if not properly validated. Fix: Review code that uses unpackit to ensure proper validation of archive contents. Use security auditing tools like 'go list -json=...' to track this dependency.
• Low · Missing Security Configuration — .goreleaser.yml. The .goreleaser.yml file exists but content is not provided. Verify that release automation includes proper security practices such as checksum generation, signing, and SBOM generation. Fix: Ensure the release configuration: 1) Generates checksums for all artifacts, 2) Signs releases with GPG, 3) Generates SBOMs, 4) Publishes to trusted repositories only.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.