### Watch Codebase Parameters and Example

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

The `watch_codebase` tool manages watch mode for a codebase. It requires a `path` and supports an optional `action` parameter (`start`, `stop`, `status`). The example shows how to start watch mode for a specified project path.

```json
{
  "action": "start",
  "path": "/path/to/project"
}
```

--------------------------------

### Search Docs Parameters and Example

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

The `search_docs` tool enables searching through indexed documentation. It requires a `query` and supports optional parameters such as `limit`, `path_filter`, `format`, and `path`. The example shows a query for installation instructions with a path filter.

```json
{
  "query": "installation instructions",
  "limit": 5,
  "path_filter": "*.md"
}
```

--------------------------------

### Assistant Guidance File Examples

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

Examples of `AGENTS.md` and `CLAUDE.md` files used to provide guidance to AI assistants. These files specify project build/test commands and preferred SwiftIndex configurations.

```markdown
# Project Guidance

- Build: ./bin/mise run build
- Tests: ./bin/mise run test
- Config: .swiftindex.toml is linted on load
```

```markdown
# Assistant Notes

- Use swiftindex for search
- Prefer local embedding providers
- Keep changes small and well tested
```

--------------------------------

### Initialize SwiftIndex Project Configuration

Source: https://context7.com/alexey1312/swift-index/llms.txt

Initializes a SwiftIndex project by creating a `.swiftindex.toml` configuration file. It offers an interactive wizard to guide users through selecting embedding providers and models, with options for non-interactive setup and forcing an overwrite of existing configurations.

```bash
# Interactive initialization
swiftindex init

# Non-interactive with specific provider
swiftindex init --provider mlx --model "mlx-community/bge-small-en-v1.5-4bit"

# Force overwrite existing config
swiftindex init --force
```

--------------------------------

### Swift Index Configuration Example (TOML)

Source: https://context7.com/alexey1312/swift-index/llms.txt

An example of a `.swiftindex.toml` configuration file, which governs all aspects of indexing, search, and LLM enhancements. Configuration loading follows a priority order: CLI > Environment > Project > Global > Defaults.

```toml
# .swiftindex.toml

# Example configuration settings would go here.
# This file controls indexing, search, and LLM features.
# Priority: CLI > Environment > Project > Global > Defaults.
```

--------------------------------

### Cursor MCP Install Link Generation

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

Provides an example of a deep link URL format for installing SwiftIndex as an MCP server within the Cursor IDE. The `config` parameter is a base64-encoded JSON object specifying server details.

```url
cursor://anysphere.cursor-deeplink/mcp/install?name=swiftindex&config=<BASE64_JSON>
```

--------------------------------

### CLI: Install for AI Assistants

Source: https://context7.com/alexey1312/swift-index/llms.txt

Installs SwiftIndex as an MCP server for various AI assistants by generating the appropriate configuration files for project-local or global installations.

```APIDOC
## CLI: Install for AI Assistants

### Description
Installs SwiftIndex as an MCP server for various AI assistants by generating the appropriate configuration files.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Command Line Arguments
- **assistant_type** (string) - Required - The type of AI assistant to install for (e.g., `claude-code`, `cursor`, `codex`, `gemini`).
- **--global** (boolean) - Optional - Installs the configuration globally instead of project-locally.
- **--dry-run** (boolean) - Optional - Previews the configuration that would be generated without actually creating files.

### Request Example
```bash
# Claude Code (project-local .mcp.json)
swiftindex install-claude-code

# Claude Code (global ~/.claude.json)
swiftindex install-claude-code --global

# Cursor IDE (project-local .cursor/mcp.json)
swiftindex install-cursor

# Codex CLI (project-local entry in ~/.codex/config.toml)
swiftindex install-codex

# Gemini CLI
swiftindex install-gemini --global

# Dry run to preview configuration
swiftindex install-claude-code --dry-run
```

### Response
N/A (Generates configuration files for AI assistants)
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

This command installs the Xcode command line tools, which are necessary for building and testing Swift projects, especially when using Xcode. It ensures that essential development utilities are available on your system.

```bash
xcode-select --install

```

--------------------------------

### Install SwiftIndex for AI Assistants

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

Install SwiftIndex as an MCP server for various AI assistants like Claude Code, Cursor, and Codex. Supports project-local or global installations, with a dry-run option to preview configuration changes.

```bash
swiftindex install-claude-code
swiftindex install-claude-code --global
swiftindex install-claude-code --dry-run
swiftindex install-cursor
swiftindex install-codex
```

--------------------------------

### Install SwiftIndex via Homebrew

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

Installs the SwiftIndex CLI tool using the Homebrew package manager. This is the recommended installation method for ease of use and updates.

```bash
brew install alexey1312/swift-index/swiftindex
```

--------------------------------

### Human Readable Output Example

Source: https://github.com/alexey1312/swift-index/blob/main/docs/search-features.md

Displays search results in a human-friendly format, showing relevance percentages and file paths. This is the default output for the `swiftindex search` command.

```text
[98%] Sources/Auth/AuthService.swift:42-87
      func authenticate(credentials: Credentials) async throws -> Token
      Handles user authentication with JWT token generation...

[92%] Sources/Auth/TokenManager.swift:15-45
      actor TokenManager
      Manages token lifecycle including refresh...
```

--------------------------------

### Install SwiftIndex via mise

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

Installs SwiftIndex using the mise version manager, fetching the latest release directly from GitHub. This method is useful for managing multiple toolchain versions.

```bash
mise use -g github:alexey1312/swift-index@latest
```

--------------------------------

### Combined Search Filters Example

Source: https://github.com/alexey1312/swift-index/blob/main/docs/search-features.md

Demonstrates the use of multiple filters simultaneously, including file extensions, path filtering, semantic weight adjustment, and result limiting, to refine search queries.

```bash
swiftindex search \
  --extensions swift \
  --path-filter "Sources/**" \
  --semantic-weight 0.8 \
  --limit 10 \
  "authentication"
```

--------------------------------

### Verify SwiftIndex Installation

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

Commands to check if SwiftIndex has been installed correctly and to list the available embedding providers. This helps confirm the installation and understand system capabilities.

```bash
swiftindex --version
swiftindex providers
```

--------------------------------

### Install SwiftIndex for AI Assistants

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

Installs SwiftIndex configurations for various AI assistants like Claude Code, Gemini CLI, Cursor, and Codex. These commands can create project-local or global configuration files.

```bash
# Claude Code (project-local .mcp.json)
swiftindex install-claude-code

# Claude Code (global ~/.claude.json)
swiftindex install-claude-code --global

# Gemini CLI (project-local .gemini.json)
swiftindex install-gemini

# Gemini CLI (global ~/.gemini.json)
swiftindex install-gemini --global

# Cursor (project-local .cursor/mcp.json)
swiftindex install-cursor

# Codex (project-local entry in ~/.codex/config.toml with cwd)
swiftindex install-codex
```

--------------------------------

### Install SwiftIndex for AI Assistants

Source: https://context7.com/alexey1312/swift-index/llms.txt

Installs SwiftIndex as an MCP server for various AI assistants by generating the appropriate configuration files. Supports installations for Claude Code, Cursor IDE, Codex CLI, and Gemini CLI, with options for project-local or global configurations and a dry-run mode to preview generated configurations.

```bash
# Claude Code (project-local .mcp.json)
swiftindex install-claude-code

# Claude Code (global ~/.claude.json)
swiftindex install-claude-code --global

# Cursor IDE (project-local .cursor/mcp.json)
swiftindex install-cursor

# Codex CLI (project-local entry in ~/.codex/config.toml)
swiftindex install-codex

# Gemini CLI
swiftindex install-gemini --global

# Dry run to preview configuration
swiftindex install-claude-code --dry-run
```

--------------------------------

### TOON Output Example

Source: https://github.com/alexey1312/swift-index/blob/main/docs/search-features.md

A token-optimized format designed for AI assistants, offering a more compact representation of search results compared to JSON. Generated using `swiftindex search --format toon "query"`.

```bash
swiftindex search --format toon "query"
```

```text
%results
@Sources/Auth/AuthService.swift#42-87
$func authenticate(credentials: Credentials) async throws -> Token
~Handles user authentication with JWT token generation
^SwiftIndexCore > Auth > AuthService
!0.98
```

--------------------------------

### TOON Format Example: Search Results

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

This example illustrates the Token-Optimized Object Notation (TOON) format for search results. It includes query details, result metadata, code snippets, and optional LLM-generated synthesis and follow-up queries.

```text
search{q,n}:
  "query string",10

results[n]{r,rel,p,l,k,s}:
  1,95,"path.swift",[10,25],"function",["symbolName"]

meta[n]{sig,bc}:
  "func example()",~

docs[n]:
  "Description of the code..."

descs[n]:
  "Validates user credentials"

code[n]:
  ---
  func example() { ... }

synthesis{sum,insights,refs}:
  "Summary of results"

follow_ups[n]{q,cat}:
  "related query","deeper"
```

--------------------------------

### MCP Tool - search_code Example Call

Source: https://github.com/alexey1312/swift-index/blob/main/openspec/specs/mcp-server/spec.md

Demonstrates an example of calling the `search_code` tool with LLM enhancements for query expansion and result synthesis. This allows for more intelligent and comprehensive search results.

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "toolName": "search_code",
    "parameters": {
      "query": "authentication logic",
      "expand_query": true,
      "synthesize": true,
      "path_filter": "Sources/Auth/**",
      "limit": 5
    }
  },
  "id": 2
}
```

--------------------------------

### Start Swift Index MCP Server

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

This command starts the SwiftIndex MCP (Multi-language Communication Protocol) server in verbose mode. Verbose mode provides detailed logging, which is helpful for debugging server issues.

```bash
swiftindex serve --verbose

```

--------------------------------

### Search Code Parameters and Example

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

The `search_code` tool allows searching within an indexed codebase. It accepts parameters like `query`, `limit`, `semantic_weight`, `format`, `path`, `extensions`, `path_filter`, `expand_query`, and `synthesize`. The example demonstrates a typical JSON payload for this tool.

```json
{
  "query": "user authentication flow",
  "limit": 10,
  "semantic_weight": 0.8,
  "format": "toon"
}
```

--------------------------------

### SwiftIndex CLI Usage for Search Enhancement

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

Demonstrates how to use SwiftIndex's command-line interface to leverage LLM-powered search enhancements. Examples include query expansion, result synthesis, and using both features simultaneously.

```bash
# Expand query with related terms before searching
swiftindex search --expand-query "async networking"

# Get AI synthesis of results
swiftindex search --synthesize "authentication flow"

# Both together
swiftindex search --expand-query --synthesize "error handling"
```

--------------------------------

### Configure Search Weights (CLI)

Source: https://github.com/alexey1312/swift-index/blob/main/docs/search-features.md

Control the balance between BM25 and semantic search via the command-line interface. Allows dynamic adjustment of search parameters for specific queries.

```bash
swiftindex search --semantic-weight 0.5 "query"
```

--------------------------------

### Initialize SwiftIndex Project

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

Initializes a new SwiftIndex project in the current directory by creating a `.swiftindex.toml` configuration file. This is the first step before indexing your codebase.

```bash
cd /path/to/your/swift/project
swiftindex init
```

--------------------------------

### Tagging and Pushing for First Release

Source: https://github.com/alexey1312/swift-index/blob/main/AGENTS.md

Outlines the steps for creating and pushing a Git tag to initiate the release process. This is a prerequisite for triggering GitHub Actions and subsequent Homebrew formula updates.

```bash
# 1. Tag and push
git tag v0.1.0
git push --tags
```

--------------------------------

### CLI: Initialize Project

Source: https://context7.com/alexey1312/swift-index/llms.txt

Initializes a new SwiftIndex project by creating a `.swiftindex.toml` configuration file. Supports interactive setup or non-interactive configuration with specified embedding providers and models.

```APIDOC
## CLI: Initialize Project

### Description
Creates a `.swiftindex.toml` configuration file in your project with an interactive wizard that guides you through selecting embedding providers and models.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Command Line Arguments
- **--provider** (string) - Optional - Specifies the embedding provider (e.g., `mlx`).
- **--model** (string) - Optional - Specifies the embedding model to use (e.g., `"mlx-community/bge-small-en-v1.5-4bit"`).
- **--force** (boolean) - Optional - Forces overwriting an existing configuration file.

### Request Example
```bash
# Interactive initialization
swiftindex init

# Non-interactive with specific provider
swiftindex init --provider mlx --model "mlx-community/bge-small-en-v1.5-4bit"

# Force overwrite existing config
swiftindex init --force
```

### Response
N/A (Creates a configuration file)
```

--------------------------------

### Running Swift Project Tests and Building MLX Release Artifacts

Source: https://github.com/alexey1312/swift-index/blob/main/GEMINI.md

Provides commands for executing all tests or specific test suites within the Swift project using the 'mise' tool. It also details the process for building release artifacts, including Metal libraries, for MLX.

```bash
./bin/mise run test                              # All tests
./bin/mise run test:filter SwiftIndexCoreTests   # Specific suite

./bin/mise run build:release
```

--------------------------------

### JSON Output Example

Source: https://github.com/alexey1312/swift-index/blob/main/docs/search-features.md

Provides verbose search results in JSON format, including all metadata such as file path, line numbers, content, documentation comments, signature, breadcrumb, and relevance score. Generated using `swiftindex search --format json "query"`.

```bash
swiftindex search --format json "query"
```

```json
{
  "results": [{
    "path": "Sources/Auth/AuthService.swift",
    "startLine": 42,
    "endLine": 87,
    "content": "func authenticate...",
    "docComment": "Handles user authentication...",
    "signature": "func authenticate(credentials: Credentials) async throws -> Token",
    "breadcrumb": "SwiftIndexCore > Auth > AuthService",
    "score": 0.98,
    "kind": "function"
  }]
}
```

--------------------------------

### Swift Configuration: Include and Exclude Patterns

Source: https://github.com/alexey1312/swift-index/blob/main/openspec/specs/storage/spec.md

Shows how to configure the indexing process using include and exclude patterns. These patterns allow fine-grained control over which files are processed during indexing, enabling targeted indexing and exclusion of specific directories like tests.

```json
{
  "include": ["Sources/**/*.swift"],
  "exclude": ["**/Tests/**"]
}
```

--------------------------------

### Run Swift Tests

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

These bash commands demonstrate how to run tests for a Swift project. You can run all tests, filter by a specific test suite, or enable code coverage reporting.

```bash
# Run all tests
swift test

# Run specific test suite
swift test --filter "E2ETests"

# Run with coverage
swift test --enable-code-coverage

```

--------------------------------

### Running Swift Project Tests

Source: https://github.com/alexey1312/swift-index/blob/main/AGENTS.md

Provides commands for executing tests within the Swift project using the 'mise' tool. It shows how to run all tests or filter tests by a specific target suite.

```bash
./bin/mise run test                              # All tests
./bin/mise run test:filter SwiftIndexCoreTests   # Specific suite
```

--------------------------------

### Uninstall SwiftIndex using Homebrew

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

This command removes the SwiftIndex application installed via Homebrew. It's a straightforward way to uninstall if you used Homebrew for installation.

```bash
brew uninstall swiftindex
```

--------------------------------

### Swift CLI: Indexing Command

Source: https://github.com/alexey1312/swift-index/blob/main/openspec/specs/storage/spec.md

Demonstrates the command-line interface for indexing a project. The `swiftindex index` command initiates the indexing process, and the `--rebuild` flag ensures a complete re-index by clearing existing data first.

```bash
swiftindex index
swiftindex index --rebuild
```

--------------------------------

### Tool Selection Guide for Development Tasks

Source: https://github.com/alexey1312/swift-index/blob/main/openspec/AGENTS.md

A table summarizing recommended tools for various development tasks, including file pattern matching (Glob), code content searching (Grep), direct file access (Read), and multi-step investigation (Task). It provides a brief rationale for each tool's selection.

```text
| Task                  | Tool | Why                      |
| --------------------- | ---- | ------------------------ |
| Find files by pattern | Glob | Fast pattern matching    |
| Search code content   | Grep | Optimized regex search   |
| Read specific files   | Read | Direct file access       |
| Explore unknown scope | Task | Multi-step investigation |
```

--------------------------------

### Build Swift Project

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

This command builds the Swift project using the Swift Package Manager. It compiles all source files and dependencies, preparing the project for execution or testing.

```bash
swift build

```

--------------------------------

### Code Research Parameters and Example

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

The `code_research` tool facilitates multi-step research over the indexed codebase. It takes a `query` and optional parameters like `path`, `depth`, and `focus`. The example illustrates a research query about search enhancement configuration.

```json
{
  "query": "How is search enhancement configured and used?",
  "depth": 3,
  "focus": "architecture"
}
```

--------------------------------

### Example: Multi-Capability Change Structure

Source: https://github.com/alexey1312/swift-index/blob/main/openspec/AGENTS.md

Illustrates the directory structure for a change that spans multiple capabilities, such as authentication and notifications. It shows how different specification files (`spec.md`) can be organized within capability subdirectories.

```text
openspec/changes/add-2fa-notify/
├── proposal.md
├── tasks.md
└── specs/
    ├── auth/
    │   └── spec.md   # ADDED: Two-Factor Authentication
    └── notifications/
        └── spec.md   # ADDED: OTP email notification
```

--------------------------------

### Swift LLM Provider and Query Expansion

Source: https://context7.com/alexey1312/swift-index/llms.txt

Demonstrates creating an LLM provider using configuration and expanding a search query with synonyms and related concepts using SwiftIndex.

```swift
import SwiftIndexCore

// Create LLM provider from configuration
let config = LLMTierConfig(
    provider: "anthropic",
    model: "claude-haiku-4-5-20251001",
    timeout: 30
)

let llmProvider = try LLMProviderFactory.createProvider(
    from: config,
    openAIKey: ProcessInfo.processInfo.environment["OPENAI_API_KEY"],
    anthropicKey: ProcessInfo.processInfo.environment["ANTHROPIC_API_KEY"]
)

// Query expansion
let queryExpander = QueryExpander(provider: llmProvider)
let expanded = try await queryExpander.expand(
    query: "async networking",
    timeout: 30
)
print("Synonyms: \(expanded.synonyms)")
print("Related: \(expanded.relatedConcepts)")
```

--------------------------------

### OpenAI Embedding Provider Configuration

Source: https://github.com/alexey1312/swift-index/blob/main/README.md

Configuration for utilizing OpenAI's cloud-based embedding models. This setup requires specifying the provider and the desired OpenAI model.

```toml
[embedding]
provider = "openai"
model = "text-embedding-3-small"
```

--------------------------------

### Search by File Extensions

Source: https://github.com/alexey1312/swift-index/blob/main/docs/search-features.md

Limits the search scope to files with specific extensions, such as Swift and TypeScript. This is useful for targeting code written in particular languages.

```bash
swiftindex search --extensions swift,ts "async function"
```

--------------------------------

### Documentation Search CLI Command

Source: https://github.com/alexey1312/swift-index/blob/main/docs/search-features.md

Searches standalone documentation using the `search-docs` command in the CLI. It takes a query string to find relevant documentation.

```bash
swiftindex search-docs "installation guide"
```

--------------------------------

### Configure Codex CLI LLM Provider for SwiftIndex

Source: https://github.com/alexey1312/swift-index/blob/main/docs/search-enhancement.md

This TOML configuration sets up the Codex CLI provider for SwiftIndex. It specifies the provider and a timeout for the LLM operations.

```toml
[search.enhancement.utility]
provider = "codex-cli"
timeout = 30
```

--------------------------------

### Enable Query Expansion

Source: https://github.com/alexey1312/swift-index/blob/main/docs/search-features.md

Activates query expansion using the `--expand-query` flag. This can help find more relevant results when initial searches yield too few or no results.

```bash
swiftindex search --expand-query "query"
```

--------------------------------

### Use Query Expansion (CLI)

Source: https://github.com/alexey1312/swift-index/blob/main/docs/search-features.md

Leverage query expansion via the CLI to broaden search terms for conceptual queries. Improves recall by including synonyms, related concepts, and alternative phrasings.

```bash
# CLI
swiftindex search --expand-query "error handling"
```