Repo (Local Code Search)

Repo provides fast, offline code search for local repositories using FTS5 full-text indexing and regex via ripgrep. Search mode is auto-detected from the query syntax. These commands are primarily used by agents during coding sessions to navigate and understand the codebase.

Index a Repository

$ recalletta repo index

Indexes the current repository (detected by walking up to find .git/ or .recalletta-index). Works from any subdirectory.

Option	Purpose
`[PATH]`	Index a specific directory instead of the current repo
`-f, --force`	Force full re-index (ignore file hashes)
`--dry-run`	Show what would be indexed without making changes

Indexing is incremental by default — only files that changed (by size + mtime) are re-indexed.

$ recalletta repo index
$ recalletta repo index --force
$ recalletta repo index /path/to/repo

What Gets Indexed

Respects .gitignore patterns
Skips binary files (detected by content inspection)
Skips files larger than 1MB
Skips hidden files/directories (starting with .)
Language detection is automatic based on file extension

Non-Git Projects

For projects without a .git/ directory, create a marker file at the root:

$ touch /path/to/project/.recalletta-index

Storage

Index databases are stored at ~/.recalletta/repos/<repo-hash>.db. Typical index size is 10-30% of source code size.

Search

$ recalletta repo search <QUERY> [OPTIONS]

Option	Default	Purpose
`-n, --limit <N>`	10	Maximum number of results
`-p, --path <PATH>`		Filter by path prefix (e.g., `src/`)
`-l, --lang <LANG>`		Filter by language (e.g., `rust`, `python`)

Search Modes (Auto-Detected)

The query syntax determines which search mode is used. You do not choose explicitly.

FTS5 — natural language queries, ranked by BM25 relevance. Requires an index.

$ recalletta repo search "database connection"
$ recalletta repo search "error handling"
$ recalletta repo search "func*"                 # Prefix match
$ recalletta repo search '"exact phrase"'         # Phrase match
$ recalletta repo search "error OR warning"       # Boolean OR
$ recalletta repo search "error AND NOT fatal"    # Boolean AND + NOT
$ recalletta repo search "NEAR(open close, 5)"   # Proximity (within 5 tokens)

FTS5 also supports field-scoped queries:

$ recalletta repo search "path:test"              # Search only file paths
$ recalletta repo search "content:TODO"           # Search only file content

Glob/Extension — find files by name pattern. Uses the index.

$ recalletta repo search "*.cshtml"               # All .cshtml files
$ recalletta repo search "**/*.rs"                # All Rust files recursively
$ recalletta repo search "src/**/*.ts"            # TypeScript files in src/
$ recalletta repo search "ext:cshtml"             # Files with .cshtml extension

Regex — pattern matching via ripgrep. No index required.

$ recalletta repo search 'fn\s+\w+'               # Function definitions
$ recalletta repo search 'TODO|FIXME|HACK'        # Markers
$ recalletta repo search 'impl.*for'              # impl blocks
$ recalletta repo search '^\s*use\s'              # Lines starting with "use"
$ recalletta repo search '\d{4}-\d{2}-\d{2}'      # Date patterns

Regex is auto-detected when the query contains: \s, \d, \w, \b, character sets like [a-z], dot + quantifier like .*, both anchors ^...$, regex groups (?:...), or alternation a|b.

Combining Filters

$ recalletta repo search 'TODO|FIXME' -l rust          # Regex, Rust files only
$ recalletta repo search "database" -p src/ -n 20      # FTS5, src/ only, 20 results
$ recalletta repo search "**/*.ts" -p src/components/  # Glob, scoped to path

Output

File searches (glob/extension): file paths only
Content searches (FTS5/regex): paths + code snippets with line numbers and 2 lines of context before/after each match

Check Index Status

$ recalletta repo status

Shows whether an index exists for the current repository and its statistics. If no index exists:

$ recalletta repo status
No index found for repository at /path/to/repo.
Run 'recalletta repo index' to create one.

Remove an Index

$ recalletta repo drop

Deletes the index database for the current repository.

Option	Purpose
`-f, --force`	Skip confirmation prompt