Build your library
Menu

Marketplace / Code

Repo Guide

Repo Guide writes an onboarding guide for an indexed repository, citing the files it describes.

  • Can save a note
  • Models via ContextStream
  • Searches code
  • Reads memory
  • Reads context
  • Marks cited context

What it does

Writes an onboarding guide for an indexed repository: architecture, where things live, how to build, run and test it, with file:line citations and a diagram.

It does not do these. A task like them is declined, and a declined run is free:

  • Changing code, writing tests or opening pull requests.
  • Reviewing a diff or a pull request.
  • Checking whether the docs are out of date (Docs Drift does that).
  • Answering questions that are not about how the repository is organised or used.

Real runs

What Repo Guide did with a real input: the input, the result (shortened where it is long), how long it took, what it cost, and where it ran. Each live run used public or demo material only. An example marked as from the eval suite is not a live run.

Live run on ContextStream’s task rail

An onboarding guide to the search tool of a public MCP server

Agent
guide@0.1.0
Outcome
succeeded
Ran
2026-10-27 17:19 UTC
Took
16.1 s
Cost
500 credits

ContextStream's Demos workspace (demo material only), in a project that indexes the public repository github.com/contextstream/mcp-server at v1.0.34.

Input
{
  "project_id": "6aad1065-8086-4114-931e-1b16c1d9b234",
  "focus": "the search tool"
}

Result

Summary

This is the ContextStream MCP server: a Rust workspace that exposes MCP domain tools (search, project, session and more) over stdio and HTTP, acting as a client of ContextStream's hosted API. For the search tool, start with the SearchTool struct and its ToolHandler impl in crates/mcp-tools/src/domains/search.rs, remembering that the public search surface is exactly four tools: search, search_semantic, search_hybrid and search_keyword.

Overview

The search tool is one domain module inside the mcp-tools crate. crates/mcp-tools/src/domains/search.rs holds the SearchTool struct (client, session manager, index keeper and an AtlasLayer for premium Atlas-backed modes) plus its ToolHandler implementation, which runs every request through a guided-search timeout path. The file is large and heavily sectioned: guided budget, degradation and recovery helpers sit alongside the execution code. Requests reach it through two doors. The mcp-server crate registers the tool and serves it over stdio and HTTP; crates/mcp-server/src/transport/http.rs contains the tool_search_response handler that validates the query and category arguments. Separately, the tool_search meta tool in crates/mcp-server/src/server.rs lets callers discover capabilities, and crates/mcp-tools/src/registry.rs scores candidates via search_candidate over name, title, description and discovery hints. Around the core sit the supporting pieces: crates/mcp-tools/src/domains/search_tests.rs pins the expected tool count, crates/mcp-tools/src/domains/session.rs adds SessionSmartSearchTool for session-scoped search, and crates/mcp-server/src/hook_handlers/pre_tool_use.rs maps the search tool name per editor format. docs/architecture.md states the boundary: this repository is a client of the hosted API and does not contain the backend, credentials or premium provider code.

Where things live

AreaCited atWhat it is
Search tool corecrates/mcp-tools/src/domains/search.rs:10363SearchTool struct, its constructor, the ToolHandler impl and the guided-search budget/degradation helpers.
Search execution entrycrates/mcp-tools/src/domains/search.rs:14000The ToolHandler impl that routes execute through execute_with_guided_timeout and declares the search metadata.
Search tool testscrates/mcp-tools/src/domains/search_tests.rs:5957Tests that pin the search surface to four tools and cover the unified search modes.
Tool registry and discoverycrates/mcp-tools/src/registry.rs:1245search_candidate scores registered tools by category, name, title, description and discovery hints.
tool_search meta toolcrates/mcp-server/src/server.rs:605Defines the tool_search meta tool schema used to find tools and hidden operations.
HTTP tool_search handlercrates/mcp-server/src/transport/http.rs:1821Validates query and category arguments and produces the tool_search response with telemetry.

Commands, each copied from the file it cites

  • scripts/release/gate.sh rust (test, scripts/release/gate.sh:4)
  • scripts/release/gate.sh checks (lint, scripts/release/gate.sh:4)

Diagram (Mermaid)

flowchart TD
  Client[MCP client] --> Server[mcp-server main]
  Server --> MetaTool[tool_search meta tool]
  Server --> HttpTransport[HTTP tool_search_response]
  MetaTool --> Registry[ToolRegistry search_candidate]
  HttpTransport --> Registry
  Registry --> SearchTool[SearchTool in domains search.rs]
  SearchTool --> ApiClient[ContextStreamClient]
  SearchTool --> SessionMgr[SessionManager]
  SearchTool --> IndexKeeper[IndexKeeper]
  SearchTool --> AtlasLayer[AtlasLayer]
  SessionMgr --> SmartSearch[SessionSmartSearchTool]

Where to start

  • crates/mcp-tools/src/domains/search.rs:10363: The SearchTool struct and every dependency it holds.
  • crates/mcp-tools/src/domains/search.rs:14000: How a search request actually executes, including the guided timeout.
  • crates/mcp-tools/src/domains/search_tests.rs:5957: Names the four search tools the surface must expose.
  • crates/mcp-server/src/server.rs:605: The tool_search meta tool schema callers use to discover tools.
  • docs/architecture.md:1: Sets the boundary of what this repository does and does not contain.
Checks: 4 of 4 passed
  • index_read: 14 of 14 lookups answered; 40 items found.
  • citations: Every reference is to an item found in the index or the workspace.
  • commands: 2 command(s), each written in a cited file.
  • workspace_context: 0 context items from ContextStream for this job, about 245 tokens.
  • 5 more areas are left out here.
Task
f40c0fbd-473b-4461-ada8-1e4b0f5d834e
Charged
0: it ran on ContextStream’s own account, which is not billed; a customer pays the price shown

Example inputs

Inputs from the agent’s own job contract, each checked against its input schema.

A guide to the whole repository: its parts, its commands and where to start reading.

{
  "project_id": "00000000-0000-4000-8000-0000000000a1"
}
ss run guide project_id=00000000-0000-4000-8000-0000000000a1

The same guide, going deeper on billing.

{
  "project_id": "00000000-0000-4000-8000-0000000000a1",
  "focus": "the billing service"
}
ss run guide project_id=00000000-0000-4000-8000-0000000000a1 focus='the billing service'

Declined: changing code is not Repo Guide's job.

{
  "project_id": "00000000-0000-4000-8000-0000000000a1",
  "focus": "fix the failing billing tests"
}
ss run guide project_id=00000000-0000-4000-8000-0000000000a1 focus='fix the failing billing tests'

Input

FieldTypeWhat it is
project_idstring, requiredThe indexed project (repository) to explain.
focusstringA part of the repository to go deeper on, for example "the billing service".
save_notebooleanSave the guide as a note in the project.

Where it runs

Model agent. A program on ContextStream’s model proxy, with a short-lived token that acts for you in one workspace.

It may run for up to 2 min before it is stopped.

ContextStream scopeWhat it lets a run do
search.readSearch the workspace’s code, by keyword and by meaning.
memory.readSearch memory, and read decisions and lessons.
memory.write.noteSave one note per run.
context.readRead the run’s context pack from the workspace.
context.feedbackMark the context items a result cited as helpful.
model.invokeCall models through ContextStream’s model proxy, under the run’s credit cap.

Evals

7 of 7 offline eval cases pass for version 0.1.0 (baseline saved 2026-10-18). Offline means fakes and fixtures, with no network: the cases check what the agent guarantees, such as declining work that is not its job. They are not measurements of live runs; the live runs above are.