GuideSearch / Ask / Repos

User guide

Docs

Learn Keymap in the order the workspace is meant to be used: prepare repositories, search code, inspect source, then ask questions backed by citations.

ReposPrepare indexed code before any search or answer.SearchFind exact text, symbols, paths, and languages.

BrowseInspect files, highlighted ranges, history, and references.

AskAsk focused questions and open cited source.

Daily path

Start with the working loop

Keymap works best as a loop: add code, search for the exact place, inspect source, then ask questions with real file context.

1Open Repos and add a GitHub repository with owner/repo or a GitHub URL.
2Wait until the repository state becomes ready; queued or indexing repositories are not searchable yet.
3Use Search for exact code, symbols, paths, languages, and repository-scoped discovery.
4Open matching files in Browse or ask source-aware questions from Ask when you need explanation.

Search discovers code. Browse reads source. Ask explains code with citations.
Keep at least one ready repository selected before using Search or Ask.

Repos

Add and manage repositories

Repositories are the source set for both Search and Ask. A repo must be indexed before Keymap can search or cite it.

1Open Settings or the bottom dock Repos item, then enter owner/repo or a full GitHub URL.
2Use the optional TOKEN_ENV field only when the repository needs a token already available in the server environment.
3Click Add. Keymap queues the repository for indexing and refreshes the list.
4Watch the status: queued means waiting, indexing means work is running, ready means usable, and failed means the indexer could not finish.
5Use refresh to recheck state. Use the delete button only when you want to purge that repository from the workspace.

Queued work can wait if the indexer is offline.
Deleting a repository removes it from future Search and Ask scopes.

Search with query language

Search is URL-first and query-first. Type a query, select ready repos, toggle case or regex when needed, then open results or preview source.

1Select one or more ready repositories below the Search box.
2Type the smallest useful query and press Enter or Search.
3Use result filters to narrow by repository or language without leaving the results workspace.
4Click Preview to inspect a file beside results, or click a code match to open Browse at highlighted lines.
5Use Load more when the first result set is not enough.

Text

renderToStream

Find a literal word or phrase in file contents.

Path

file:src/ router

Search content only in matching file paths.

Symbol

sym:useRouter

Find symbol-indexed definitions or declarations.

Language

lang:typescript useEffect

Limit content search to one language.

Repo

repo:keymap Query

Scope the query to a repository name.

Exclude

Search -file:test

Remove files or terms with a leading minus.

Combine

repo:keymap lang:tsx (Search or Ask)

Mix scope filters and boolean groups.

Search state belongs in the URL, so result pages can be refreshed or shared.
Regex and case-sensitive modes are explicit toggles in the Search footer controls.

Browse

Browse source from matches and citations

Browse is the shared source inspection surface for Search matches and Ask citations. It is where highlighted code becomes navigable context.

1Open Browse by clicking a Search match, Search preview path, or Ask citation.
2Use the file tree to move through nearby files in the same repository.
3Use Code or Blame to switch between source and line ownership when available.
4Use History to inspect recent commits for the current file or repository.
5Use Explore to inspect definitions or references for selected symbols.
6Use file search to jump to another path inside the same repository.

Highlighted Browse URLs point to exact line or line-column ranges.
Browse keeps source, tree, history, and explore panels in one code-first workspace.

Ask

Ask source-aware questions

Ask is for explanation, summarization, and follow-up questions. It should show what it is doing and cite files it actually used.

1Select one or more ready repositories before submitting a question.
2Ask focused questions such as where a function is defined, how a flow starts, or why an error might happen.
3After the first submit, Keymap creates a thread so follow-up questions stay in context.
4Watch the assistant activity rows for search, file reads, and source-gathering progress.
5Click citations to open the referenced source beside the answer on wide screens or in Browse on narrow screens.
6Use History from Ask landing to reopen earlier threads.

Citations are only meaningful when the assistant saw matching source.
If an answer has no citations, treat it as less grounded and ask for specific files or symbols.

Fixes

Troubleshoot common states

Most blocked states come from repo readiness, indexer health, empty queries, or Ask configuration. Check those before changing your workflow.

1No ready repos: open Repos, add a repository, and wait for ready before searching or asking.
2Indexer offline: queued repositories will wait; refresh after the indexer is back online.
3No Search results: remove narrow filters, try a simpler term, or increase matches with Load more.
4Search fallback or error: read the message shown in the results surface and retry after repository state is ready.
5Ask has no citations: ask a narrower question, include a file path or symbol, or verify the selected repo contains the target code.
6Ask unavailable: confirm the Ask provider is configured for the workspace.

Search failures should stay visible rather than being treated as normal empty results.
Ask source panels can only show references returned by the Ask run.

Keyboard

Use the main shortcuts

Shortcuts are scoped to the active surface. They help you stay in the code workflow without adding extra UI.

Focus current input

Focus Search, Ask, or the active filter where supported.

Enter

Submit

Run Search, send Ask, or select the highlighted suggestion.

Escape

Close panels

Close suggestions, syntax help, dialogs, or assist surfaces.

mod+b

Toggle side panel

Toggle Search filters or the Browse file tree.

mod+p

Open file search

Open Browse file search in the current repository.

shift+mod+h

Browse History

Open or collapse the Browse History panel.

shift+mod+e

Browse Explore

Open or collapse the Browse Explore panel.

`mod` means Command on macOS and Control on Windows or Linux.
Typing inside an input keeps the shortcut from stealing focus.