Skip to main content

Configuration Reference

Complete reference for all CommandLane configuration options.

Configuration File​

CommandLane uses pkb.config.json in your project or home directory. The file is created automatically on first run.

File Locations​

Configuration is loaded in this order (later overrides earlier):

  1. ./pkb.config.json (project directory)
  2. ~/.cmdlane/pkb.config.json (user config)
  3. Environment variables (highest priority)

Core Settings​

General​

OptionTypeDefaultDescription
enable_aibooleantrueEnable AI features
log_levelstring"INFO"Logging level: DEBUG, INFO, WARNING, ERROR

Watcher​

Background context monitoring settings:

OptionTypeDefaultDescription
watcher_enabled_by_defaultbooleanfalseAuto-start watcher with app
watch_interval_secondsnumber3Context polling frequency
popover_cooldown_minutesnumber5Min time between popovers
max_popover_itemsnumber2Max items per popover
popover_auto_dismiss_msnumber10000Auto-dismiss delay (ms)

AI & Classification​

Classification Engine​

OptionTypeDefaultDescription
ai_classification_use_tinybertbooleanfalseUse local TinyBERT model
ai_classification_model_pathstring".models/tinybert-tasknote/"Path to TinyBERT model
ai_classification_providerstring"local"Provider: local, openai, anthropic, ollama
ai_classification_api_modelstringvariesModel ID when using API provider
ai_classification_temperaturenumber0.0Output determinism (0.0-1.0)
ai_classification_num_predictnumber150Max tokens for classification
ai_rule_confidence_thresholdnumber0.8Rule-based classifier threshold

AI Fallback​

OptionTypeDefaultDescription
ai_classification_use_llmbooleanfalseEnable LLM fallback
ai_classification_llm_modelstring"phi3:mini"Ollama model for fallback

Storage​

SQLite Backend​

OptionTypeDefaultDescription
storage.backendstring"sqlite"Storage backend type
storage.sqlite_db_pathstring"pkb_data.db"Database file location
storage.enable_fts5booleantrueEnable full-text search
storage.enable_vector_searchbooleantrueEnable semantic search
storage.sqlite_cache_sizenumber2000SQLite cache pages
storage.sqlite_journal_modestring"WAL"Journal mode
storage.sqlite_synchronousstring"NORMAL"Sync mode

Export​

OptionTypeDefaultDescription
storage.export_enabledbooleanfalseEnable automatic exports
storage.export_pathstring"exports/"Export directory
storage.export_frequencystring"manual"realtime, daily, manual

UI Settings​

Capture Window​

OptionTypeDefaultDescription
ui_enabledbooleantrueEnable UI features
ui_hotkey_keysarray["ctrl", "space"]Capture window hotkey
ui_dashboard_hotkey_keysarray["ctrl", "shift", "d"]Dashboard hotkey
ui_window_widthnumber600Window width (pixels)
ui_window_heightnumber110Window height (pixels)
ui_window_alphanumber0.95Window transparency (0.0-1.0)
ui_animation_duration_msnumber200Animation speed

Launcher​

OptionTypeDefaultDescription
launcher_show_developer_toolsbooleanfalseShow dev tools in launcher

Agent​

OptionTypeDefaultDescription
agent_default_providerstring"auto"Default AI provider: auto, openai, anthropic, ollama
agent_default_modelstringnullProvider-specific default model
note

chat_default_provider and chat_default_model are deprecated aliases. Use the agent_ variants instead.

CDP (Browser URL Capture)​

OptionTypeDefaultDescription
cdp_enabledbooleanfalseEnable Chrome DevTools Protocol for browser URL capture
cdp_portnumber9222Chrome debug port

Search Settings​

OptionTypeDefaultDescription
search.hybrid_weightsarray[0.3, 0.7][keyword, semantic] weights
search.rrf_knumber50Reciprocal Rank Fusion k
search.max_resultsnumber50Max results per backend

Integrations​

Ollama​

OptionTypeDefaultDescription
integrations.ollama.config.base_urlstring"http://localhost:11434"Ollama server URL
integrations.ollama.connectedbooleanfalseConnection status

Notion​

OptionTypeDefaultDescription
integrations.notion.connectedbooleanfalseConnection status
integrations.notion.config.tasks_database_idstringnullTasks database ID
integrations.notion.config.notes_database_idstringnullNotes database ID

OpenAI / Anthropic​

API keys are stored encrypted in the config file. Set via environment variables or dashboard.

Security​

OptionTypeDefaultDescription
security.max_text_lengthnumber10000Max input text length
security.validate_inputsbooleantrueEnable input validation
security.atomic_writesbooleantrueUse atomic file writes

Agent​

Privacy​

Settings that control how the AI agent handles sensitive data in conversation history.

OptionTypeDefaultDescription
privacy.purge_tool_outputbooleanfalseAlso purge tool output echoed in assistant messages when saving conversations
privacy.purge_on_resumebooleantruePurge sensitive tool outputs when resuming conversations

purge_on_resume​

When a conversation is resumed, historical messages are loaded back into the agent's context. By default, purge_on_resume strips raw outputs from shell_execute and file_operation (read) tool results, replacing them with [output purged] or [content purged]. This prevents prompt injection attacks from extracting sensitive data that was read in earlier turns.

The agent's own text responses and all user messages are preserved -- only raw tool outputs are removed. If the agent needs data it read previously, it can re-read the file or re-run the command.

This is intentional and secure by default. The in-memory context for resumed sessions will not contain historical tool outputs. If you find this tradeoff unacceptable (e.g., you need the agent to reference prior tool results without re-fetching), you can disable it:

{
  "privacy": {
    "purge_on_resume": false
  }
}

Shell​

OptionTypeDefaultDescription
shell.approved_commandsarray[]User-approved command patterns for agent shell execution

Environment Variables​

All configuration options can be overridden with environment variables using the PKB_ prefix:

# Naming convention: PKB_<OPTION_NAME> (uppercase, underscores)
$env:PKB_LOG_LEVEL = "DEBUG"
$env:PKB_WATCHER_INTERVAL_SECONDS = "5"
$env:PKB_UI_HOTKEY_KEYS = "ctrl,alt,space"
$env:PKB_AI_CLASSIFICATION_TEMPERATURE = "0.1"

# Nested options use underscores
$env:PKB_STORAGE_SQLITE_DB_PATH = "custom.db"
$env:PKB_SEARCH_HYBRID_WEIGHTS = "0.4,0.6"

API Keys​

$env:OPENAI_API_KEY = "sk-..."
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Example Configurations​

Minimal (Offline)​

{
  "ai_classification_use_tinybert": true,
  "ai_classification_use_llm": false,
  "watcher_enabled_by_default": false,
  "enable_ai": true
}

Performance Optimized​

{
  "ai_classification_use_tinybert": true,
  "storage": {
    "sqlite_cache_size": 10000,
    "sqlite_journal_mode": "WAL",
    "sqlite_synchronous": "NORMAL"
  },
  "search": {
    "hybrid_weights": [0.4, 0.6],
    "rrf_k": 30
  }
}

Always-On Background​

{
  "watcher_enabled_by_default": true,
  "watch_interval_seconds": 5,
  "popover_cooldown_minutes": 3,
  "max_popover_items": 3,
  "ui_enabled": true
}

Custom Hotkeys​

{
  "ui_hotkey_keys": ["ctrl", "alt", "c"],
  "ui_dashboard_hotkey_keys": ["ctrl", "alt", "d"]
}

Large Database​

{
  "storage": {
    "sqlite_cache_size": 20000,
    "sqlite_journal_mode": "WAL",
    "sqlite_synchronous": "NORMAL",
    "enable_fts5": true,
    "enable_vector_search": true
  },
  "search": {
    "max_results": 100
  }
}

Validation​

Configuration is validated automatically:

  • On startup: CommandLane checks for invalid settings and shows errors
  • In Dashboard: Settings page shows validation errors inline
  • On save: Invalid configurations are rejected with helpful messages

Open Dashboard > Settings to see your current configuration and any validation issues.

Hot Reloading​

Most configuration changes take effect immediately. Some require restart:

  • Hotkey changes
  • Storage backend changes
  • AI model path changes