sync: Auto-sync from Mikes-MacBook-Air.local at 2026-01-26 19:45:00
Synced files: - Removed grepai installation temp files (CHANGELOG.md, LICENSE, README.md, grepai.zip) - grepai v0.19.0 installed and configured on Mac - Index built: 960 files, 6430 chunks, 1842 symbols Machine: Mikes-MacBook-Air.local Timestamp: 2026-01-26 19:45:00 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
339
CHANGELOG.md
339
CHANGELOG.md
@@ -1,339 +0,0 @@
|
|||||||
# Changelog
|
|
||||||
|
|
||||||
All notable changes to this project will be documented in this file.
|
|
||||||
|
|
||||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
||||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
||||||
|
|
||||||
## [Unreleased]
|
|
||||||
|
|
||||||
## [0.19.0] - 2026-01-22
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Watcher Performance Optimization**: Skip unchanged files on subsequent launches (#62)
|
|
||||||
- New `last_index_time` field in configuration tracks last indexing timestamp
|
|
||||||
- Files with ModTime before `last_index_time` are skipped, avoiding unnecessary embeddings
|
|
||||||
- Config write throttling (30s) prevents file system overload during active development
|
|
||||||
- Significantly faster subsequent `grepai watch` launches (~1ms vs ~100ms for unchanged codebases)
|
|
||||||
- Fully backward compatible: old configs work normally, optimization kicks in after first watch
|
|
||||||
|
|
||||||
### Changed
|
|
||||||
|
|
||||||
- `Indexer` now accepts `lastIndexTime` parameter for ModTime-based file skipping
|
|
||||||
- `runInitialScan` returns `IndexStats` to enable conditional config updates
|
|
||||||
|
|
||||||
## [0.18.0] - 2026-01-21
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Qdrant Vector Store Backend**: New storage backend using Qdrant vector database (#57)
|
|
||||||
- Support for local Qdrant (Docker) and Qdrant Cloud
|
|
||||||
- gRPC connection with TLS support
|
|
||||||
- Automatic collection creation and management
|
|
||||||
- Docker Compose profile for easy local setup: `docker compose --profile=qdrant up`
|
|
||||||
- Configuration options: endpoint, port, TLS, API key, collection name
|
|
||||||
|
|
||||||
### Fixed
|
|
||||||
|
|
||||||
- **Qdrant Backend Improvements**: Various fixes and improvements
|
|
||||||
- Fixed default port display in `grepai init` prompt (6333 → 6334 for gRPC)
|
|
||||||
- Added UTF-8 sanitization to prevent indexing errors on files with invalid characters
|
|
||||||
- Added `qdrant_storage` to default ignore patterns
|
|
||||||
- Updated CLI help to include qdrant in backend options
|
|
||||||
- Fixed typo in compose.yaml ("Optionnal" → "Optional")
|
|
||||||
|
|
||||||
## [0.17.0] - 2026-01-21
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Cursor Rules Support**: `grepai agent-setup` now supports `.cursor/rules` configuration file (#59)
|
|
||||||
- `.cursor/rules` (Cursor's current standard) takes priority over deprecated `.cursorrules`
|
|
||||||
- Backwards compatibility maintained for existing `.cursorrules` files
|
|
||||||
- Both files are configured if present (idempotence handled by marker detection)
|
|
||||||
|
|
||||||
## [0.16.1] - 2026-01-18
|
|
||||||
|
|
||||||
### Fixed
|
|
||||||
|
|
||||||
- **CLI Error Display**: Commands now properly display error messages on stderr (#52, #53)
|
|
||||||
- Previously errors were silenced by Cobra's `SilenceErrors: true` setting
|
|
||||||
- Permission errors in `update` command now show user-friendly message with sudo suggestion
|
|
||||||
|
|
||||||
## [0.16.0] - 2026-01-16
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Background Daemon Mode**: New flags for `grepai watch` to run as a background process
|
|
||||||
- `grepai watch --background`: Start watcher as a detached daemon
|
|
||||||
- `grepai watch --status`: Check if background watcher is running (shows PID and log location)
|
|
||||||
- `grepai watch --stop`: Gracefully stop the background watcher (with 30s timeout)
|
|
||||||
- `--log-dir`: Override default log directory
|
|
||||||
- OS-specific default log directories:
|
|
||||||
- Linux: `~/.local/state/grepai/logs/` (or `$XDG_STATE_HOME`)
|
|
||||||
- macOS: `~/Library/Logs/grepai/`
|
|
||||||
- Windows: `%LOCALAPPDATA%\grepai\logs\`
|
|
||||||
- PID file management with file locking to prevent race conditions
|
|
||||||
- Automatic stale PID detection and cleanup
|
|
||||||
- Ready signaling: parent waits for child to fully initialize before returning
|
|
||||||
- Graceful shutdown with index persistence on SIGINT/SIGTERM
|
|
||||||
- **New `daemon` package**: Cross-platform process lifecycle management
|
|
||||||
- Platform-specific implementations for Unix and Windows
|
|
||||||
- File locking (flock on Unix, LockFileEx on Windows)
|
|
||||||
- Process detection and signal handling
|
|
||||||
|
|
||||||
## [0.15.1] - 2026-01-16
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **External Gitignore Support**: New `external_gitignore` configuration option to specify a path to an external gitignore file (e.g., `~/.config/git/ignore`) (#50)
|
|
||||||
- Supports `~` expansion for home directory paths
|
|
||||||
- External patterns are respected during indexing alongside project-level `.gitignore` files
|
|
||||||
- If the file doesn't exist, a warning is logged but indexing continues normally
|
|
||||||
|
|
||||||
## [0.15.0] - 2026-01-14
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **C# Language Support for Trace**: Symbol extraction and call graph analysis now supports C# (#48)
|
|
||||||
- Classes (with inheritance, generics, sealed/abstract/static/partial modifiers)
|
|
||||||
- Structs (including readonly and ref structs)
|
|
||||||
- Records (record, record class, record struct)
|
|
||||||
- Interfaces (including generic interfaces)
|
|
||||||
- Methods (with all modifiers: public, private, protected, internal, static, virtual, override, abstract, async, etc.)
|
|
||||||
- Constructors
|
|
||||||
- Expression-bodied members
|
|
||||||
- C# keywords added to filter out false positives
|
|
||||||
- `.cs` added to default traced languages
|
|
||||||
- Tree-sitter support for precise symbol extraction
|
|
||||||
|
|
||||||
## [0.14.0] - 2026-01-12
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Java Language Support for Trace**: Symbol extraction and call graph analysis now supports Java (#32)
|
|
||||||
- Classes (with extends/implements, generics, sealed/non-sealed)
|
|
||||||
- Inner and nested classes
|
|
||||||
- Interfaces (including generic interfaces)
|
|
||||||
- Annotations (`@interface`)
|
|
||||||
- Enums (top-level and inner, with methods)
|
|
||||||
- Records (Java 14+)
|
|
||||||
- Methods with all modifiers (public, protected, private, static, final, abstract, synchronized, native, strictfp)
|
|
||||||
- Constructors
|
|
||||||
- Default interface methods (Java 8+)
|
|
||||||
- Abstract methods
|
|
||||||
- Java keywords added to filter out false positives
|
|
||||||
- `.java` added to default traced languages
|
|
||||||
|
|
||||||
## [0.13.0] - 2026-01-12
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Self-Update Command**: New `grepai update` command for automatic updates (#42)
|
|
||||||
- `grepai update --check`: Check for available updates without installing
|
|
||||||
- `grepai update`: Download and install the latest version from GitHub releases
|
|
||||||
- `grepai update --force`: Force update even if already on latest version
|
|
||||||
- Automatic platform detection (linux/darwin/windows, amd64/arm64)
|
|
||||||
- SHA256 checksum verification before installation
|
|
||||||
- Progress bar during download
|
|
||||||
- Graceful error handling for network issues, rate limits, and permission errors
|
|
||||||
|
|
||||||
### Changed
|
|
||||||
|
|
||||||
- **Makefile**: Uses Docker for consistent linting with golangci-lint v1.64.2
|
|
||||||
|
|
||||||
## [0.12.0] - 2026-01-12
|
|
||||||
|
|
||||||
### Fixed
|
|
||||||
|
|
||||||
- **Custom OpenAI Endpoint**: Fixed `embedder.endpoint` config not being used for OpenAI provider (#35)
|
|
||||||
- Enables Azure OpenAI and Microsoft Foundry support
|
|
||||||
- Custom endpoints now correctly passed to the OpenAI embedder
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Configurable Vector Dimensions**: New `embedder.dimensions` config option (#35)
|
|
||||||
- Allows specifying vector dimensions per embedding model
|
|
||||||
- PostgreSQL vector column automatically resizes to match configured dimensions
|
|
||||||
- Backward compatible: old configs without `dimensions` use sensible defaults per provider
|
|
||||||
|
|
||||||
## [0.11.0] - 2026-01-12
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Nested `.gitignore` Support**: Each subdirectory can now have its own `.gitignore` file (#40)
|
|
||||||
- Patterns in nested `.gitignore` files apply only to their directory and subdirectories
|
|
||||||
- Matches git's native behavior for hierarchical ignore rules
|
|
||||||
- Example: `src/.gitignore` with `generated/` only ignores `src/generated/`, not `docs/generated/`
|
|
||||||
|
|
||||||
### Fixed
|
|
||||||
|
|
||||||
- **Directory Pattern Matching**: Patterns with trailing slash (e.g., `build/`) now correctly match the directory itself
|
|
||||||
- Previously only matched contents inside the directory
|
|
||||||
- Now triggers `filepath.SkipDir` for better performance on large repositories
|
|
||||||
- Significantly improves indexing speed when ignoring `node_modules/`, `vendor/`, etc.
|
|
||||||
|
|
||||||
## [0.10.0] - 2026-01-11
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Compact JSON Output**: New `--compact`/`-c` flag for `grepai search` command (#33)
|
|
||||||
- Outputs minimal JSON without `content` field for ~80% token savings
|
|
||||||
- Requires `--json` flag (returns error if used alone)
|
|
||||||
- Recommended format for AI agents: `grepai search "query" --json --compact`
|
|
||||||
- All agent setup templates updated to use `--json --compact` by default
|
|
||||||
|
|
||||||
## [0.9.0] - 2026-01-11
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Claude Code Subagent**: New `--with-subagent` flag for `grepai agent-setup` (#17)
|
|
||||||
- Creates `.claude/agents/deep-explore.md` for Claude Code
|
|
||||||
- Provides a specialized exploration agent with grepai search and trace access
|
|
||||||
- Uses `model: inherit` to match user's current model
|
|
||||||
- Subagents operate in isolated context, ensuring grepai tools are available during exploration
|
|
||||||
|
|
||||||
## [0.8.1] - 2026-01-11
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
- Simplify Claude Code MCP setup: use `claude mcp add` command instead of manual JSON configuration
|
|
||||||
|
|
||||||
## [0.8.0] - 2026-01-11
|
|
||||||
|
|
||||||
### Added
|
|
||||||
- **MCP Server Mode**: New `grepai mcp-serve` command for Model Context Protocol integration (#18)
|
|
||||||
- Exposes grepai as native MCP tools for AI agents (Claude Code, Cursor, Windsurf, etc.)
|
|
||||||
- Available tools: `grepai_search`, `grepai_trace_callers`, `grepai_trace_callees`, `grepai_trace_graph`, `grepai_index_status`
|
|
||||||
- Uses stdio transport for local MCP server communication
|
|
||||||
- Structured JSON responses by default
|
|
||||||
- Works automatically in subagents without explicit configuration
|
|
||||||
|
|
||||||
## [0.7.2] - 2026-01-11
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
- **Sidebar Reorganization**: Moved "Search Boost" and "Hybrid Search" from Configuration to Features section
|
|
||||||
- **Configuration Reference**: Updated full configuration reference with correct field names
|
|
||||||
- Added missing options: `version`, `watch.debounce_ms`, `trace.mode`, `trace.enabled_languages`, `trace.exclude_patterns`
|
|
||||||
- Fixed `scanner.ignore` → `ignore` (root level)
|
|
||||||
- Fixed `store.postgres.connection_string` → `dsn`
|
|
||||||
- Removed `store.gob.path` (handled automatically)
|
|
||||||
- **Trace Documentation**: Added missing supported languages (C, C++, Zig, Rust) to the languages table
|
|
||||||
|
|
||||||
## [0.7.1] - 2026-01-11
|
|
||||||
|
|
||||||
### Added
|
|
||||||
- **Agent Setup Trace Instructions**: Updated `grepai agent-setup` to include trace command documentation (#16)
|
|
||||||
- Added "Call Graph Tracing" section with `trace callers`, `trace callees`, `trace graph` examples
|
|
||||||
- All trace examples include `--json` flag for optimal AI agent integration
|
|
||||||
- Updated workflow to include trace as step 2 for understanding function relationships
|
|
||||||
|
|
||||||
## [0.7.0] - 2026-01-10
|
|
||||||
|
|
||||||
### Added
|
|
||||||
- **Extended Language Support for Trace**: Symbol extraction now supports additional languages
|
|
||||||
- C (`.c`, `.h`) - functions, structs, enums, typedefs
|
|
||||||
- Zig (`.zig`) - functions, methods (inside structs/enums), inline/export/extern functions, structs, unions, enums, error sets, opaque types, nested types
|
|
||||||
- Rust (`.rs`) - functions, methods, structs, enums, traits, type aliases
|
|
||||||
- C++ (`.cpp`, `.hpp`, `.cc`, `.cxx`, `.hxx`) - functions, methods, classes, structs, enums
|
|
||||||
- **Default ignore patterns** for Zig and Rust build directories: `target`, `.zig-cache`, `zig-out`
|
|
||||||
|
|
||||||
## [0.6.0] - 2026-01-10
|
|
||||||
|
|
||||||
### Added
|
|
||||||
- **Search JSON Output**: New `--json`/`-j` flag for `grepai search` command
|
|
||||||
- Machine-readable JSON output optimized for AI agents
|
|
||||||
- Excludes internal fields (vector, hash, updated_at) to minimize token usage
|
|
||||||
- Error handling outputs JSON format when flag is used
|
|
||||||
- Closes #13
|
|
||||||
|
|
||||||
## [0.5.0] - 2026-01-10
|
|
||||||
|
|
||||||
### Added
|
|
||||||
- **Call Graph Tracing**: New `grepai trace` command for code navigation
|
|
||||||
- `trace callers <symbol>` - find all functions calling a symbol
|
|
||||||
- `trace callees <symbol>` - find all functions called by a symbol
|
|
||||||
- `trace graph <symbol>` - build call graph with configurable depth
|
|
||||||
- Regex-based symbol extraction (fast mode) for Go, JS/TS, Python, PHP
|
|
||||||
- Tree-sitter integration (precise mode) with build tag `treesitter`
|
|
||||||
- Separate symbol index stored in `.grepai/symbols.gob`
|
|
||||||
- JSON output for AI agent integration (`--json` flag)
|
|
||||||
- Automatic symbol indexing during `grepai watch`
|
|
||||||
|
|
||||||
## [0.4.0] - 2026-01-10
|
|
||||||
|
|
||||||
### Added
|
|
||||||
- **LM Studio Provider**: New local embedding provider using LM Studio
|
|
||||||
- Supports OpenAI-compatible API format
|
|
||||||
- Configurable endpoint and model selection
|
|
||||||
- Privacy-first alternative for local embeddings
|
|
||||||
|
|
||||||
## [0.3.0] - 2026-01-09
|
|
||||||
|
|
||||||
### Added
|
|
||||||
- **Search Boost**: Configurable score multipliers based on file paths
|
|
||||||
- Penalize tests, mocks, fixtures, generated files, and docs
|
|
||||||
- Boost source directories (`/src/`, `/lib/`, `/app/`)
|
|
||||||
- Language-agnostic patterns, enabled by default
|
|
||||||
- **Hybrid Search**: Combine vector similarity with text matching
|
|
||||||
- Uses Reciprocal Rank Fusion (RRF) algorithm
|
|
||||||
- Configurable k parameter (default: 60)
|
|
||||||
- Optional, disabled by default
|
|
||||||
- `GetAllChunks()` method to VectorStore interface for text search
|
|
||||||
- Dedicated documentation pages for Search Boost and Hybrid Search
|
|
||||||
- Feature cards on docs homepage
|
|
||||||
|
|
||||||
### Changed
|
|
||||||
- Searcher now accepts full SearchConfig instead of just BoostConfig
|
|
||||||
|
|
||||||
## [0.2.0] - 2026-01-09
|
|
||||||
|
|
||||||
### Added
|
|
||||||
- Initial release of grepai
|
|
||||||
- `grepai init` command for project initialization
|
|
||||||
- `grepai watch` command for real-time file indexing
|
|
||||||
- `grepai search` command for semantic code search
|
|
||||||
- `grepai agent-setup` command for AI agent integration
|
|
||||||
- Ollama embedding provider (local, privacy-first)
|
|
||||||
- OpenAI embedding provider
|
|
||||||
- GOB file storage backend (default)
|
|
||||||
- PostgreSQL with pgvector storage backend
|
|
||||||
- Gitignore support
|
|
||||||
- Binary file detection and exclusion
|
|
||||||
- Configurable chunk size and overlap
|
|
||||||
- Debounced file watching
|
|
||||||
- Cross-platform support (macOS, Linux, Windows)
|
|
||||||
|
|
||||||
### Security
|
|
||||||
- Privacy-first design with local embedding option
|
|
||||||
- No telemetry or data collection
|
|
||||||
|
|
||||||
## [0.1.0] - 2026-01-09
|
|
||||||
|
|
||||||
### Added
|
|
||||||
- Initial public release
|
|
||||||
|
|
||||||
[Unreleased]: https://github.com/yoanbernabeu/grepai/compare/v0.19.0...HEAD
|
|
||||||
[0.19.0]: https://github.com/yoanbernabeu/grepai/compare/v0.18.0...v0.19.0
|
|
||||||
[0.18.0]: https://github.com/yoanbernabeu/grepai/compare/v0.17.0...v0.18.0
|
|
||||||
[0.17.0]: https://github.com/yoanbernabeu/grepai/compare/v0.16.1...v0.17.0
|
|
||||||
[0.16.1]: https://github.com/yoanbernabeu/grepai/compare/v0.16.0...v0.16.1
|
|
||||||
[0.16.0]: https://github.com/yoanbernabeu/grepai/compare/v0.15.1...v0.16.0
|
|
||||||
[0.15.1]: https://github.com/yoanbernabeu/grepai/compare/v0.15.0...v0.15.1
|
|
||||||
[0.15.0]: https://github.com/yoanbernabeu/grepai/compare/v0.14.0...v0.15.0
|
|
||||||
[0.14.0]: https://github.com/yoanbernabeu/grepai/compare/v0.13.0...v0.14.0
|
|
||||||
[0.13.0]: https://github.com/yoanbernabeu/grepai/compare/v0.12.0...v0.13.0
|
|
||||||
[0.12.0]: https://github.com/yoanbernabeu/grepai/compare/v0.11.0...v0.12.0
|
|
||||||
[0.11.0]: https://github.com/yoanbernabeu/grepai/compare/v0.10.0...v0.11.0
|
|
||||||
[0.10.0]: https://github.com/yoanbernabeu/grepai/compare/v0.9.0...v0.10.0
|
|
||||||
[0.9.0]: https://github.com/yoanbernabeu/grepai/compare/v0.8.1...v0.9.0
|
|
||||||
[0.8.1]: https://github.com/yoanbernabeu/grepai/compare/v0.8.0...v0.8.1
|
|
||||||
[0.8.0]: https://github.com/yoanbernabeu/grepai/compare/v0.7.2...v0.8.0
|
|
||||||
[0.7.2]: https://github.com/yoanbernabeu/grepai/compare/v0.7.1...v0.7.2
|
|
||||||
[0.7.1]: https://github.com/yoanbernabeu/grepai/compare/v0.7.0...v0.7.1
|
|
||||||
[0.7.0]: https://github.com/yoanbernabeu/grepai/compare/v0.6.0...v0.7.0
|
|
||||||
[0.6.0]: https://github.com/yoanbernabeu/grepai/compare/v0.5.0...v0.6.0
|
|
||||||
[0.5.0]: https://github.com/yoanbernabeu/grepai/compare/v0.4.0...v0.5.0
|
|
||||||
[0.4.0]: https://github.com/yoanbernabeu/grepai/compare/v0.3.0...v0.4.0
|
|
||||||
[0.3.0]: https://github.com/yoanbernabeu/grepai/compare/v0.2.0...v0.3.0
|
|
||||||
[0.2.0]: https://github.com/yoanbernabeu/grepai/compare/v0.1.0...v0.2.0
|
|
||||||
[0.1.0]: https://github.com/yoanbernabeu/grepai/releases/tag/v0.1.0
|
|
||||||
21
LICENSE
21
LICENSE
@@ -1,21 +0,0 @@
|
|||||||
MIT License
|
|
||||||
|
|
||||||
Copyright (c) 2026 Yoan Bernabeu
|
|
||||||
|
|
||||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
||||||
of this software and associated documentation files (the "Software"), to deal
|
|
||||||
in the Software without restriction, including without limitation the rights
|
|
||||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
||||||
copies of the Software, and to permit persons to whom the Software is
|
|
||||||
furnished to do so, subject to the following conditions:
|
|
||||||
|
|
||||||
The above copyright notice and this permission notice shall be included in all
|
|
||||||
copies or substantial portions of the Software.
|
|
||||||
|
|
||||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
||||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
||||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
||||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
||||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
||||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
||||||
SOFTWARE.
|
|
||||||
269
README.md
269
README.md
@@ -1,269 +0,0 @@
|
|||||||
# grepai
|
|
||||||
|
|
||||||
[](https://github.com/yoanbernabeu/grepai/actions/workflows/ci.yml)
|
|
||||||
[](https://goreportcard.com/report/github.com/yoanbernabeu/grepai)
|
|
||||||
[](LICENSE)
|
|
||||||
[](https://yoanbernabeu.github.io/grepai/)
|
|
||||||
|
|
||||||
> **[Full documentation available here](https://yoanbernabeu.github.io/grepai/)** — Installation guides, configuration options, AI agent integration, and more.
|
|
||||||
|
|
||||||
**A privacy-first, CLI-native way to semantically search your codebase.**
|
|
||||||
|
|
||||||
Search code by *what it does*, not just what it's called. `grepai` indexes the meaning of your code using vector embeddings, enabling natural language queries that find conceptually related code—even when naming conventions vary.
|
|
||||||
|
|
||||||
## Why grepai?
|
|
||||||
|
|
||||||
`grep` was built in 1973 for exact text matching. Modern codebases need semantic understanding.
|
|
||||||
|
|
||||||
| | `grep` / `ripgrep` | `grepai` |
|
|
||||||
|----------------------|------------------------------|-----------------------------------|
|
|
||||||
| **Search type** | Exact text / regex | Semantic understanding |
|
|
||||||
| **Query** | `"func.*Login"` | `"user authentication flow"` |
|
|
||||||
| **Finds** | Exact pattern matches | Conceptually related code |
|
|
||||||
| **AI Agent context** | Requires many searches | Fewer, more relevant results |
|
|
||||||
|
|
||||||
### Built for AI Agents
|
|
||||||
|
|
||||||
grepai is designed to provide **high-quality context** to AI coding assistants. By returning semantically relevant code chunks, your agents spend less time searching and more time coding.
|
|
||||||
|
|
||||||
## Getting Started
|
|
||||||
|
|
||||||
### Installation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -sSL https://raw.githubusercontent.com/yoanbernabeu/grepai/main/install.sh | sh
|
|
||||||
```
|
|
||||||
|
|
||||||
Or download from [Releases](https://github.com/yoanbernabeu/grepai/releases).
|
|
||||||
|
|
||||||
### Quick Start
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grepai init # Initialize in your project
|
|
||||||
grepai watch # Start background indexing daemon
|
|
||||||
grepai search "error handling" # Search semantically
|
|
||||||
grepai trace callers "Login" # Find who calls a function
|
|
||||||
```
|
|
||||||
|
|
||||||
## Commands
|
|
||||||
|
|
||||||
| Command | Description |
|
|
||||||
|--------------------------|----------------------------------------|
|
|
||||||
| `grepai init` | Initialize grepai in current directory |
|
|
||||||
| `grepai watch` | Start real-time file watcher daemon |
|
|
||||||
| `grepai search <query>` | Search codebase with natural language |
|
|
||||||
| `grepai trace <cmd>` | Analyze call graph (callers/callees) |
|
|
||||||
| `grepai status` | Browse index state interactively |
|
|
||||||
| `grepai agent-setup` | Configure AI agents integration |
|
|
||||||
| `grepai update` | Update grepai to the latest version |
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grepai search "authentication" -n 5 # Limit results (default: 10)
|
|
||||||
grepai search "authentication" --json # JSON output for AI agents
|
|
||||||
grepai search "authentication" --json -c # Compact JSON (~80% fewer tokens)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Background Daemon
|
|
||||||
|
|
||||||
Run the watcher as a background process:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grepai watch --background # Start in background
|
|
||||||
grepai watch --status # Check if running
|
|
||||||
grepai watch --stop # Stop gracefully
|
|
||||||
```
|
|
||||||
|
|
||||||
Logs are stored in OS-specific directories:
|
|
||||||
|
|
||||||
| Platform | Log Directory |
|
|
||||||
|----------|---------------|
|
|
||||||
| Linux | `~/.local/state/grepai/logs/` |
|
|
||||||
| macOS | `~/Library/Logs/grepai/` |
|
|
||||||
| Windows | `%LOCALAPPDATA%\grepai\logs\` |
|
|
||||||
|
|
||||||
Use `--log-dir /custom/path` to override (must be passed to all commands):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grepai watch --background --log-dir /custom/path # Start in background
|
|
||||||
grepai watch --status --log-dir /custom/path # Check if running
|
|
||||||
grepai watch --stop --log-dir /custom/path # Stop gracefully
|
|
||||||
```
|
|
||||||
|
|
||||||
### Self-Update
|
|
||||||
|
|
||||||
Keep grepai up to date:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grepai update --check # Check for available updates
|
|
||||||
grepai update # Download and install latest version
|
|
||||||
grepai update --force # Force update even if already on latest
|
|
||||||
```
|
|
||||||
|
|
||||||
The update command:
|
|
||||||
- Fetches the latest release from GitHub
|
|
||||||
- Verifies checksum integrity
|
|
||||||
- Replaces the binary automatically
|
|
||||||
- Works on all supported platforms (Linux, macOS, Windows)
|
|
||||||
|
|
||||||
### Call Graph Analysis
|
|
||||||
|
|
||||||
Find function relationships in your codebase:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grepai trace callers "Login" # Who calls Login?
|
|
||||||
grepai trace callees "HandleRequest" # What does HandleRequest call?
|
|
||||||
grepai trace graph "ProcessOrder" --depth 3 # Full call graph
|
|
||||||
```
|
|
||||||
|
|
||||||
Output as JSON for AI agents:
|
|
||||||
```bash
|
|
||||||
grepai trace callers "Login" --json
|
|
||||||
```
|
|
||||||
|
|
||||||
## AI Agent Integration
|
|
||||||
|
|
||||||
grepai integrates natively with popular AI coding assistants. Run `grepai agent-setup` to auto-configure.
|
|
||||||
|
|
||||||
| Agent | Configuration File |
|
|
||||||
|--------------|----------------------------------------|
|
|
||||||
| Cursor | `.cursorrules` |
|
|
||||||
| Windsurf | `.windsurfrules` |
|
|
||||||
| Claude Code | `CLAUDE.md` / `.claude/settings.md` |
|
|
||||||
| Gemini CLI | `GEMINI.md` |
|
|
||||||
| OpenAI Codex | `AGENTS.md` |
|
|
||||||
|
|
||||||
### MCP Server Mode
|
|
||||||
|
|
||||||
grepai can run as an MCP (Model Context Protocol) server, making it available as a native tool for AI agents:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grepai mcp-serve # Start MCP server (stdio transport)
|
|
||||||
```
|
|
||||||
|
|
||||||
Configure in your AI tool's MCP settings:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"mcpServers": {
|
|
||||||
"grepai": {
|
|
||||||
"command": "grepai",
|
|
||||||
"args": ["mcp-serve"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Available MCP tools:
|
|
||||||
- `grepai_search` — Semantic code search
|
|
||||||
- `grepai_trace_callers` — Find function callers
|
|
||||||
- `grepai_trace_callees` — Find function callees
|
|
||||||
- `grepai_trace_graph` — Build call graph
|
|
||||||
- `grepai_index_status` — Check index health
|
|
||||||
|
|
||||||
### Claude Code Subagent
|
|
||||||
|
|
||||||
For enhanced exploration capabilities in Claude Code, create a specialized subagent:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grepai agent-setup --with-subagent
|
|
||||||
```
|
|
||||||
|
|
||||||
This creates `.claude/agents/deep-explore.md` with:
|
|
||||||
- Semantic search via `grepai search`
|
|
||||||
- Call graph tracing via `grepai trace`
|
|
||||||
- Workflow guidance for code exploration
|
|
||||||
|
|
||||||
Claude Code automatically uses this agent for deep codebase exploration tasks.
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Stored in `.grepai/config.yaml`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
embedder:
|
|
||||||
provider: ollama # ollama | lmstudio | openai
|
|
||||||
model: nomic-embed-text
|
|
||||||
endpoint: http://localhost:11434 # Custom endpoint (for Azure OpenAI, etc.)
|
|
||||||
dimensions: 768 # Vector dimensions (depends on model)
|
|
||||||
store:
|
|
||||||
backend: gob # gob | postgres
|
|
||||||
chunking:
|
|
||||||
size: 512
|
|
||||||
overlap: 50
|
|
||||||
search:
|
|
||||||
boost:
|
|
||||||
enabled: true # Structural boosting for better relevance
|
|
||||||
trace:
|
|
||||||
mode: fast # fast (regex) | precise (tree-sitter)
|
|
||||||
external_gitignore: "" # Path to external gitignore (e.g., ~/.config/git/ignore)
|
|
||||||
```
|
|
||||||
|
|
||||||
> **Note**: Old configs without `endpoint` or `dimensions` are automatically updated with sensible defaults.
|
|
||||||
|
|
||||||
### Search Boost (enabled by default)
|
|
||||||
|
|
||||||
grepai automatically adjusts search scores based on file paths. Patterns are language-agnostic:
|
|
||||||
|
|
||||||
| Category | Patterns | Factor |
|
|
||||||
|----------|----------|--------|
|
|
||||||
| Tests | `/tests/`, `/test/`, `__tests__`, `_test.`, `.test.`, `.spec.` | ×0.5 |
|
|
||||||
| Mocks | `/mocks/`, `/mock/`, `.mock.` | ×0.4 |
|
|
||||||
| Fixtures | `/fixtures/`, `/testdata/` | ×0.4 |
|
|
||||||
| Generated | `/generated/`, `.generated.`, `.gen.` | ×0.4 |
|
|
||||||
| Docs | `.md`, `/docs/` | ×0.6 |
|
|
||||||
| Source | `/src/`, `/lib/`, `/app/` | ×1.1 |
|
|
||||||
|
|
||||||
Customize or disable in `.grepai/config.yaml`. See [documentation](https://yoanbernabeu.github.io/grepai/configuration/) for details.
|
|
||||||
|
|
||||||
### Hybrid Search (optional)
|
|
||||||
|
|
||||||
Enable hybrid search to combine vector similarity with text matching:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
search:
|
|
||||||
hybrid:
|
|
||||||
enabled: true
|
|
||||||
k: 60
|
|
||||||
```
|
|
||||||
|
|
||||||
Uses [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf) to merge results. Useful when queries contain exact identifiers.
|
|
||||||
|
|
||||||
### Embedding Providers
|
|
||||||
|
|
||||||
**Ollama (Default)** — Privacy-first, runs locally:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ollama pull nomic-embed-text
|
|
||||||
```
|
|
||||||
|
|
||||||
**LM Studio** — Local, OpenAI-compatible API:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Start LM Studio and load an embedding model
|
|
||||||
# Default endpoint: http://127.0.0.1:1234
|
|
||||||
```
|
|
||||||
|
|
||||||
**OpenAI** — Cloud-based:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export OPENAI_API_KEY=sk-...
|
|
||||||
```
|
|
||||||
|
|
||||||
### Storage Backends
|
|
||||||
|
|
||||||
- **GOB (Default)**: File-based, zero config
|
|
||||||
- **PostgreSQL + pgvector**: For large monorepos
|
|
||||||
- **Qdrant**: Docker-based vector database
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Ollama, LM Studio, or OpenAI API key (for embeddings)
|
|
||||||
- Go 1.22+ (only for building from source)
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
[MIT License](LICENSE) - Yoan Bernabeu 2026
|
|
||||||
BIN
grepai.zip
BIN
grepai.zip
Binary file not shown.
Reference in New Issue
Block a user