maproom-search

Maproom Search

When to Use

Tool	Use Case
maproom	Find code by concept
Grep	Exact text/regex
Glob	File paths

First-Time Setup

1. Initialize Database

maproom db migrate

Run once per machine to create the local database.

2. Scan Repository

maproom scan

Takes ~2s for small repos. Embeddings are generated by default (--generate-embeddings true).

For large repos, run in the background:

nohup maproom scan > /tmp/maproom-scan.log 2>&1 &

To regenerate embeddings separately (e.g., after model changes):

maproom generate-embeddings

Always run embedding generation in the background — it makes API calls per chunk and can take minutes for large repos. Use the Bash tool's run_in_background parameter or nohup:

nohup maproom generate-embeddings > /tmp/maproom-embeddings.log 2>&1 &

3. Verify

maproom status

FTS search works immediately after scan. Vector search requires embeddings to complete.

Choosing Search Type

You Have	Use	Example
Exact function/variable name	search	--query "validate_state_file_schema"
Known terminology	search	--query "autogate ready block"
Conceptual question	vector-search	--query "how to pause automated work"
Exploring unfamiliar code	vector-search	--query "authentication flow"
Finding code patterns	search	--query "try except json"

Rule of thumb: Know the words? Use search. Know the concept? Use vector-search.

Vector Search Syntax

maproom vector-search --repo <repo> --query "<query>" --format agent

Requires embeddings (see First-Time Setup step 2).

Evidence from Testing

Query	FTS (search)	Vector (vector-search)
"autogate gate ready"	Found exact function	Related concepts, less precise
"mechanism to pause automated work"	Poor results	Found relevant documentation
"validate schema json"	Found exact functions	Found related validation concepts

For query optimization, see search-best-practices.md.

Output Formats

The search and vector-search commands support two output formats via --format:

JSON (default): Verbose structured output with full metadata. Preview requires explicit --preview flag. Agent (--format agent): Compact one-line-per-result optimized for agent context windows. Preview is implicit (120 chars).

JSON Format Example

$ maproom search --repo <repo> --query "test" --format json --k 2

{"hits":[{"chunk_id":4722,"end_line":159,"file_relpath":"plugins/.../README.md","kind":"code_block","score":3.60,"start_line":150,"symbol_name":"Code: text"}]}

Agent Format Example

$ maproom search --repo <repo> --query "test" --format agent

plugins/.../README.md:150 | code_block Code: text | 3.60 | ```text tests/ ├── integration-test-sdd-loop.sh...

Structure: {file}:{line} | {kind} {symbol} | {score} | {preview}...

Preview Behavior

Agent format implicitly enables preview — adding --preview is redundant. Use --preview-length to adjust (default: 120 chars for agent, 200 for json). For JSON format, --preview must be explicitly passed to include a "preview" field.

Recommendation

For agent use, always pass --format agent. It conserves context window tokens while preserving essential location, kind, score, and preview information.

Filtering and Tuning

All filter values are case-sensitive. Combine multiple values with commas for OR logic. Filters are AND-combined across flags: --kind func --lang py returns only Python functions.

Flag	Value	Matches
--kind	func	Function definitions
--kind	class	Class definitions
--kind	method	Class methods
--kind	heading_2 / heading_3	Markdown headings
--kind	code_block	Fenced code blocks
--kind	markdown_section	Markdown sections (lists, tables)
--kind	json_key	JSON key-value pairs
--lang	py	Python (.py)
--lang	ts	TypeScript (.ts)
--lang	rs	Rust (.rs)
--lang	go	Go (.go)
--lang	md	Markdown (.md)
--lang	json	JSON (.json)

$ maproom search --repo <repo> --query "auth" --kind func --lang py --format agent
$ maproom vector-search --repo <repo> --query "error handling" --threshold 0.7 --format agent

--preview-length <N> — Adjust preview character limit (default: 120 for agent, 200 for json). See Output Formats for preview behavior details. --threshold <N> — Vector-search only. Cosine similarity filter (0.0-1.0); only results >= threshold are returned. Omit for no filtering.

Task	Recommended Flags
Find Python functions	--kind func --lang py --format agent
Find TypeScript classes	--kind class --lang ts --format agent
Browse markdown docs	--kind heading_2 --lang md --format agent
High-precision semantic	--threshold 0.8 --format agent (vector-search)
Find all class hierarchies	--kind class --format agent
Scan JSON config keys	--kind json_key --lang json --format agent

Context Command Reference

Explore a chunk's relationships after finding it via search:

maproom context --chunk-id <id> [flags]

Flag	Purpose	Example
--callers	Include functions that call this chunk	--callers
--callees	Include functions called by this chunk	--callees
--max-depth	Traversal depth (default: 2)	--max-depth 3
--budget	Token limit for context bundle (default: 6000)	--budget 4000

Flags combine freely: context --chunk-id <id> --callers --callees --max-depth 3

Common Workflows

Understand a Feature's Implementation

Find a feature and trace its call relationships (depth-first).

1. Search by concept:

maproom vector-search --repo <repo> --query "authentication login flow" --format agent

2. Expand context around a relevant result:

maproom context --chunk-id <id> --callers --callees

(Vector search because we know the concept but not exact function names.)

Find All Error Handlers

Locate error handling patterns across the codebase.

1. Search for error-related terms:

maproom search --repo <repo> --query "error exception handler" --format agent

2. Get context with a constrained budget:

maproom context --chunk-id <id> --budget 4000

(FTS appropriate since "error" and "exception" are known keywords.)

Trace Call Chains

Follow a function's callers up the call stack to find entry points.

1. Find the function:

maproom search --repo <repo> --query "process_payment" --kind func --format agent

2. Trace callers with increased depth:

maproom context --chunk-id <id> --callers --max-depth 3

(FTS used to locate an exact function name.)

Onboard to Unfamiliar Code

Explore iteratively (breadth-first) when you don't know the terminology yet.

1. Broad concept search:

maproom vector-search --repo <repo> --query "data processing pipeline" --format agent

2. Read context on an interesting result:

maproom context --chunk-id <id>

3. Refine using terms discovered in step 2:

maproom vector-search --repo <repo> --query "transform stage batch worker" --format agent

(Vector search for exploring concepts when terminology is unknown.)

Find Configuration and Settings

Locate where configuration values are defined and how they're consumed.

1. Search for config terms:

maproom search --repo <repo> --query "config settings env" --format agent

2. See what the config drives:

maproom context --chunk-id <id> --callees

(FTS because configuration keywords are known terms.)

Multi-Repo Search

All workflows above use --repo <repo> placeholders. This section explains how to choose which repo to use.

Choosing the Right Repo

Question Type	Search In	Why
"How does X work?"	Code repo	Implementation details live in source code
"Why was X built this way?"	Specs repo	Design rationale in planning documents
"What was the plan for X?"	Specs repo	Tickets, epics, and architecture docs
"Where is X implemented?"	Code repo	Function and class locations
"What are the requirements for X?"	Specs repo	Ticket acceptance criteria and epic goals
"What changed in X?"	Code repo	Recent modifications and git history

Reading the Config File

The workspace config file maproom-repos.yaml (in the workspace root) lists all available repos and their roles. Check it to find repo names and paths:

cat maproom-repos.yaml

A template is available at ./templates/maproom-repos.yaml for reference.

No-Config Fallback

If maproom-repos.yaml is not found, discover indexed repos directly:

maproom status

This lists all repos that have been scanned and are available for search.

Cross-Repo Search Workflow

When a question spans both design and implementation, search across repos sequentially.

Example: Understanding why and how authentication works

1. Check the specs repo for design rationale:

maproom vector-search --repo specs --query "authentication design decisions" --format agent

2. Then check the code repo for implementation:

maproom vector-search --repo code --query "authentication login flow" --format agent

3. Expand context on a relevant code result:

maproom context --chunk-id <id> --callers --callees

(Vector search across repos: specs for "why", code for "how".)

For detailed multi-repo strategies, cross-repo patterns, and chunk kind information, see multi-repo-guide.md.

Troubleshooting

For detailed error recovery steps, see troubleshooting.md.

Token limit exceeded (input token count is ... but the model supports up to 20000): Re-run with smaller batches: maproom generate-embeddings --batch-size 25

Vector search returns no results (search completes but returns empty): Verify embeddings exist: maproom status — if missing, run maproom generate-embeddings

No repositories indexed (status shows no repositories): Run First-Time Setup above to scan and index your repository.

Stale results after code changes (results reference old or deleted code): Re-scan the repository: maproom scan

Irrelevant results (results don't match intent): Check Choosing Search Type above — FTS for exact terms, vector for concepts. Use 2-3 core terms.

Query Tips

Extract 2-3 terms from questions. See search-best-practices.md.