⚡ Context Harness / Docs
Home Docs Blog Demo
Docs / Getting Started / Quick Start

Quick Start

Go from zero to searchable knowledge base in 5 minutes.

This guide takes you from installation to having an AI agent searching your codebase in 5 minutes.

1. Create a config file

$ mkdir -p config
$ cat > config/ctx.toml << 'EOF'
[db]
path = "./data/ctx.sqlite"

[chunking]
max_tokens = 700          # ~2800 chars per chunk
overlap_tokens = 80       # overlap between chunks for context

[retrieval]
final_limit = 12          # max results per query
hybrid_alpha = 0.6        # blend: 0 = keyword only, 1 = semantic only

[server]
bind = "127.0.0.1:7331"

[connectors.filesystem.local]
root = "./docs"
include_globs = ["**/*.md", "**/*.rs", "**/*.txt"]
exclude_globs = ["**/target/**", "**/node_modules/**"]
EOF

2. Initialize and sync

$ ctx init
Database initialized successfully.

$ ctx sync filesystem
sync filesystem:local
  fetched: 47 items
  upserted documents: 47
  chunks written: 203
ok

Every matching file is now chunked and indexed in SQLite with FTS5 full-text search.

3. Search from the CLI

$ ctx search "authentication flow"
1. [0.94] filesystem / src/auth.rs
   "JWT signing key loaded from AWS Secrets Manager on startup..."
2. [0.81] filesystem / docs/deployment.md
   "Key rotation procedure for production auth services..."
3. [0.72] filesystem / docs/architecture.md
   "Authentication middleware intercepts requests before routing..."

4. Start the MCP server

$ ctx serve mcp
Listening on 127.0.0.1:7331

In another terminal, verify it works:

$ curl -s localhost:7331/health
{"status":"ok"}

$ curl -s localhost:7331/tools/search \
    -H "Content-Type: application/json" \
    -d '{"query": "auth"}' | jq '.results[0]'
{
  "id": "a1b2c3d4-...",
  "source": "filesystem:local",
  "title": "src/auth.rs",
  "score": 0.94,
  "snippet": "JWT signing key loaded from..."
}

5. Connect to Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "context-harness": {
      "url": "http://127.0.0.1:7331/mcp"
    }
  }
}

Cursor connects to the /mcp endpoint, which speaks the MCP Streamable HTTP protocol (JSON-RPC). Now ask Cursor’s agent: “Search our docs for the deployment procedure” — it will call Context Harness automatically.

6. Enable semantic search (optional)

Keyword search works great out of the box. For hybrid search that understands meaning, add embeddings:

$ export OPENAI_API_KEY="sk-..."

Add to config/ctx.toml:

[embedding]
provider = "openai"
model = "text-embedding-3-small"
dims = 1536
batch_size = 64

Generate embeddings:

$ ctx embed pending
Embedding 203 chunks... done (4.2s)

$ ctx search "how does the system handle failures" --mode hybrid
# Now finds conceptually related docs, not just keyword matches

You can also use Ollama (provider = "ollama") or local models (provider = "local") for fully offline embeddings. All release binaries include the local provider (fastembed on primary platforms, tract on musl and Intel Mac). See the configuration reference for the platform table.

7. Add a remote repo (optional)

Index a GitHub repo alongside your local files:

# Add to config/ctx.toml:
[connectors.git.platform]
url = "https://github.com/acme/platform.git"
branch = "main"
include_globs = ["docs/**/*.md", "src/**/*.rs"]
shallow = true

$ ctx sync git:platform
sync git:platform
  cloning https://github.com/acme/platform.git...
  fetched: 89 items
  upserted documents: 89
  chunks written: 412
ok

# Search now returns results from both filesystem and git sources
$ ctx search "deploy" --mode hybrid

# Or sync everything at once:
$ ctx sync all

What’s next?

← Previous Installation