gobby-code 1.0.0

The Problem

AI coding agents read entire files to find a single function. A 2000-line module gets dumped into the context window when all the agent needed was a 15-line method. Multiply that across a session and you're burning thousands of tokens on code that isn't relevant.

The Fix

gcode indexes your codebase using tree-sitter AST parsing plus safe repo text chunking, where content chunks stay within file boundaries and skip binary, large, and excluded files, then gives agents (and humans) precise, token-efficient access to symbols, docs, configs, content chunks, and dependency graphs.

$ gcode search "handleAuth"
[
  {"name": "handleAuth", "kind": "function", "file_path": "src/auth/middleware.ts",
   "line_start": 42, "signature": "async function handleAuth(req, res, next)", ...}
]

One search call instead of reading 50 files. 90%+ token savings.

How It Works

codebase → tree-sitter AST + safe text chunks → PostgreSQL hub → search / retrieve / navigate
                │                              │
     ┌──────────┼──────────┐                   │
     │          │          │                 ┌──┴──┐
  symbols    chunks     files               │     │
  (BM25)    (BM25)   (hashes)             FalkorDB Qdrant
                                          (calls) (vectors)

1. Index — Walk files, parse ASTs with tree-sitter, and chunk safe repo text
2. Store — PostgreSQL hub tables for symbols/content, FalkorDB for call/import graphs, Qdrant for semantic vectors
3. Search — Hybrid ranking: pg_search BM25 + required semantic/graph sources that can degrade → exact-tiered RRF results with raw rrf_score metadata
4. Retrieve — Byte-offset reads for exact symbol source, no file-level bloat

Installation

Pre-built binaries

Download from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/GobbyAI/gobby-cli/releases/latest/download/gcode-aarch64-apple-darwin.tar.gz | tar xz
sudo mv gcode /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/GobbyAI/gobby-cli/releases/latest/download/gcode-x86_64-apple-darwin.tar.gz | tar xz
sudo mv gcode /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/GobbyAI/gobby-cli/releases/latest/download/gcode-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv gcode /usr/local/bin/

# Linux (ARM64)
curl -L https://github.com/GobbyAI/gobby-cli/releases/latest/download/gcode-aarch64-unknown-linux-gnu.tar.gz | tar xz
sudo mv gcode /usr/local/bin/

# Windows (x86_64) — PowerShell
Invoke-WebRequest -Uri https://github.com/GobbyAI/gobby-cli/releases/latest/download/gcode-x86_64-pc-windows-msvc.zip -OutFile gcode.zip
Expand-Archive gcode.zip -DestinationPath .

Build from source

cargo install gobby-code

Graph and semantic features are configured at runtime. You do not need Cargo feature flags to enable FalkorDB, Qdrant, or embeddings support. Gobby-managed projects read FalkorDB settings from databases.falkordb.*; daemon-independent setups can use GOBBY_FALKORDB_HOST, GOBBY_FALKORDB_PORT, and GOBBY_FALKORDB_PASSWORD.

Runtime indexing/search requires a migrated Gobby PostgreSQL hub. gcode asks the local daemon broker for the hub DSN first. If the daemon is unavailable, resolution checks GCODE_DATABASE_URL, GOBBY_POSTGRES_DSN, ~/.gobby/gcore.yaml databases.postgres.dsn, then bootstrap database_url. Bootstrap config requires hub_backend: postgres.

Standalone setup is tested against PostgreSQL 18 with pg_search BM25 indexes. The schema preflight reads PostgreSQL catalogs such as pg_class and pg_namespace to validate only gcode-owned code-index tables and indexes.

With Gobby

gcode is installed automatically as part of the Gobby platform. If you're using Gobby, you already have it.

Usage

# Initialize and index a project (one step)
gcode init

# Search
gcode search "query"                      # Hybrid: BM25 + semantic + graph boost
gcode search "query" --kind function      # Filter by symbol kind
gcode search "query" --language rust      # Filter by source language
gcode search "query" src/**/*.rs          # Filter by path or glob
gcode search-symbol "outline"             # Exact-first symbol/command lookup
gcode search-symbol "outline" --with-graph # Exact-first lookup plus graph neighbors
gcode search-symbol "outline" --kind function --language rust
gcode search-symbol "Context" crates/gcode/src
gcode search-text "query"                 # BM25 on symbol names/signatures
gcode search-text "query" crates/gcode/src
gcode grep "pattern"                      # Exact indexed content grep
gcode grep -w note_path [PATH...]         # ASCII identifier whole-word grep
gcode grep '\bnote_path\b' src -m 50      # Rust regex word boundaries are supported
gcode search-content "query"              # BM25 on source, comments, skill files, docs/Markdown, configs, CSS, SQL, and extensionless text
gcode search-content "query" docs/**/*.md crates/gcode/src

# Symbol retrieval
gcode outline src/auth.ts                 # Hierarchical symbol tree
gcode symbol-at src/auth.ts:42            # Symbol containing or nearest to a line
gcode symbol <id>                         # Source code by symbol ID
gcode symbols <id1> <id2> ...             # Batch retrieve
gcode tree                                # File tree with symbol counts

# Dependency graph reads (requires FalkorDB)
gcode graph overview --limit 100          # Project overview graph
gcode callers <symbol-id>                 # Who calls this symbol?
gcode usages <symbol-id>                  # Incoming call sites for this symbol
gcode imports src/auth.ts                 # Import graph for a file
gcode blast-radius "handleAuth" --depth 3 # Transitive impact analysis

# Graph lifecycle (requires FalkorDB)
gcode graph clear                         # Clear current project's graph projection
gcode graph clear --project-id <id>       # Clear graph projection by explicit project id
gcode graph sync-file --file src/lib.rs   # Sync one indexed file into the graph projection
gcode graph rebuild                       # Rebuild current project's graph projection

# Project management
gcode status                              # Index stats
gcode projects                            # List all indexed projects
gcode setup --standalone                  # Provision daemon-independent services
gcode index                               # Re-index (incremental)
gcode invalidate                          # Clear index, force full re-index

# Cross-project queries
gcode search --project myapp "query"      # By project name
gcode search --project /path/to/app "q"   # By path

# Global flags
--format text|json                        # Output format (default: json)
--quiet                                   # Suppress warnings and progress
--no-freshness                            # Skip read-time index/source freshness checks

gcode grep defaults to grouped text output: each matched file is printed once, followed by line-numbered matches and context. Other high-volume text outputs, including tree, callers, usages, and blast-radius, also group repeated paths for compact agent-readable output. gcode grep --format json returns structured matches with spans and context. Regex patterns use Rust regex syntax, including \b word boundaries; use -w/--word for ASCII identifier whole-word search. For reference mapping, resolve a symbol ID first and prefer gcode usages <symbol-id> or gcode callers <symbol-id> over text grep when the graph projection is synced.

AI CLI Skill Installation

For non-Gobby-managed projects, gcode init installs the bundled gcode skill for every supported project-local AI CLI target:

Gobby-managed projects skip these project-local writes because Gobby owns CLI wiring.

Daemon-Independent Runtime

gcode is standalone in the important CLI sense: gcode index, gcode search, gcode status, and symbol retrieval do not require the Gobby daemon process. They do require the migrated PostgreSQL hub schema because that hub is the source of truth for code-index rows.

With Gobby

codebase → tree-sitter → PostgreSQL hub + pg_search BM25
                          FalkorDB              → call graphs, blast radius, imports
                          Qdrant + embeddings   → semantic vector search
                          Gobby daemon          → auto-indexing, graph/vector orchestration,
                                                  config, secrets, sessions, agents

Gobby adds graph queries, graph lifecycle orchestration, semantic search, and infrastructure that makes gcode better at its core job — not just more features bolted on.

Search quality improves. With FalkorDB, gcode search blends BM25 text matching with call-graph relevance. With Qdrant plus a configured embeddings API, conceptual queries like "database connection pooling" can find semantically similar code even when the exact words don't match.

Config and secrets are managed. FalkorDB connection settings, Qdrant API keys, and auth credentials are stored in the shared database and encrypted with Fernet. No env vars to juggle.

PostgreSQL DSNs can stay out of plaintext files. Isolated gcode runtimes ask the daemon broker first. Operators who need daemonless access can opt into GCODE_DATABASE_URL, GOBBY_POSTGRES_DSN, ~/.gobby/gcore.yaml, or inline bootstrap database_url.

Indexing happens automatically. The Gobby daemon watches for file changes and re-indexes in the background. Without the daemon, run gcode index manually.

Get started with Gobby at github.com/GobbyAI/gobby.

Graceful Degradation

Read-side graph commands and graph lifecycle depend on FalkorDB. Vector lifecycle depends on Qdrant plus embeddings for sync/rebuild. All code-index projection lifecycle paths are Rust-owned and scoped to code projection state: graph clears target code-index FalkorDB labels only, and vector clears target only code_symbols_{project_id} rather than memory vector collections. gcode graph sync-file --allow-missing-indexed-file is reserved for daemon and background-worker stale work; humans should let the default strict missing-file error surface stale or incorrect sync requests.

Language Support

gcode parses ASTs using tree-sitter with support for 18 languages. Files that pass the same safety checks but do not match a tree-sitter language are indexed as content-only text for search-content.

Content-only indexing covers repo text files such as source comments, skill files, docs/Markdown, configs, scripts, CSS, SQL, Dockerfile/Makefile, and other extensionless text files. Markdown is content-only and does not go through tree-sitter AST symbol detection. Binary, excluded, empty, and >10MB files are skipped. Secret-like skips are filename/path checks from src/index/security.rs: extensions such as .env, .pem, .key, .p12, .pfx, .jks, .keystore, and .secret; prefixes such as credentials, .env, id_rsa, id_ed25519, and token; and substrings such as api_key, apikey, _secret., and _token.. No content secret scanner or external detector is currently used.

Build

gcode uses runtime-configured services rather than Cargo feature flags.

cargo build --release
cargo test --no-default-features
cargo clippy --no-default-features -- -D warnings

Platform Support

Contributing

See CONTRIBUTING.md for details.

License

Apache 2.0 — Use it, fork it, build on it.