# Local Indexing

<p className="subtitle">
	Learn how Cody's local indexing engine works to provide fast keyword search
	in your workspace.
</p>

Cody uses **symf** (symbol finder), a local keyword search engine, to create and maintain code indexes for your workspace folders. This enables fast context retrieval directly from your local codebase.

## How Local Indexing Works

Symf automatically creates and maintains indexes of your code:

-   Starts automatically when you open a workspace and authenticate
-   Runs in the background with minimal performance impact
-   Detects file changes and reindexes as needed
-   Persists across restarts for instant availability

## Configuration Settings

### VS Code Settings

Configure symf behavior through VS Code settings (`settings.json`):

**`cody.experimental.symf.enabled`** (default: `true`)

-   Enables or disables symf functionality
-   Set to `false` to completely disable local indexing

**`cody.internal.symf.path`**

-   Specify a custom path to the symf binary
-   When set, automatic download is skipped
-   Useful for custom builds or air-gapped environments

**Manual Index Control:**

Use the Command Palette to manually trigger indexing:

-   **`Cody: Update search index for current workspace folder`** - Reindex the active workspace folder
-   **`Cody: Update search index for all workspace folders`** - Reindex all open workspace folders

### JetBrains Settings

Configure symf behavior in your project's custom settings file:

**Location:** `.idea/.sourcegraph/cody_settings.json`

**`cody.experimental.symf.enabled`** (default: `true`)

```json
{
	"cody.experimental.symf.enabled": "true"
}
```

**Note:** JetBrains does not currently expose manual index control commands. Indexing happens automatically in the background through the Cody Agent.

### Enterprise Configuration

Administrators can use the **`symf-retrieval-disabled`** feature flag to completely disable symf for their organization. This:

-   Prevents automatic binary downloads
-   Disables all symf operations
-   Useful for organizations with strict firewall policies
-   Works for both VS Code and JetBrains clients

## Index Storage Location

Indexes are stored in your VS Code extension's global storage directory under `symf/indexroot/`. The exact location varies by operating system:

### Windows

```
%APPDATA%\Code\User\globalStorage\sourcegraph.cody-ai\symf\indexroot\
```

### macOS

```
~/Library/Application Support/Code/User/globalStorage/sourcegraph.cody-ai/symf/indexroot/
```

### Linux

```
~/.config/Code/User/globalStorage/sourcegraph.cody-ai/symf/indexroot/
```

Each workspace folder gets its own subdirectory based on its absolute path. The symf binary itself is stored in the parent `symf/` directory.

### Additional Storage Directories

-   **`.tmp/`** - Temporary indexes during rebuilding
-   **`.trash/`** - Deleted indexes
-   **`.failed/`** - Tracks failed index attempts to prevent retry loops

## Limitations

-   **Desktop only** - Only works on VS Code Desktop with local file systems (file:// URIs)
-   **Not supported** on VS Code Web, remote workspaces, or virtual file systems
-   **Authentication required** - Indexing only starts after you authenticate with Cody
-   **Retry logic** - If indexing fails, it won't automatically retry unless you manually trigger a reindex

### Network Requirements

The symf binary is automatically downloaded from GitHub (`https://github.com/sourcegraph/symf/releases/`). Organizations with firewall restrictions should either:

1. Allow downloads from GitHub releases
2. Use the `cody.internal.symf.path` setting to point to a manually installed binary
3. Enable the `symf-retrieval-disabled` feature flag to disable symf entirely

## Troubleshooting

If you experience issues with local indexing:

1. **Check the Cody output channel** for debug logs (View → Output → Cody)
2. **Manually trigger reindexing** using the Command Palette commands
3. **Clear indexes** by deleting the storage directory and restarting VS Code
4. **Use a custom binary** if automatic downloads fail due to network restrictions
5. **Verify authentication** - Ensure you're signed in to Cody

For persistent issues, consider disabling symf with `cody.experimental.symf.enabled: false` and relying on other context retrieval methods.