Getting Started

Developers often fix the same problem twice: the command or log pattern disappears into shell history, notes, and logs searched by hand weeks later. devgrep indexes those artifacts into SQLite and lets you fuzzy-search them from the terminal.

Everything runs locally. There is no account, cloud service, telemetry, or AI layer.

After installation, create your first index:

devgrep index

This indexes shell history (bash and zsh) and walks configured paths for .log files and markdown notes. You do not need a config file first — sensible defaults apply immediately.

# database
~/.local/share/devgrep/devgrep.db

# optional config
~/.config/devgrep/config.yaml

Indexing parses developer artifacts into normalized documents stored in SQLite. Each indexer implements a pluggable interface in internal/indexer:

• shell-history — bash/zsh history with duplicate suppression
• logs — .log files under indexed paths
• markdown-notes — .md and .markdown files

Storage uses WAL mode, prepared statements, and source_states for incremental offsets so re-indexing only processes new content.

A source is a category of indexed content: history, logs, or notes. Control which sources are indexed or searched with --source:

devgrep index --source history
devgrep search --source logs "connection refused"
devgrep search --source history,logs --plain "deploy"

View what is indexed with devgrep sources or devgrep sources --tree for a directory tree.

Direct search skips the subcommand when the first argument is not a known command:

devgrep postgres timeout
# same as
devgrep search "postgres timeout"

When stdout is a terminal, search opens the Bubble Tea TUI. Use --plain for scriptable output:

devgrep --plain search "docker compose"

[history]
docker compose up -d postgres

[last used]
3 weeks ago

[directory]
~/projects/auth-api

[score]
92

When you index an explicit directory, devgrep persists it as a watched path and, by default, keeps watching in the foreground:

devgrep index ~/projects/api

Watch mode uses fsnotify with 500ms debouncing. It handles new, modified, and deleted files — deletions remove documents from the index.

# index once, no watch
devgrep index ~/projects/api --no-watch

# restore persisted watchers
devgrep index --watch

Preview what would be indexed without writing to SQLite:

devgrep index . --dry-run

Dry-run lists files that would be indexed, ignored paths with reasons, and estimated counts. Use this before indexing an unfamiliar project.

Phase 1 sources

• ~/.bash_history and ~/.zsh_history
• .log files under indexed paths (configurable extensions and size limits)
• Markdown notes under indexed paths

Ignored by default

• Heavy directories: .git, node_modules, vendor, dist, build, .cache, and more
• Large files, media, binaries, and archives (centralized in internal/utils)