CodeIndex

日本語版はこちら / Japanese version

A CLI tool that indexes large codebases into a SQLite database for fast search. Works for both humans and AI agents.

Prerequisites

.NET 8.0 SDK is required to build cdidx.

OS	Install command
Linux (Ubuntu/Debian)	`sudo apt-get update && sudo apt-get install -y dotnet-sdk-8.0`
Linux (Fedora)	`sudo dnf install dotnet-sdk-8.0`
macOS	`brew install dotnet@8`
Windows	`winget install Microsoft.DotNet.SDK.8`

Alternatively, download the installer from dotnet.microsoft.com.

Verify:

dotnet --version   # should print 8.x.x

Installation

1. Build

dotnet build src/CodeIndex/CodeIndex.csproj -c Release
dotnet publish src/CodeIndex/CodeIndex.csproj -c Release -o ./publish

2. Add to PATH

Linux

sudo cp ./publish/cdidx /usr/local/bin/cdidx

macOS

sudo cp ./publish/cdidx /usr/local/bin/cdidx

If /usr/local/bin is not in your PATH (Apple Silicon default shell):

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

Windows

# PowerShell (run as Administrator)
New-Item -ItemType Directory -Force -Path C:\Tools
Copy-Item .\publish\cdidx.exe C:\Tools\cdidx.exe

# Add to PATH permanently (current user)
$path = [Environment]::GetEnvironmentVariable('Path', 'User')
if ($path -notlike '*C:\Tools*') {
    [Environment]::SetEnvironmentVariable('Path', "$path;C:\Tools", 'User')
}

Restart your terminal after adding to PATH.

3. Verify

cdidx --version

Quick Start

Index a project

cdidx ./myproject
cdidx ./myproject --rebuild     # full rebuild from scratch
cdidx ./myproject --verbose     # show per-file details

Default output:

⠹ Scanning...
  Found 42 files

Indexing...
  ████████████████████░░░░░░░░░░░░  67.0%  [28/42]

Done.
  Files   : 42
  Chunks  : 318
  Symbols : 156
  Skipped : 28 (unchanged)
  Elapsed : 00:00:02

With --verbose, each file also shows a status tag so you can see exactly what happened:

  [OK  ] src/app.cs (12 chunks, 5 symbols)
  [SKIP] src/utils.cs
  [DEL ] src/old.cs
  [ERR ] src/bad.cs: <message>

[OK ] = indexed successfully, [SKIP] = unchanged / skipped, [DEL ] = deleted from DB (file removed from disk), [ERR ] = failed (verbose mode includes stack trace)

This is useful for debugging indexing issues or verifying which files were actually processed.

Search code

cdidx search "authenticate"              # full-text search
cdidx search "handleRequest" --lang go   # filter by language
cdidx search "TODO" --limit 50           # more results

Output:

src/Auth/Login.cs:15-30
  public bool Authenticate(string user, string pass)
  {
      var hash = ComputeHash(pass);
      return _store.Verify(user, hash);
  ...

src/Auth/TokenService.cs:42-58
  public string GenerateToken(User user)
  {
      var claims = BuildClaims(user);
      return _jwt.CreateToken(claims);
  ...

(2 results)

Use --json for machine-readable output (AI agents):

{"path":"src/Auth/Login.cs","start_line":15,"end_line":30,"content":"public bool Authenticate(...)...","lang":"csharp","score":12.5}
{"path":"src/Auth/TokenService.cs","start_line":42,"end_line":58,"content":"public string GenerateToken(...)...","lang":"csharp","score":9.8}

Search symbols (functions, classes, etc.)

cdidx symbols UserService              # find by name
cdidx symbols --kind class             # all classes
cdidx symbols --kind function --lang python

Output:

class      UserService                              src/Services/UserService.cs:8
function   GetUserById                              src/Services/UserService.cs:24
function   CreateUser                               src/Services/UserService.cs:45
(3 symbols)

List files

cdidx files                            # all indexed files
cdidx files --lang csharp              # only C# files

Output:

csharp          120 lines  src/Services/UserService.cs
csharp           85 lines  src/Controllers/UserController.cs
csharp           42 lines  src/Models/User.cs
(3 files)

Check status

cdidx status

Output:

Files   : 42
Chunks  : 318
Symbols : 156
Languages:
  csharp         28
  python         10
  javascript      4

Options

Option	Applies to	Description
`--db <path>`	All commands	Database file path (default: `codeindex.db`)
`--json`	All commands	JSON output (for AI/machine use)
`--limit <n>`	Query commands	Max results (default: 20)
`--lang <lang>`	Query commands	Filter by language
`--kind <kind>`	`symbols`	Filter by symbol kind (function/class/import)
`--rebuild`	`index`	Delete existing DB and rebuild
`--verbose`	`index`	Show per-file status (`[OK ]`/`[SKIP]`/`[DEL ]`/`[ERR ]`)
`--commits <id...>`	`index`	Update only files changed in specified commits
`--files <path...>`	`index`	Update only the specified files

Exit codes

Code	Meaning
`0`	Success
`1`	Usage error (invalid arguments)
`2`	Not found (no search results, missing directory)
`3`	Database error

How it works

cdidx scans your project directory, splits each source file into overlapping chunks, and stores everything in a SQLite database with FTS5 full-text search. Incremental mode (default) first purges database entries for files that no longer exist on disk, then checks each file's last-modified timestamp against the database — only files whose timestamp exactly matches are skipped, and any difference (newer or older) triggers re-indexing. Newly appeared files are indexed as new entries. This means re-indexing after a branch switch only processes the files that actually differ.

Git branch switching

The database reflects the working tree at the time of the last index. After switching branches, simply re-run cdidx . — files that no longer exist on disk are purged from the database, newly appeared files are indexed, and existing files are re-indexed only when their timestamp differs. The update is proportional to the number of changed files, not the total project size.

Situation	What happens
File unchanged across branches	Skipped (instant)
File content changed	Re-indexed
File deleted after checkout	Purged from DB
File added after checkout	Indexed as new

Supported languages

Language	Extensions	Symbols
Python	`.py`	yes
JavaScript	`.js`, `.jsx`	yes
TypeScript	`.ts`, `.tsx`	yes
C#	`.cs`	yes
Go	`.go`	yes
Rust	`.rs`	yes
Java	`.java`	yes
Kotlin	`.kt`	yes
Ruby	`.rb`	yes
C	`.c`, `.h`	yes
C++	`.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`	yes
PHP	`.php`	yes
Swift	`.swift`	yes
Shell	`.sh`	--
SQL	`.sql`	--
Markdown	`.md`	--
YAML	`.yaml`, `.yml`	--
JSON	`.json`	--
TOML	`.toml`	--
HTML	`.html`	--
CSS	`.css`, `.scss`	--
Vue	`.vue`	--
Svelte	`.svelte`	--
Terraform	`.tf`	--

All languages are fully searchable via FTS5. Languages with Symbols = yes also support structured queries by function/class/import name.

Prerequisites: sqlite3

AI agents that query the database directly via SQL need the sqlite3 CLI.

OS	Status
macOS	Pre-installed
Linux	Usually pre-installed. If not: `sudo apt install sqlite3`
Windows	`winget install SQLite.SQLite` or `scoop install sqlite`

AI Integration

cdidx is designed as an AI-friendly code search tool. All query commands support --json for JSON lines output, making them easy to parse programmatically.

Setup: Add to CLAUDE.md

To let AI agents use the generated codeindex.db, place a CLAUDE.md in your project root:

# Code Search Rules

This project has a `codeindex.db` file.
When searching code, **query this SQLite database** instead of using `find`, `grep`, or `ls -R`.

## Keeping the index up to date

After editing files, update the database so search results stay accurate:

```bash
cdidx . --files path/to/changed_file.cs   # update specific files you modified
cdidx . --commits HEAD                     # update all files changed in the last commit
cdidx . --commits abc123                   # you can also pass a specific commit hash
cdidx .                                    # full incremental update (skips unchanged files)
```

**Rule: whenever you modify source files, run one of the above before your next search.**

## CLI (recommended)

```bash
cdidx search "keyword"           # full-text search (JSON lines)
cdidx symbols "ClassName"        # structured symbol search
cdidx files --lang python        # list indexed files
cdidx status --json              # DB stats
```

## Direct SQL queries

The queries below require `sqlite3`. If it is not installed, suggest the user install it:
- **macOS**: pre-installed
- **Linux**: `sudo apt install sqlite3`
- **Windows**: `winget install SQLite.SQLite` or `scoop install sqlite`

### Full-text search
```sql
SELECT f.path, c.start_line, c.content
FROM fts_chunks fc
JOIN chunks c ON c.id = fc.rowid
JOIN files f ON f.id = c.file_id
WHERE fts_chunks MATCH 'keyword'
LIMIT 20;
```

### Search by function/class name
```sql
SELECT f.path, s.name, s.line
FROM symbols s
JOIN files f ON f.id = s.file_id
WHERE s.kind = 'function' AND s.name LIKE '%keyword%';
```

Incremental updates for CI / hooks

Instead of re-indexing the entire project, AI agents can update only the files that changed:

# Update only files changed in specific commits (e.g. in a post-merge hook)
cdidx ./myproject --commits abc123 def456

# Update only specific files (e.g. after saving a file in an editor hook)
cdidx ./myproject --files src/app.cs src/utils.cs

These options make it practical to keep the index up-to-date in real time, even on large codebases.

Why cdidx over grep/ripgrep for AI?

	`grep` / `rg`	`cdidx`
Output format	Plain text (needs parsing)	JSON lines (machine-ready)
Search speed on large repos	Scans every file each time	Pre-built FTS5 index
Symbol awareness	None	Functions, classes, imports
Incremental update	N/A	`--commits`, `--files`

More

Developer Guide — Architecture, database schema, FTS5 internals, AI integration, design decisions

CodeIndex（日本語）

大規模コードベースをSQLiteデータベースにインデックスし、高速検索を実現するCLIツールです。人間にもAIエージェントにも対応しています。

前提条件

cdidxのビルドには .NET 8.0 SDK が必要です。

OS	インストールコマンド
Linux (Ubuntu/Debian)	`sudo apt-get update && sudo apt-get install -y dotnet-sdk-8.0`
Linux (Fedora)	`sudo dnf install dotnet-sdk-8.0`
macOS	`brew install dotnet@8`
Windows	`winget install Microsoft.DotNet.SDK.8`

または dotnet.microsoft.com からインストーラーをダウンロードしてください。

確認:

dotnet --version   # 8.x.x と表示されること

インストール

1. ビルド

dotnet build src/CodeIndex/CodeIndex.csproj -c Release
dotnet publish src/CodeIndex/CodeIndex.csproj -c Release -o ./publish

2. PATHに追加

Linux

sudo cp ./publish/cdidx /usr/local/bin/cdidx

macOS

sudo cp ./publish/cdidx /usr/local/bin/cdidx

/usr/local/bin がPATHに含まれていない場合（Apple Siliconのデフォルトシェル）:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

Windows

# PowerShell（管理者として実行）
New-Item -ItemType Directory -Force -Path C:\Tools
Copy-Item .\publish\cdidx.exe C:\Tools\cdidx.exe

# PATHに永続的に追加（現在のユーザー）
$path = [Environment]::GetEnvironmentVariable('Path', 'User')
if ($path -notlike '*C:\Tools*') {
    [Environment]::SetEnvironmentVariable('Path', "$path;C:\Tools", 'User')
}

PATH追加後はターミナルを再起動してください。

3. 確認

cdidx --version

クイックスタート

プロジェクトをインデックス

cdidx ./myproject
cdidx ./myproject --rebuild     # 完全再構築
cdidx ./myproject --verbose     # ファイルごとの詳細表示

デフォルト出力:

⠹ Scanning...
  Found 42 files

Indexing...
  ████████████████████░░░░░░░░░░░░  67.0%  [28/42]

Done.
  Files   : 42
  Chunks  : 318
  Symbols : 156
  Skipped : 28 (unchanged)
  Elapsed : 00:00:02

--verbose を付けると、各ファイルにステータスタグも表示され、何が起きたか一目でわかります:

  [OK  ] src/app.cs (12 chunks, 5 symbols)
  [SKIP] src/utils.cs
  [DEL ] src/old.cs
  [ERR ] src/bad.cs: <message>

[OK ] = インデックス成功、[SKIP] = 未変更・スキップ、[DEL ] = DBから削除（ディスク上のファイルが消えた）、[ERR ] = 失敗（verboseではスタックトレースも表示）

インデックスの問題をデバッグしたり、どのファイルが実際に処理されたかを確認するのに便利です。

コード検索

cdidx search "authenticate"              # 全文検索
cdidx search "handleRequest" --lang go   # 言語でフィルタ
cdidx search "TODO" --limit 50           # 結果数を増やす

出力:

src/Auth/Login.cs:15-30
  public bool Authenticate(string user, string pass)
  {
      var hash = ComputeHash(pass);
      return _store.Verify(user, hash);
  ...

src/Auth/TokenService.cs:42-58
  public string GenerateToken(User user)
  {
      var claims = BuildClaims(user);
      return _jwt.CreateToken(claims);
  ...

(2 results)

--json でAI/機械向け出力:

{"path":"src/Auth/Login.cs","start_line":15,"end_line":30,"content":"public bool Authenticate(...)...","lang":"csharp","score":12.5}
{"path":"src/Auth/TokenService.cs","start_line":42,"end_line":58,"content":"public string GenerateToken(...)...","lang":"csharp","score":9.8}

シンボル検索（関数、クラスなど）

cdidx symbols UserService              # 名前で検索
cdidx symbols --kind class             # すべてのクラス
cdidx symbols --kind function --lang python

出力:

class      UserService                              src/Services/UserService.cs:8
function   GetUserById                              src/Services/UserService.cs:24
function   CreateUser                               src/Services/UserService.cs:45
(3 symbols)

ファイル一覧

cdidx files                            # 全インデックス済みファイル
cdidx files --lang csharp              # C#ファイルのみ

出力:

csharp          120 lines  src/Services/UserService.cs
csharp           85 lines  src/Controllers/UserController.cs
csharp           42 lines  src/Models/User.cs
(3 files)

状態確認

cdidx status

出力:

Files   : 42
Chunks  : 318
Symbols : 156
Languages:
  csharp         28
  python         10
  javascript      4

オプション一覧

オプション	対象	説明
`--db <path>`	全コマンド	DBファイルパス（デフォルト: `codeindex.db`）
`--json`	全コマンド	JSON出力（AI/機械向け）
`--limit <n>`	クエリ系	最大結果数（デフォルト: 20）
`--lang <lang>`	クエリ系	言語でフィルタ
`--kind <kind>`	`symbols`	シンボル種別でフィルタ（function/class/import）
`--rebuild`	`index`	既存DBを削除して再構築
`--verbose`	`index`	ファイルごとのステータス表示（`[OK ]`/`[SKIP]`/`[DEL ]`/`[ERR ]`）
`--commits <id...>`	`index`	指定コミットの変更ファイルのみ更新
`--files <path...>`	`index`	指定ファイルのみ更新

終了コード

コード	意味
`0`	成功
`1`	引数エラー
`2`	未検出（検索結果なし、ディレクトリ不在）
`3`	データベースエラー

動作の仕組み

cdidxはプロジェクトディレクトリを走査し、各ソースファイルを重複を持つチャンクに分割し、FTS5全文検索付きのSQLiteデータベースに格納します。インクリメンタルモード（デフォルト）では各ファイルの最終更新タイムスタンプをDB内の値と比較し、完全一致するファイルのみスキップします。タイムスタンプが異なれば（新しくても古くても）再インデックスされるため、ブランチ切り替え後も正確にインデックスが更新されます。

Gitブランチ切り替え

データベースはインデックス実行時のワーキングツリーを反映します。ブランチ切り替え後は cdidx . を再実行してください。ディスク上から消えたファイルはDBからパージされ、新たに現れたファイルはインデックスに追加され、既存ファイルはタイムスタンプが異なる場合のみ再インデックスされます。更新量はプロジェクト全体のサイズではなく変更ファイル数に比例します。

状況	動作
ブランチ間でファイル未変更	スキップ（即時）
ファイル内容が変更	再インデックス
checkout後にファイル削除	DBからパージ
checkout後にファイル追加	新規インデックス

対応言語

言語	拡張子	シンボル
Python	`.py`	yes
JavaScript	`.js`, `.jsx`	yes
TypeScript	`.ts`, `.tsx`	yes
C#	`.cs`	yes
Go	`.go`	yes
Rust	`.rs`	yes
Java	`.java`	yes
Kotlin	`.kt`	yes
Ruby	`.rb`	yes
C	`.c`, `.h`	yes
C++	`.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`	yes
PHP	`.php`	yes
Swift	`.swift`	yes
Shell	`.sh`	--
SQL	`.sql`	--
Markdown	`.md`	--
YAML	`.yaml`, `.yml`	--
JSON	`.json`	--
TOML	`.toml`	--
HTML	`.html`	--
CSS	`.css`, `.scss`	--
Vue	`.vue`	--
Svelte	`.svelte`	--
Terraform	`.tf`	--

全言語がFTS5による全文検索に対応。シンボル = yes の言語は関数・クラス・インポート名での構造化検索にも対応しています。

前提条件: sqlite3

AIエージェントがDBを直接SQL検索する場合、sqlite3 CLIが必要です。

OS	状況
macOS	プリインストール済み
Linux	通常プリインストール済み。未導入時: `sudo apt install sqlite3`
Windows	`winget install SQLite.SQLite` または `scoop install sqlite`

AIとの連携

cdidxはAI対応のコード検索ツールとして設計されています。すべてのクエリコマンドは --json でJSONライン出力に対応し、プログラムからのパースが容易です。

セットアップ: CLAUDE.mdに追加

AIエージェントに codeindex.db を活用させるには、プロジェクトルートに CLAUDE.md を配置してください:

# コードベース検索ルール

このプロジェクトには `codeindex.db` があります。
コードを検索する際は `find`, `grep`, `ls -R` ではなく**このSQLiteデータベースを検索**してください。

## インデックスの最新化

ファイルを編集したら、検索結果を正確に保つためにデータベースを更新してください:

```bash
cdidx . --files path/to/changed_file.cs   # 変更したファイルだけ更新
cdidx . --commits HEAD                     # 直前のコミットで変更されたファイルを更新
cdidx . --commits abc123                   # 特定のコミットハッシュも指定可能
cdidx .                                    # フルインクリメンタル更新（未変更ファイルはスキップ）
```

**ルール: ソースファイルを修正したら、次の検索の前に上記のいずれかを実行すること。**

## CLI（推奨）

```bash
cdidx search "keyword"           # 全文検索（JSONライン出力）
cdidx symbols "ClassName"        # 構造化シンボル検索
cdidx files --lang python        # インデックス済みファイル一覧
cdidx status --json              # DB統計情報
```

## 直接SQLクエリ

以下のクエリには `sqlite3` が必要です。未インストールの場合、ユーザーにインストールを提案してください:
- **macOS**: プリインストール済み
- **Linux**: `sudo apt install sqlite3`
- **Windows**: `winget install SQLite.SQLite` または `scoop install sqlite`

### 全文検索
```sql
SELECT f.path, c.start_line, c.content
FROM fts_chunks fc
JOIN chunks c ON c.id = fc.rowid
JOIN files f ON f.id = c.file_id
WHERE fts_chunks MATCH 'キーワード'
LIMIT 20;
```

### 関数・クラス名で検索
```sql
SELECT f.path, s.name, s.line
FROM symbols s
JOIN files f ON f.id = s.file_id
WHERE s.kind = 'function' AND s.name LIKE '%キーワード%';
```

CI / フック向けインクリメンタル更新

プロジェクト全体を再インデックスする代わりに、変更のあったファイルだけを更新できます:

# 特定コミットの変更ファイルのみ更新（例: post-mergeフックで）
cdidx ./myproject --commits abc123 def456

# 特定ファイルのみ更新（例: エディタの保存フックで）
cdidx ./myproject --files src/app.cs src/utils.cs

これらのオプションにより、大規模コードベースでもリアルタイムにインデックスを最新に保つことが実用的になります。

AIにとって grep/ripgrep より cdidx が優れる理由

	`grep` / `rg`	`cdidx`
出力形式	プレーンテキスト（パース必要）	JSONライン（機械処理可能）
大規模リポジトリでの検索速度	毎回全ファイルスキャン	構築済みFTS5インデックス
シンボル認識	なし	関数、クラス、インポート
インクリメンタル更新	N/A	`--commits`, `--files`

もっと詳しく

開発者ガイド — アーキテクチャ、DBスキーマ、FTS5の内部構造、AI連携、設計判断

Name		Name	Last commit message	Last commit date
Latest commit History 114 Commits
.github/workflows		.github/workflows
src/CodeIndex		src/CodeIndex
tests/CodeIndex.Tests		tests/CodeIndex.Tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CodeIndex.sln		CodeIndex.sln
DEVELOPER_GUIDE.md		DEVELOPER_GUIDE.md
LICENSE		LICENSE
README.md		README.md
version.json		version.json

Folders and files

Latest commit

History

Repository files navigation

CodeIndex

Prerequisites

Installation

1. Build

2. Add to PATH

3. Verify

Quick Start

Index a project

Search code

Search symbols (functions, classes, etc.)

List files

Check status

Options

Exit codes

How it works

Git branch switching

Supported languages

Prerequisites: sqlite3

AI Integration

Setup: Add to CLAUDE.md

Incremental updates for CI / hooks

Why cdidx over grep/ripgrep for AI?

More

CodeIndex（日本語）

前提条件

インストール

1. ビルド

2. PATHに追加

3. 確認

クイックスタート

プロジェクトをインデックス

コード検索

シンボル検索（関数、クラスなど）

ファイル一覧

状態確認

オプション一覧

終了コード

動作の仕組み

Gitブランチ切り替え

対応言語

前提条件: sqlite3

AIとの連携

セットアップ: CLAUDE.mdに追加

CI / フック向けインクリメンタル更新

AIにとって grep/ripgrep より cdidx が優れる理由

もっと詳しく

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages