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/BloopAI/bloop 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.

GO — Healthy across all four use cases

• 11 active contributors
• Distributed ownership (top contributor 42% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{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 BloopAI/bloop repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/BloopAI/bloop.

What it runs against: a local clone of BloopAI/bloop — 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 BloopAI/bloop | 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 oss exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 549 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of BloopAI/bloop. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/BloopAI/bloop.git
#   cd bloop
#
# 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 BloopAI/bloop and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "BloopAI/bloop(\\.git)?\\b" \\
  && ok "origin remote is BloopAI/bloop" \\
  || miss "origin remote is not BloopAI/bloop (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 oss >/dev/null 2>&1 \\
  && ok "default branch oss exists" \\
  || miss "default branch oss no longer exists"

# 4. Critical files exist
test -f "server/bleep/Cargo.toml" \\
  && ok "server/bleep/Cargo.toml" \\
  || miss "missing critical file: server/bleep/Cargo.toml"
test -f "apps/desktop/src-tauri/src/main.rs" \\
  && ok "apps/desktop/src-tauri/src/main.rs" \\
  || miss "missing critical file: apps/desktop/src-tauri/src/main.rs"
test -f "apps/desktop/src/App.tsx" \\
  && ok "apps/desktop/src/App.tsx" \\
  || miss "missing critical file: apps/desktop/src/App.tsx"
test -f "client/package.json" \\
  && ok "client/package.json" \\
  || miss "missing critical file: client/package.json"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 549 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~519d)"
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/BloopAI/bloop"
  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).

bloop is a fast code search engine written in Rust that combines full-text indexing via Tantivy, semantic search via Qdrant embeddings, and AI-powered conversational search to let developers ask natural language questions about their codebase and generate patches. It powers a desktop app (Tauri-based) and CLI that syncs local and GitHub repositories, enabling ChatGPT-like interactions with your source code as context. Monorepo with two main Cargo members: server/bleep (Rust indexing engine, full-text & semantic search, repository sync) and apps/desktop/src-tauri (Tauri-based desktop app wrapping the server). TypeScript/React frontend in apps/desktop/src communicates with the Rust backend via Tauri IPC. Qdrant vector DB and Tantivy indexes stored on-disk; CLI entrypoint in server, GUI entrypoint in desktop app.

Developers and engineering teams who need to quickly understand large or unfamiliar codebases, refactor duplicated logic, document poorly-commented libraries, or generate features using existing code as context. Spans individual contributors to teams using it for on-device (privacy-focused) semantic search without external API dependencies.

Actively developed and production-ready: the repo shows a mature tech stack (1.1M lines of Rust, 1M lines of TypeScript), structured GitHub workflows for CI/CD (client-test, server-test, tauri-test, tauri-release), and multiple polished release artifacts (desktop binaries for macOS/Windows/Linux). Tauri ecosystem integration and dual packaging (CLI + desktop) suggest post-MVP maturity, though the fast-moving AI/search landscape means continuous feature iteration.

Moderate risk from heavy dependencies on Tantivy and Qdrant (both external Rust crates that evolve independently), plus Tauri's ongoing stability in the GUI framework space. Single organization (BloopAI) maintains this, so contributor velocity depends on that team's bandwidth. The monorepo structure (server + desktop in one Cargo workspace) means changes to core indexing can cascade to both frontends; no observed pinned version constraints in Cargo.toml suggests bleeding-edge dependency management.

Active release cycle visible in GitHub workflows: build-on-release.yml and tauri-release.yml trigger on tags, client-test.yml and server-test.yml run per PR, and dependencies.yml monitors updates. The presence of local_config.json setup instructions and OpenAI API integration suggests ongoing work on the conversational/Code Studio features. Desktop app has platform-specific Qdrant binaries pre-bundled (qdrant-* in apps/desktop/src-tauri/bin), indicating active macOS/Windows/Linux support.

git clone https://github.com/BloopAI/bloop.git
cd bloop
git checkout oss
echo '{"github_access_token":"YOUR_TOKEN","openai_api_key":"YOUR_KEY"}' > local_config.json
# For desktop: cd apps/desktop && npm install && npm run tauri dev
# For CLI: cd server/bleep && cargo run --release

Daily commands: Desktop dev: cd apps/desktop && npm install && npm run tauri dev (requires Rust toolchain + Node.js). Server CLI: cd server/bleep && cargo run --release (listen on localhost by default per README.md stub). Tests: npm run test in desktop, cargo test in server (GitHub Actions runs client-test.yml and server-test.yml per PR).

• server/bleep/Cargo.toml — Workspace root for the Rust backend; defines the primary search engine dependencies and build profiles.
• apps/desktop/src-tauri/src/main.rs — Desktop application entry point using Tauri; bridges the Rust backend and TypeScript UI.
• apps/desktop/src/App.tsx — Main React entry point for the web UI; orchestrates conversation search and code navigation features.
• client/package.json — Client-side dependencies and build configuration for the web interface shared across desktop and server deployments.
• Cargo.toml — Workspace-level Cargo manifest defining all Rust members, profiles, and patches for the fast search engine core.
• apps/desktop/src-tauri/config/config.json — Tauri desktop app configuration including window setup, permissions, and binary bundling.
• .github/workflows/build-on-release.yml — CI/CD pipeline for building and releasing desktop and server binaries across multiple platforms.

• Bleep Search Engine (Rust) — Core indexing and regex search across codebases; tokenizes and indexes files

Add a New Chat Command or Search Feature

1. Define the new command handler in the Tauri backend (apps/desktop/src-tauri/src/backend.rs)
2. Add the corresponding UI input component in the chat interface (apps/desktop/src/TextSearch.tsx)
3. Wire up the frontend API call to invoke the Tauri command (apps/desktop/src/App.tsx)
4. Add integration tests to the build workflow (.github/workflows/tauri-test.yml)

Integrate a New Vector Database or Search Backend

1. Add database client dependency to the Rust workspace (server/bleep/Cargo.toml)
2. Implement database integration module (similar to Qdrant in desktop) (apps/desktop/src-tauri/src/qdrant.rs)
3. Update configuration to support the new backend connection (apps/desktop/src-tauri/src/config.rs)
4. Add environment template variables (.env.example)

Add a New Desktop Feature or Panel

1. Create a new React component in the apps/desktop/src directory (apps/desktop/src/App.tsx)
2. Add routing and state management for the feature (apps/desktop/src/App.tsx)
3. Style using Tailwind CSS via the config (apps/desktop/tailwind.config.cjs)
4. Test in Storybook if reusable across client library (client/.storybook/main.cjs)

Add Support for a New Programming Language or Repository Type

1. Extend backend repository sync logic and indexing rules (server/bleep/Cargo.toml)
2. Update Tauri backend handlers to process the new language's symbol/file metadata (apps/desktop/src-tauri/src/backend.rs)
3. Add language-specific UI filters or display logic in the search UI (apps/desktop/src/TextSearch.tsx)
4. Update tests and release workflow (.github/workflows/build-on-release.yml)

• Rust (Bleep engine core) — Blazing-fast regex and semantic search with minimal memory footprint; production-grade performance for large codebases.
• Tauri (Desktop framework) — Lightweight, secure cross-platform desktop app that avoids Electron's overhead while leveraging native OS capabilities.
• React + TypeScript (Frontend) — Modern reactive UI framework with type safety for complex conversational search and code navigation features.
• Qdrant (Vector database) — High-performance vector similarity search for semantic code understanding; built-in to desktop binary with bundled models.
• Vite (Build tool) — Fast, modern build pipeline with HMR for development; integrates seamlessly with Tauri for optimized production bundles.

• Embed Qdrant in the desktop app instead of remote-only

  • Why: Offline-first capability and reduced latency for personal code exploration on local machines.
  • Consequence: Increases desktop binary size and storage footprint; requires shipping pre-trained models with the app.

• Rust backend + React frontend separation

  • Why: Leverages Rust for performance-critical search while keeping UI dynamic and responsive with JavaScript.
  • Consequence: Added IPC/Tauri boundary adds latency (~5-10ms per call); requires coordinated testing across layers.

• Tauri over Electron

  • Why: Smaller bundle size, native OS integration, and better security model for code traversal.
  • Consequence: Narrower plugin ecosystem compared to Electron; some platform-specific quirks in windowing and system integration.

• Does not provide real-time collaborative editing; focused on read-only search and AI-assisted navigation.
• Does not handle authentication or multi-user access control; designed for single-user or local-only usage.
• Not a replacement for git workflows; complements version control but does not manage commits or branches.
• Does not provide IDE-level debugging; focuses on code understanding and search, not runtime inspection.

local_config.json is mandatory: Without github_access_token and openai_api_key at repo root, conversational search and Code Studio features will fail silently or error at runtime. Rust workspace setup: Both server/bleep and apps/desktop/src-tauri share the root Cargo.lock; cargo build at root builds both. Tauri binary bundling: Desktop app expects platform-specific Qdrant binaries in apps/desktop/src-tauri/bin/; missing these breaks the built app. Node + Rust toolchain required: Desktop dev needs both npm and rustc; no fallback to pre-built server. OpenAI API costs: Code Studio and conversational features call OpenAI APIs per-query; key account has live charges. Nix + direnv optional: .envrc and .gitpod.Dockerfile suggest reproducible environments, but not required if you have Rust/Node already.

• Full-Text Indexing (Tantivy) — bloop's regex and keyword search speed depends on inverted indexes built by Tantivy; understanding tokenization, stemming, and query parsing is key to optimizing search performance and relevance.
• Vector Embeddings & Semantic Search (Qdrant) — The 'conversational search' feature converts queries and code snippets to embeddings, then finds similar code via cosine distance; understanding embedding models and approximate nearest neighbor search explains why semantic search works and its latency trade-offs.
• Abstract Syntax Trees (AST) and Tree-Sitter — Tree-sitter parses 10+ languages into ASTs, enabling symbol search, go-to-definition, and type-aware queries; knowing how to write tree-sitter queries (S-expressions) is essential for adding language support or improving code navigation.
• Repository Synchronization (Git2 + Indexing) — bloop syncs local and GitHub repos into Tantivy/Qdrant indexes; understanding Git object storage, delta compression, and incremental indexing explains how bloop handles large repos without re-indexing on every query.
• Tauri IPC Bridge (Rust ↔ TypeScript) — Desktop app communicates with the Rust backend via Tauri's IPC; knowing how commands are serialized, error handling, and async/await patterns across the bridge is critical for feature additions spanning backend and UI.
• On-Device Embeddings (Privacy-Focused ML) — bloop runs embeddings locally (no external ML API), reducing privacy risk and latency; understanding the trade-off between embedding quality, model size, and inference speed informs decisions on supporting custom models or fine-tuning.
• Workspace Monorepo (Cargo + npm) — bloop uses a mixed monorepo: Rust workspace (server + desktop-tauri) and npm workspaces (desktop frontend); understanding interdependencies and build order prevents broken commits when modifying shared code.

• quickwit-oss/tantivy — Direct dependency powering bloop's full-text indexing layer; understanding Tantivy's index format and query DSL is critical for search optimization.
• qdrant/qdrant — Direct dependency for vector embeddings and semantic search; bloop bundles Qdrant binaries in the desktop app and queries it for similarity search.
• tree-sitter/tree-sitter — Core parser library enabling 10+ language symbol search and code navigation (go-to-definition, go-to-reference); bloop uses tree-sitter queries to extract code structure.
• tauri-apps/tauri — Desktop app framework (Rust + TypeScript); bloop's entire GUI is built on Tauri, so understanding the IPC bridge and event handling is essential for UI changes.
• github/codeql — Conceptual peer: CodeQL is also a code search tool with semantic capabilities, though it targets security analysis; useful for understanding alternative approaches to code indexing and querying.

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 integration tests for Tauri desktop app commands in src-tauri

The desktop app (apps/desktop/src-tauri) has Cargo.toml and build.rs but no visible test structure. Given that bloop is a Rust-based search engine with a Tauri desktop wrapper, there are likely backend commands (search, indexing, etc.) that need integration tests. This would improve reliability of the desktop release pipeline and catch regressions early.

• [ ] Examine apps/desktop/src-tauri/src structure (not shown in file list) to identify command handlers
• [ ] Create tests/integration_tests.rs with test cases for key Tauri commands (likely: indexing repos, performing searches, managing workspace state)
• [ ] Add test execution step to .github/workflows/tauri-test.yml to run integration tests before building
• [ ] Document how to run tests locally in apps/desktop/README.md

Add GitHub Actions workflow for dependency security auditing

The repo has .github/workflows/dependencies.yml but its purpose isn't clear from the name alone. Given the workspace contains patched dependencies (esaxx-rs via git) and two Cargo projects, there should be explicit cargo-audit or dependabot workflows to catch vulnerabilities. This is critical for a tool users run locally on their codebases.

• [ ] Verify current .github/workflows/dependencies.yml coverage (check if it runs cargo-audit or cargo-deny)
• [ ] If missing, create .github/workflows/security-audit.yml that runs 'cargo audit' for both workspace members on PRs and schedule daily
• [ ] Add SECURITY.md at repo root documenting vulnerability reporting process
• [ ] Update CONTRIBUTING.md to mention running 'cargo audit' before submitting PRs

Add end-to-end tests for client-server communication in .github/workflows

The repo has separate workflows for client-test.yml and server-test.yml, but no E2E workflow testing the full stack (server + desktop app together). This gap means integration bugs between the Rust server and Tauri frontend could slip through CI. With qdrant binaries already bundled in src-tauri/bin, E2E testing is feasible.

• [ ] Create .github/workflows/e2e-test.yml that starts the bleep server and runs Tauri UI tests against it
• [ ] Add a basic test scenario (e.g., index a sample repo, perform a search, verify results in UI)
• [ ] Use Tauri's built-in testing capabilities or webdriver for browser automation
• [ ] Document E2E testing setup in CONTRIBUTING.md with instructions for local testing

• Add integration tests for the Qdrant embedding pipeline: server/bleep/tests/ likely lacks end-to-end tests covering semantic search queries (indexing a small test repo, querying it, validating result ranking). Write tests that verify embedding quality and query relevance.: Core feature with high-impact correctness; tests would validate the semantic search reliability.
• Expand tree-sitter symbol search to underexplored languages: The README claims '10+ languages' supported, but server/bleep likely has a list of enabled languages. Pick a popular one missing (e.g., Go, Kotlin, Swift) and add tree-sitter parser + symbol extraction logic (go-to-definition, go-to-reference).: Concrete feature gap with clear boundary; tree-sitter has community parsers ready to integrate.
• Document the Code Studio LLM playground with examples: apps/desktop/src probably has Code Studio UI, but the feature lacks user-facing examples in docs or inline help. Add a .md guide in apps/desktop/README.md with 3 example prompts (e.g., 'Explain this function', 'Find security bugs', 'Refactor this') and expected outputs.: Feature is prominent in the README but underdocumented; good onboarding value for new users and contributors.

• High · Incomplete Docker Build Command — Dockerfile (builder stage, final RUN command). The Dockerfile has a truncated RUN command in the builder stage. The line 'cp /build/targ' appears incomplete, which could indicate a build failure or incomplete artifact handling. This makes it unclear if the binary is properly built and copied to the final stage. Fix: Complete the docker build command. Ensure the full binary path is correctly specified: 'cp /build/target/release/bleep /app/bleep' and verify the final stage properly copies the artifact.
• High · Missing Final Docker Stage — Dockerfile (end of file). The Dockerfile appears to be incomplete - it shows a multi-stage build with 'FROM rust' and 'FROM node' stages, but the final runtime stage is not visible. This could expose the full builder environment in production. Fix: Add a final minimal runtime stage (e.g., 'FROM debian:bookworm-slim' or 'distroless') that copies only the compiled binary and necessary runtime dependencies, excluding build tools and source code.
• Medium · Unvetted Patch Dependency — Cargo.toml (patch.crates-io section). The Cargo.toml uses a patch for 'esaxx-rs' pointing to a GitHub repository without a specific commit hash or version constraint. This allows pulling arbitrary commits from the repository, which could be exploited if the repository is compromised. Fix: Pin the dependency to a specific commit hash: esaxx-rs = { git = "https://github.com/bloopai/esaxx-rs", rev = "<specific_commit_hash>" } or use a released version.
• Medium · Excessive Build Permissions — Dockerfile (sccache download section). The Dockerfile builder stage includes 'sccache' download and execution from GitHub without checksum verification. This could allow man-in-the-middle attacks or compromised release downloads. Fix: Add checksum verification for downloaded artifacts: verify SHA256 hash of the sccache tarball before extraction and execution.
• Medium · Cache Mount Without Isolation — Dockerfile (RUN --mount commands). The Dockerfile uses mount caches for sccache and build artifacts without explicit permissions restrictions. In multi-tenant build environments, this could lead to cache poisoning or information disclosure. Fix: Add 'sharing=locked' to cache mounts or verify the build environment is properly isolated. Consider using '--mount=type=cache,sharing=private' for sensitive caches.
• Medium · Deprecated Rust Version — Dockerfile (FROM rust:1.73-slim-bookworm). The Dockerfile specifies 'rust:1.73-slim-bookworm', which is outdated (current stable is 1.75+). This may contain unpatched security vulnerabilities in the Rust toolchain. Fix: Update to the latest stable Rust version or use a specific recent version (e.g., 'rust:1.75-slim-bookworm') and establish a regular update schedule.
• Low · Environment Variable Documentation Missing — .env.example. The .env.example file contains minimal documentation about environment variables ('API_URL' and 'ONBOARDING'). The actual security-sensitive configuration options are not documented, making it unclear what credentials or sensitive data should be managed. Fix: Expand .env.example with all required environment variables, mark sensitive ones with comments (e.g., # SENSITIVE), and document their purpose and expected format.
• Low · Pre-built Binary Distribution — apps/desktop/src-tauri/bin/. The file structure shows pre-built qdrant binaries in version control (apps/desktop/src-tauri/bin/qdrant-*). Binaries in version control can be difficult to audit and may pose supply chain risks. Fix: Move binary artifacts out of version control. Use a package manager or release artifacts system. If binaries must be distributed, include cryptographic signatures and verify them during build/installation.
• Low · Model Files in Version Control — undefined. Machine learning model files (tokenizer.json, model.onnx, etc.) are stored in version Fix: undefined

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.