Terraphim
v1.16.0
Terraphim
Home Capabilities How-tos Docs Rust Releases Install Donate

Introducing Multi-Haystack Roles: Local + Global Code Search

16 February 2026 4 min read 669 words
Technical Terraphim release features grepapp haystack code-search

Today we are announcing a significant enhancement to Terraphim's engineer roles: multi-haystack support. FrontEnd Engineers and Python Engineers now have access to both local code search (via Ripgrep) and global GitHub search (via GrepApp) in a single query.

Traditionally, developers face a frustrating choice when searching for code:

  1. Search locally - Fast, but limited to your own codebase
  2. Search GitHub - Broad, but requires leaving your workflow

When you are stuck on "how do I use this library?" or "what's the idiomatic way to solve this?", you need both: your local context for project-specific code, and global examples from the broader community.

The Solution: Dual Haystacks

Starting with Terraphim v1.8.1, select engineer roles now come with dual haystacks:

FrontEnd Engineer

  • Haystack 1: Local Ripgrep search (~/projects or custom path)
  • Haystack 2: GrepApp global search (filtered to JavaScript)

Python Engineer

  • Haystack 1: Local Ripgrep search (~/projects or custom path)
  • Haystack 2: GrepApp global search (filtered to Python)

Rust Engineer v2 (already available)

  • Haystack 1: QueryRs (docs.rs search)
  • Haystack 2: Local Ripgrep search

How It Works

When you search as a FrontEnd or Python Engineer, Terraphim queries both sources simultaneously:

Your Query: "how to use useEffect"
    |
+-------------------+     +--------------------+
|  Local Ripgrep    |     |  GrepApp           |
|  (your code)      |     |  (GitHub repos)    |
+---------+---------+     +---------+----------+
          |                         |
          +-----------+-------------+
                      |
           Combined Results
           (ranked by relevance)

The results are merged and ranked according to your role's relevance function:

  • FrontEnd Engineer: BM25Plus ranking
  • Python Engineer: BM25F field-weighted ranking

This means you get the best of both worlds: your project's specific implementations AND real-world examples from popular repositories.

Real-World Use Cases

Learning a New Library

You are trying to use react-query for the first time. A single search shows:

  • How you have used it elsewhere in your codebase (local)
  • How Facebook uses it in their production apps (global)

Debugging Common Patterns

You are debugging a Python asyncio issue. Your search returns:

  • Your current implementation (local)
  • How aiohttp, FastAPI, and Django handle similar patterns (global)

Discovering Idioms

You want to know the "Pythonic" way to do something. Instead of reading docs, you can see:

  • How the standard library implements it
  • How popular open-source projects handle similar cases

Technical Implementation

Under the hood, this uses our existing GrepApp integration:

Haystack {
    location: "https://grep.app".to_string(),
    service: ServiceType::GrepApp,
    read_only: true,
    fetch_content: false,
    extra_parameters: {
        let mut params = HashMap::new();
        params.insert("language".to_string(), "python".to_string());
        params
    },
}

The extra_parameters field allows language-specific filtering:

  • FrontEnd Engineer: language=javascript
  • Python Engineer: language=python

GrepApp returns structured results from millions of GitHub repositories, complete with:

  • Repository name and file path
  • Code snippet with context
  • Direct link to view on GitHub
  • Branch information

Graceful Degradation

We know network availability is not guaranteed. If GrepApp is unreachable:

  • Local search continues working normally
  • No errors or interruptions
  • You still get your project-specific results

This follows our philosophy: local-first, enhance with global.

What's Next

This is just the beginning. We are planning:

  1. More roles with dual haystacks:

    • Go Engineer (GrepApp + local)
    • TypeScript-specific role
    • Language-agnostic search role

  2. Configurable filters:

    • Filter by specific repositories
    • Filter by file paths
    • Filter by popularity/stars

  3. Enhanced ranking:

    • Boost results from starred repositories
    • Learn from your click patterns
    • Personalised ranking per engineer

Try It Now

If you are already using Terraphim v1.8.1+, you can try the new roles immediately:

# Switch to FrontEnd Engineer (with dual haystack)
terraphim-agent onboard --role frontend-engineer

# Switch to Python Engineer (with dual haystack)
terraphim-agent onboard --role python-engineer

# Search as usual: both local and global results appear
terraphim-agent search "async def"

The Bigger Picture

Multi-haystack roles represent a fundamental shift in how we think about code search:

Old model: One haystack per role, choose your scope New model: Multiple haystacks per role, get comprehensive results

This aligns with how developers actually work: they do not want to choose between "my code" and "the world's code" — they want both, intelligently combined.

As we expand this pattern to more roles and add more haystack types (MCP servers, Atomic Data, AI assistants), Terraphim becomes not just a search tool, but a knowledge synthesis engine for developers.

Feedback Welcome

Have ideas for other haystack combinations? Want to see this pattern applied to other roles? Let us know:

Related Reading:

Terraphim: Search your world.