Using CodeSearch

CodeSearch keeps a local index of the repositories you work in. A coding agent asks it where something is implemented and gets back whole declarations, ranked — so it opens two or three files instead of reading its way through the tree.

The app does the indexing. A small codesearch command answers queries by asking the running app. Nothing is uploaded: the index, and your source, stay on your Mac.

Setup

The app walks you through this on first launch. It is four steps, in order — the command cannot reach an app with no profile, and the agent skill is no use before the command exists.

1. Choose a code directory

   Point CodeSearch at a folder that holds your projects. It scans for git repositories inside and lists what it found. One folder of many checkouts is the normal case; you can add more later.

   Screenshot: the directory step, repositories listed
   /assets/docs/setup-directory.png

2. Install the command-line tool

   The codesearch executable ships inside the app bundle. The Integrations pane installs it, offering /usr/local/bin by default and recognising /opt/homebrew/bin if you keep tools there.

   The same pane carries the background service switch. Leave it on: the tool talks to the app, and this is what lets it start the app on demand.

   Screenshot: Integrations pane, CLI install + background service switch
   /assets/docs/setup-cli.png

3. Install the agent skill

   A skill file tells a coding agent when to reach for codesearch and how to read what comes back. CodeSearch writes it to ~/.claude/skills/codesearch/SKILL.md, or wherever else you keep skills.

   You do not have to use one. The skill is what makes the agent reach for the index on its own, rather than you telling it to every time.

   Screenshot: the skill step, directory picker
   /assets/docs/setup-skill.png

4. Build the first index

   Run it once from the app. After that it reindexes in the background on a schedule — every 30 minutes by default, and adjustable per profile.

   Screenshot: an indexing run, progress and chunk count
   /assets/docs/setup-index.png

Profiles

A profile is one index over one set of code. Most people need one. Separate profiles are worth it when you want different scopes — work and side projects, say — because a query names the profile it searches, so splitting them is how you keep results narrow.

Each profile holds:

• Directories to scan, and the repositories found inside them.
• Include and exclude globs, for pulling in or keeping out particular paths.
• Honour .gitignore, on by default, so build output and vendored dependencies stay out.
• Repositories only, which ignores anything in the folder that is not a git checkout.
• Reindex interval, and a switch to pause the profile entirely.

The profile view also reports what the index actually contains — chunk count, size on disk, the language breakdown, and the history of recent runs.

Screenshot: profile detail — directories, stats, run history
/assets/docs/profile-overview.png

From the command line

Two commands. The tool holds no index of its own — each call is one message to the running app, and the answer printed.

List what is indexed, and how much is in each profile:

$ codesearch profiles list
My Code  —  48213 chunks, 3 Oct 2026 at 09:14

Search one profile. The query is prose, not a pattern:

$ codesearch query "where do we validate coupons" --profile "My Code"

--limit takes a count and defaults to 20. --json prints structured output, which is what an agent should use:

$ codesearch query "retry policy" --profile "My Code" --json | jq '.hits[0]'

Each hit is a whole declaration with a score. A high score means the declaration reads like the query — not that it contains those words. Treat the hits as a list of files worth opening rather than as complete answers.

From a coding agent

With the skill installed, an agent reaches for CodeSearch on its own when it is looking for where something lives in a codebase it does not know — and skips it when a path or exact symbol is already known, because grep is cheaper and exact for that.

Worth telling your agent, if it has not worked it out:

• Search before reading. The hits say which files to open.
• Query in prose. "how are webhook retries backed off" beats retryBackoff.
• Nothing outside an indexed profile is visible. codesearch profiles list says what is covered.

What gets indexed

Files are split into whole declarations — a function, a class, a method — rather than fixed-size windows, so a hit is something you can read on its own. Sixteen languages are understood:

• Swift .swift
• Go .go
• Python .py
• Ruby .rb
• JavaScript .js .jsx
• Java .java
• Rust .rs
• C .c .h
• C++ .cpp .hpp
• C# .cs
• PHP .php
• Scala .scala .sbt
• Elixir .ex .exs
• SQL .sql
• CSS .css
• Dockerfile Dockerfile

TypeScript is not among them yet. The JavaScript chunker claims .js, .jsx, .mjs and .cjs only, so .ts and .tsx files are skipped even when a profile's globs reach them.

If the tool cannot reach the app

codesearch talks to the app over a local connection, so the app has to be installed and allowed to run in the background. If a command reports it cannot connect, open Integrations and check the background service switch. The error says as much.

A profile that has never been indexed answers nothing, and tells you so rather than returning an empty list.