gobby-code 0.8.1

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 and gives agents (and humans) precise, token-efficient access to symbols, search results, 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 → PostgreSQL hub → search / retrieve / navigate
                │                   │
     ┌──────────┼──────────┐        │
     │          │          │        │
  symbols    chunks     files    ┌──┴──┐
  (BM25)    (BM25)   (hashes)   │     │
                              Neo4j  Qdrant
                             (calls) (vectors)

1. Index — Walk files, parse ASTs with tree-sitter, extract symbols and content chunks
2. Store — PostgreSQL hub tables for symbols/content, Neo4j for call/import graphs, Qdrant for semantic vectors
3. Search — Hybrid ranking: pg_search BM25 + optional semantic + optional graph sources → Reciprocal Rank Fusion
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 Neo4j, Qdrant, or embeddings support.

Runtime indexing/search requires a migrated Gobby PostgreSQL hub. gcode reads ~/.gobby/bootstrap.yaml, requires hub_backend: postgres, and resolves the hub DSN from database_url_ref or database_url. For database_url_ref: keyring:gobby:postgres_database_url, gcode asks the local Gobby daemon broker for the DSN first and falls back to the native OS keyring when the broker is unavailable. The DSN is not written to a plaintext runtime file. The Gobby daemon process does not need to be running for normal index/search commands when keyring fallback is available.

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" --path "src/**/*.rs" # Filter by file path glob
gcode search-symbol "outline"             # Exact-first symbol/command lookup
gcode search-symbol "outline" --kind function --language rust
gcode search-text "query"                 # BM25 on symbol names/signatures
gcode search-content "query"              # BM25 on file content, comments, config, CSS

# Symbol retrieval
gcode outline src/auth.ts                 # Hierarchical symbol tree
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 Neo4j)
gcode callers "handleAuth"                # Who calls this?
gcode usages "handleAuth"                 # Incoming call sites
gcode imports src/auth.ts                 # Import graph for a file
gcode blast-radius "handleAuth" --depth 3 # Transitive impact analysis

# Graph lifecycle (requires Gobby daemon)
gcode graph clear                         # Clear current project's graph projection
gcode graph rebuild                       # Rebuild current project's graph projection

# Project management
gcode status                              # Index stats
gcode projects                            # List all indexed projects
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

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
                          Neo4j                 → call graphs, blast radius, imports
                          Qdrant + embeddings   → semantic vector search
                          Gobby daemon          → auto-indexing, graph/vector sync,
                                                  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 Neo4j, 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. Neo4j URLs, Qdrant API keys, and auth credentials are stored in the shared database and encrypted with Fernet. No env vars to juggle.

PostgreSQL DSNs stay out of plaintext files. Isolated gcode runtimes keep database_url_ref: keyring:gobby:postgres_database_url; gcode resolves it through the daemon broker when available and falls back to the native OS keyring.

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 depend on Neo4j. gcode graph clear and gcode graph rebuild are separate lifecycle operations routed through the Gobby daemon for the current resolved project.

Language Support

gcode parses ASTs using tree-sitter with support for 18 languages:

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.