Getting Started

This guide walks you through installing and configuring jeeves-watcher from scratch.

Prerequisites

• Node.js 20+ (Node.js 24+ recommended)
• Qdrant running locally or accessible via network
  • Installation: See Deployment Guide
  • Default URL: http://localhost:6333

Installation

Install globally via npm:

npm install -g @karmaniverous/jeeves-watcher
Copy

Or add to a project:

npm install --save-dev @karmaniverous/jeeves-watcher
Copy

Initialize Configuration

Create a new configuration file:

jeeves-watcher init
Copy

This generates jeeves-watcher.config.json with sensible defaults and a $schema pointer for IDE autocomplete:

{
  "$schema": "node_modules/@karmaniverous/jeeves-watcher/config.schema.json",
  "watch": {
    "paths": ["**/*.{md,markdown,txt,text,json,html,htm,pdf,docx}"],
    "ignored": ["**/node_modules/**", "**/.git/**", "**/.jeeves-watcher/**"]
  },
  "configWatch": {
    "enabled": true,
    "debounceMs": 1000
  },
  "embedding": {
    "provider": "gemini",
    "model": "gemini-embedding-001",
    "dimensions": 3072
  },
  "vectorStore": {
    "url": "http://127.0.0.1:6333",
    "collectionName": "jeeves-watcher"
  },
  "metadataDir": ".jeeves-watcher",
  "api": {
    "host": "127.0.0.1",
    "port": 1936
  },
  "logging": {
    "level": "info"
  }
}
Copy

Configure Watch Paths

Edit the watch.paths array to specify which directories to monitor. Use glob patterns for flexible matching:

{
  "watch": {
    "paths": [
      "./docs/**/*.md",
      "./notes/**/*.{md,txt}",
      "./projects/**/*.{md,json,pdf}"
    ],
    "ignored": [
      "**/node_modules/**",
      "**/.git/**",
      "**/temp/**"
    ]
  }
}
Copy

Glob syntax:

• ** — matches any number of directories
• * — matches any characters within a filename
• {md,txt} — brace expansion for multiple extensions

Set Up Embedding Provider

Google Gemini (Default)

Set your API key as an environment variable:

# Windows (PowerShell)
$env:GOOGLE_API_KEY = "your-api-key-here"

# Linux/macOS
export GOOGLE_API_KEY="your-api-key-here"
Copy

The config references it via template syntax:

{
  "embedding": {
    "provider": "gemini",
    "model": "gemini-embedding-001",
    "apiKey": "${GOOGLE_API_KEY}"
  }
}
Copy

Note: Set templates in inference rules use Handlebars {{...}} syntax (e.g. {{frontmatter.title}}), which is distinct from the ${...} environment variable syntax used in config values like embedding.apiKey.

Or hardcode the key (not recommended for committed configs):

{
  "embedding": {
    "apiKey": "AIza..."
  }
}
Copy

Mock Provider (Testing)

For testing without API costs, use the mock provider:

{
  "embedding": {
    "provider": "mock",
    "dimensions": 3072
  }
}
Copy

The mock provider generates deterministic embeddings from content hashes.

Configuration Discovery

If you don't specify --config, the watcher uses cosmiconfig to search for configuration (from current directory upward):

• jeeves-watcher property in package.json
• .jeeves-watcherrc (JSON or YAML)
• .jeeves-watcherrc.json, .jeeves-watcherrc.yaml, .jeeves-watcherrc.yml
• .jeeves-watcherrc.js, .jeeves-watcherrc.ts, .jeeves-watcherrc.cjs
• jeeves-watcher.config.js, jeeves-watcher.config.ts, jeeves-watcher.config.cjs

Validate Configuration

Check that your configuration is valid:

jeeves-watcher validate
Copy

Output:

Config valid
  Watch paths: ./docs/**/*.md, ./notes/**/*.{md,txt}
  Embedding: gemini/gemini-embedding-001
  Vector store: http://127.0.0.1:6333 (jeeves-watcher)
  API: 127.0.0.1:1936
Copy

Start the Watcher

Run in foreground (for development):

jeeves-watcher start
Copy

The watcher will:

1. Connect to Qdrant and ensure the collection exists
2. Scan all watched paths for existing files
3. Index new files or files with changed content
4. Start monitoring for filesystem changes
5. Start the HTTP API server

You should see output like:

[info] Qdrant collection ready: jeeves-watcher
[info] Initial scan: 42 files to process
[info] File processed successfully: ./docs/readme.md (chunks: 2)
[info] File processed successfully: ./notes/meeting-2026-02-20.md (chunks: 1)
...
[info] API server listening on http://127.0.0.1:1936
Copy

First Search

With the watcher running, try a search:

jeeves-watcher search "machine learning" --limit 5
Copy

Or via HTTP:

curl -X POST http://127.0.0.1:1936/search \
  -H "Content-Type: application/json" \
  -d '{"query": "machine learning", "limit": 5}'
Copy

Run as a Service

For production deployment, install as a system service. See Deployment Guide for detailed instructions.

Windows (NSSM):

jeeves-watcher service install
Copy

Linux (systemd):

jeeves-watcher service install
Copy

Both commands print installation instructions — follow them to set up the service.

Next Steps

• Configuration Reference — Full config options
• Inference Rules — Automatic metadata enrichment
• API Reference — HTTP endpoints
• CLI Reference — All CLI commands
• Deployment Guide — Production setup