byterover-cli 1.3.0 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # ByteRover CLI
 
-Command-line interface for ByteRover, featuring an interactive REPL with a modern React/Ink terminal UI for managing your project's context tree and knowledge storage. Seamlessly integrate with 18 AI coding agents via modern skill files, MCP tools, or rules-based integration—supports Claude Code, Cursor, Windsurf, GitHub Copilot, Cline, and 13 more.
+Command-line interface for ByteRover, featuring an interactive REPL with a modern React/Ink terminal UI for managing your project's context tree and knowledge storage. Seamlessly integrate with 19 AI coding agents via modern skill files, MCP tools, or rules-based integration—supports Claude Code, Cursor, Windsurf, GitHub Copilot, Cline, and more.
 
 [![Version](https://img.shields.io/npm/v/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
 [![Downloads/week](https://img.shields.io/npm/dw/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
@@ -14,6 +14,7 @@ Command-line interface for ByteRover, featuring an interactive REPL with a moder
 * [Keyboard Shortcuts](#keyboard-shortcuts)
 * [What is Context Tree?](#what-is-context-tree)
 * [Supported AI Agents](#supported-ai-agents)
+* [LLM Providers](#llm-providers) (BETA)
 * [Slash Commands Reference](#slash-commands-reference)
 * [Authentication](#authentication)
 * [Configuration](#configuration)
@@ -51,7 +52,7 @@ brv --version
 
 Visit [**ByteRover Docs**](https://docs.byterover.dev) for more information.
 
-Get started with ByteRover CLI in three simple steps:
+Get started with ByteRover CLI:
 
 ### 1. Start the REPL
 
@@ -91,6 +92,14 @@ ByteRover automatically configures the best connector for your installed agents:
 - **MCP tools** for most other agents (universal protocol)
 - Switch connector types anytime via `/connectors`
 
+### 5. (Optional) Connect an LLM Provider
+
+```
+/provider
+```
+
+ByteRover works out of the box with its built-in LLM provider. To use your own models, connect to [OpenRouter](https://openrouter.ai/keys) for access to 200+ models. See [LLM Providers](#llm-providers) for details.
+
 You're now ready to use ByteRover! Try `/status` to see your project's current state.
 
 ## Interactive REPL
@@ -154,7 +163,7 @@ The **Context Tree** is ByteRover's structured knowledge system that helps you a
 - **Organized Knowledge**: Structure your project knowledge by domain and topic
 - **Easy Retrieval**: Find relevant context quickly when you need it
 - **Persistent Memory**: Maintain project-specific knowledge across sessions
-- **Agent-Friendly**: Works seamlessly with 18 AI coding agents (Claude Code, Cursor, Windsurf, GitHub Copilot, Cline, and 13 more) via skill files, MCP tools, hooks, or rules
+- **Agent-Friendly**: Works seamlessly with 19 AI coding agents (Claude Code, Cursor, Windsurf, GitHub Copilot, Cline, and more) via skill files, MCP tools, hooks, or rules
 - **Cloud Sync**: Push and sync your context tree to ByteRover's cloud storage for backup and team collaboration
 - **Dynamic Domains**: Automatically creates new domains as your knowledge grows
 
@@ -167,13 +176,16 @@ The context tree organizes knowledge into:
 
 ## Supported AI Agents
 
-ByteRover integrates with 18 AI coding agents:
+ByteRover integrates with 19 AI coding agents:
 
 **Skill Connector (Default):**
 - Claude Code, Cursor
 
 **MCP Connector (Default):**
-- Amp, Augment Code, Cline, Gemini CLI, Github Copilot, Junie, Kilo Code, Kiro, Qoder, Qwen Code, Roo Code, Trae.ai, Warp, Windsurf, Zed (and Codex via global scope)
+- Amp, Augment Code, Cline, Codex, Gemini CLI, Github Copilot, Junie, Kilo Code, Kiro, Qoder, Qwen Code, Roo Code, Trae.ai, Warp, Windsurf, Zed
+
+**Rules Connector (Default):**
+- Antigravity (rules-only integration)
 
 **All agents support rules-based integration as a universal fallback option.**
 
@@ -190,15 +202,58 @@ Use `/connectors` to manage integrations with your AI coding agents:
 ByteRover supports four connector types:
 
 1. **Skill integration** (Claude Code, Cursor - default): Modern integration that writes 3 markdown files (SKILL.md, TROUBLESHOOTING.md, WORKFLOWS.md) to your agent's skills directory for easy discovery and guidance
-2. **MCP integration** (16 other agents - default): Exposes brv-query and brv-curate as Model Context Protocol tools that AI agents can call directly
+2. **MCP integration** (16 agents - default): Exposes brv-query and brv-curate as Model Context Protocol tools that AI agents can call directly
 3. **Rules-based** (all agents): Generates agent-specific rule files (e.g., CLAUDE.md, .cursorrules) with instructions for using ByteRover
 4. **Hook integration** (Claude Code only - legacy): Direct injection via IDE settings, replaced by skill connector
 
 **Defaults by agent:**
 - Claude Code, Cursor: Skill connector
+- Antigravity: Rules connector (only supported type)
 - All others (16 agents): MCP connector
 - Rules: Available for all agents as fallback
 
+## LLM Providers (BETA)
+
+ByteRover uses LLMs internally to power `/curate` and `/query` operations. By default, the built-in ByteRover provider is used with no configuration required. You can optionally connect to OpenRouter to access 200+ models.
+
+### Available Providers
+
+| Provider | API Key Required | Models |
+|----------|-----------------|--------|
+| **ByteRover** (default) | No | Built-in internal model |
+| **OpenRouter** | Yes | 200+ models from Anthropic, OpenAI, Google, Meta, and more |
+
+### Connecting a Provider
+
+Use `/provider` (aliases: `/providers`, `/connect`) to switch providers:
+
+```
+/provider
+```
+
+This opens an interactive prompt showing all available providers with their connection status.
+
+### Selecting a Model
+
+When connected to OpenRouter, use `/model` (alias: `/models`) to browse and select models:
+
+```
+/model
+```
+
+The model browser shows:
+- **Pricing**: Input/output cost per million tokens (e.g., `$3.00/$15.00/M`)
+- **Context window**: Maximum token capacity (e.g., `200K ctx`)
+- **Free models**: Marked with `[Free]`
+- **Favorites and recents**: Starred and recently used models appear first
+
+### OpenRouter Setup
+
+1. Get an API key at [openrouter.ai/keys](https://openrouter.ai/keys)
+2. Run `/provider` and select **OpenRouter**
+3. Paste your API key when prompted (stored securely in system keychain)
+4. Run `/model` to select a model (default: `anthropic/claude-3.5-sonnet`)
+
 ## Slash Commands Reference
 
 ### Core Workflow
@@ -269,11 +324,21 @@ ByteRover supports four connector types:
 
 **Defaults:**
 - Claude Code, Cursor: `skill`
+- Antigravity: `rules` (only supported type)
 - All others: `mcp`
 
 **Reset options:**
 - `-y, --yes`: Skip confirmation prompt
 
+### LLM Providers (BETA)
+
+| Command | Description |
+|---------|-------------|
+| `/provider` | Connect to and switch between LLM providers |
+| `/model` | Select a model from the active provider (OpenRouter) |
+
+**Aliases:** `/providers` and `/connect` for `/provider`; `/models` for `/model`
+
 ### Session Management
 
 | Command | Description |

package/dist/core/domain/cipher/errors/file-system-error.d.ts

@@ -210,3 +210,14 @@ export declare class TooManyResultsError extends FileSystemError {
      */
     constructor(operation: string, count: number, maxResults: number);
 }
+/**
+ * Error thrown when PDF text extraction fails.
+ */
+export declare class PdfExtractionError extends FileSystemError {
+    /**
+     * Creates a new PDF extraction error
+     * @param path - Path to the PDF file
+     * @param reason - Reason for the extraction failure
+     */
+    constructor(path: string, reason: string);
+}

package/dist/core/domain/cipher/errors/file-system-error.js

@@ -290,3 +290,20 @@ export class TooManyResultsError extends FileSystemError {
         this.name = 'TooManyResultsError';
     }
 }
+/**
+ * Error thrown when PDF text extraction fails.
+ */
+export class PdfExtractionError extends FileSystemError {
+    /**
+     * Creates a new PDF extraction error
+     * @param path - Path to the PDF file
+     * @param reason - Reason for the extraction failure
+     */
+    constructor(path, reason) {
+        super(`Failed to extract text from PDF: ${path}. ${reason}`, 'PDF_EXTRACTION_FAILED', {
+            path,
+            reason,
+        });
+        this.name = 'PdfExtractionError';
+    }
+}

package/dist/core/domain/cipher/file-system/types.d.ts

@@ -18,16 +18,46 @@ export interface FileSystemConfig {
     /** Working directory for relative path resolution */
     workingDirectory: string;
 }
+/**
+ * PDF read mode for controlling how PDF files are returned.
+ * - 'text': Extract text content page by page (default)
+ * - 'base64': Return raw PDF as base64 attachment (for multimodal LLMs)
+ */
+export type PdfReadMode = 'base64' | 'text';
+/**
+ * Metadata extracted from a PDF file.
+ */
+export interface PdfMetadata {
+    /** Author of the PDF (if available) */
+    author?: string;
+    /** Creation date of the PDF (if available) */
+    creationDate?: Date;
+    /** Total number of pages in the PDF */
+    pageCount: number;
+    /** Title of the PDF (if available) */
+    title?: string;
+}
+/**
+ * Content extracted from a single PDF page.
+ */
+export interface PdfPageContent {
+    /** 1-based page number */
+    pageNumber: number;
+    /** Extracted text content from the page */
+    text: string;
+}
 /**
  * Options for reading files.
  */
 export interface ReadFileOptions {
     /** Character encoding */
     encoding?: BufferEncoding;
-    /** Maximum number of lines to read */
+    /** Maximum number of lines to read (for text files) or pages (for PDFs in text mode) */
     limit?: number;
-    /** Starting line number (1-based, like text editors) */
+    /** Starting line number (1-based) for text files, or starting page number for PDFs */
     offset?: number;
+    /** PDF read mode: 'text' (default) extracts text, 'base64' returns raw attachment */
+    pdfMode?: PdfReadMode;
 }
 /**
  * Options for writing files.
@@ -126,23 +156,27 @@ export interface FileAttachment {
  * Result of a file read operation.
  */
 export interface FileContent {
-    /** Attachment data for binary files (images, PDFs) */
+    /** Attachment data for binary files (images, PDFs in base64 mode) */
     attachment?: FileAttachment;
     /** File content as string */
     content: string;
     /** Character encoding used */
     encoding: string;
-    /** Formatted content with line numbers (00001| content format) */
+    /** Formatted content with line numbers (00001| content format) or PDF page separators */
     formattedContent: string;
-    /** Total number of lines in the returned content */
+    /** Total number of lines in the returned content (or pages for PDF text mode) */
     lines: number;
     /** Human-readable message about file status (truncation info, etc.) */
     message: string;
+    /** PDF metadata when reading PDF in text mode */
+    pdfMetadata?: PdfMetadata;
+    /** PDF page contents when reading PDF in text mode */
+    pdfPages?: PdfPageContent[];
     /** Preview of content (first 20 lines) for UI display */
     preview?: string;
     /** File size in bytes */
     size: number;
-    /** Total lines in the entire file */
+    /** Total lines in the entire file (or total pages for PDF text mode) */
     totalLines: number;
     /** Whether content was truncated due to size/line limits */
     truncated: boolean;

package/dist/core/domain/cipher/process/types.d.ts

@@ -82,7 +82,7 @@ export interface ExecuteOptions {
     /**
      * Timeout in milliseconds (max: ProcessConfig.maxTimeout).
      *
-     * @default 120000 (2 minutes)
+     * @default 300000 (5 minutes)
      */
     timeout?: number;
 }

package/dist/core/domain/entities/agent.d.ts

@@ -2,7 +2,7 @@ import type { ConnectorType } from './connector-type.js';
 /**
  * Array of all supported Agents.
  */
-export declare const AGENT_VALUES: readonly ["Amp", "Augment Code", "Claude Code", "Cline", "Codex", "Cursor", "Gemini CLI", "Github Copilot", "Junie", "Kilo Code", "Kiro", "Qoder", "Qwen Code", "Roo Code", "Trae.ai", "Warp", "Windsurf", "Zed"];
+export declare const AGENT_VALUES: readonly ["Amp", "Antigravity", "Augment Code", "Claude Code", "Cline", "Codex", "Cursor", "Gemini CLI", "Github Copilot", "Junie", "Kilo Code", "Kiro", "Qoder", "Qwen Code", "Roo Code", "Trae.ai", "Warp", "Windsurf", "Zed"];
 export type Agent = (typeof AGENT_VALUES)[number];
 /**
  * Connector availability configuration for an agent.

package/dist/core/domain/entities/agent.js

@@ -3,6 +3,7 @@
  */
 export const AGENT_VALUES = [
     'Amp',
+    'Antigravity',
     'Augment Code',
     'Claude Code',
     'Cline',
@@ -30,6 +31,10 @@ export const AGENT_CONNECTOR_CONFIG = {
         default: 'mcp',
         supported: ['rules', 'mcp'],
     },
+    Antigravity: {
+        default: 'rules',
+        supported: ['rules'],
+    },
     'Augment Code': {
         default: 'mcp',
         supported: ['rules', 'mcp'],

package/dist/core/domain/entities/provider-config.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Provider Configuration Entity
+ *
+ * Stores user's provider preferences and connection state.
+ * Non-sensitive data (API keys stored separately in keychain).
+ */
+/**
+ * Configuration for a single connected provider.
+ */
+export interface ConnectedProviderConfig {
+    /** Currently active model for this provider */
+    readonly activeModel?: string;
+    /** When the provider was connected */
+    readonly connectedAt: string;
+    /** User's favorite models (for quick access) */
+    readonly favoriteModels: readonly string[];
+    /** Recently used models (last 10) */
+    readonly recentModels: readonly string[];
+}
+/**
+ * Parameters for creating a ProviderConfig.
+ */
+export interface ProviderConfigParams {
+    /** Currently active provider ID */
+    readonly activeProvider: string;
+    /** Configuration for each connected provider */
+    readonly providers: Readonly<Record<string, ConnectedProviderConfig>>;
+}
+/**
+ * Default configuration when no providers are connected.
+ */
+export declare const DEFAULT_PROVIDER_CONFIG: ProviderConfigParams;
+/**
+ * Represents the provider configuration for the CLI.
+ * Tracks which providers are connected and user preferences.
+ */
+export declare class ProviderConfig {
+    readonly activeProvider: string;
+    readonly providers: Readonly<Record<string, ConnectedProviderConfig>>;
+    private constructor();
+    /**
+     * Creates a new ProviderConfig with default values.
+     */
+    static createDefault(): ProviderConfig;
+    /**
+     * Deserializes config from JSON format.
+     * Returns default config for invalid JSON structure.
+     */
+    static fromJson(json: unknown): ProviderConfig;
+    /**
+     * Get the active model for a provider.
+     */
+    getActiveModel(providerId: string): string | undefined;
+    /**
+     * Get favorite models for a provider.
+     */
+    getFavoriteModels(providerId: string): readonly string[];
+    /**
+     * Get recent models for a provider.
+     */
+    getRecentModels(providerId: string): readonly string[];
+    /**
+     * Check if a provider is connected.
+     */
+    isProviderConnected(providerId: string): boolean;
+    /**
+     * Serializes the config to JSON format.
+     */
+    toJson(): ProviderConfigParams;
+    /**
+     * Create a new config with the active model changed for a provider.
+     */
+    withActiveModel(providerId: string, modelId: string): ProviderConfig;
+    /**
+     * Create a new config with the active provider changed.
+     */
+    withActiveProvider(providerId: string): ProviderConfig;
+    /**
+     * Create a new config with a model toggled as favorite.
+     */
+    withFavoriteToggled(providerId: string, modelId: string): ProviderConfig;
+    /**
+     * Create a new config with a provider connected.
+     */
+    withProviderConnected(providerId: string, options?: {
+        activeModel?: string;
+    }): ProviderConfig;
+    /**
+     * Create a new config with a provider disconnected.
+     */
+    withProviderDisconnected(providerId: string): ProviderConfig;
+}

package/dist/core/domain/entities/provider-config.js

@@ -0,0 +1,181 @@
+/**
+ * Provider Configuration Entity
+ *
+ * Stores user's provider preferences and connection state.
+ * Non-sensitive data (API keys stored separately in keychain).
+ */
+/**
+ * Type guard for ProviderConfig JSON validation.
+ */
+const isProviderConfigJson = (json) => {
+    if (typeof json !== 'object' || json === null)
+        return false;
+    const obj = json;
+    if (typeof obj.activeProvider !== 'string')
+        return false;
+    if (typeof obj.providers !== 'object' || obj.providers === null)
+        return false;
+    return true;
+};
+/**
+ * Default configuration when no providers are connected.
+ */
+export const DEFAULT_PROVIDER_CONFIG = {
+    activeProvider: 'byterover',
+    providers: {},
+};
+/**
+ * Maximum number of recent models to track.
+ */
+const MAX_RECENT_MODELS = 10;
+/**
+ * Represents the provider configuration for the CLI.
+ * Tracks which providers are connected and user preferences.
+ */
+export class ProviderConfig {
+    activeProvider;
+    providers;
+    constructor(params) {
+        this.activeProvider = params.activeProvider;
+        this.providers = params.providers;
+    }
+    /**
+     * Creates a new ProviderConfig with default values.
+     */
+    static createDefault() {
+        return new ProviderConfig(DEFAULT_PROVIDER_CONFIG);
+    }
+    /**
+     * Deserializes config from JSON format.
+     * Returns default config for invalid JSON structure.
+     */
+    static fromJson(json) {
+        if (!isProviderConfigJson(json)) {
+            return ProviderConfig.createDefault();
+        }
+        return new ProviderConfig(json);
+    }
+    /**
+     * Get the active model for a provider.
+     */
+    getActiveModel(providerId) {
+        return this.providers[providerId]?.activeModel;
+    }
+    /**
+     * Get favorite models for a provider.
+     */
+    getFavoriteModels(providerId) {
+        return this.providers[providerId]?.favoriteModels ?? [];
+    }
+    /**
+     * Get recent models for a provider.
+     */
+    getRecentModels(providerId) {
+        return this.providers[providerId]?.recentModels ?? [];
+    }
+    /**
+     * Check if a provider is connected.
+     */
+    isProviderConnected(providerId) {
+        return providerId in this.providers;
+    }
+    /**
+     * Serializes the config to JSON format.
+     */
+    toJson() {
+        return {
+            activeProvider: this.activeProvider,
+            providers: this.providers,
+        };
+    }
+    /**
+     * Create a new config with the active model changed for a provider.
+     */
+    withActiveModel(providerId, modelId) {
+        const existingConfig = this.providers[providerId];
+        if (!existingConfig) {
+            return this;
+        }
+        // Add to recent models (at the front, deduplicated)
+        const recentModels = [
+            modelId,
+            ...existingConfig.recentModels.filter((m) => m !== modelId),
+        ].slice(0, MAX_RECENT_MODELS);
+        const newProviderConfig = {
+            ...existingConfig,
+            activeModel: modelId,
+            recentModels,
+        };
+        return new ProviderConfig({
+            ...this.toJson(),
+            providers: {
+                ...this.providers,
+                [providerId]: newProviderConfig,
+            },
+        });
+    }
+    /**
+     * Create a new config with the active provider changed.
+     */
+    withActiveProvider(providerId) {
+        return new ProviderConfig({
+            ...this.toJson(),
+            activeProvider: providerId,
+        });
+    }
+    /**
+     * Create a new config with a model toggled as favorite.
+     */
+    withFavoriteToggled(providerId, modelId) {
+        const existingConfig = this.providers[providerId];
+        if (!existingConfig) {
+            return this;
+        }
+        const isFavorite = existingConfig.favoriteModels.includes(modelId);
+        const favoriteModels = isFavorite
+            ? existingConfig.favoriteModels.filter((m) => m !== modelId)
+            : [...existingConfig.favoriteModels, modelId];
+        const newProviderConfig = {
+            ...existingConfig,
+            favoriteModels,
+        };
+        return new ProviderConfig({
+            ...this.toJson(),
+            providers: {
+                ...this.providers,
+                [providerId]: newProviderConfig,
+            },
+        });
+    }
+    /**
+     * Create a new config with a provider connected.
+     */
+    withProviderConnected(providerId, options) {
+        const existingConfig = this.providers[providerId];
+        const newProviderConfig = {
+            activeModel: options?.activeModel ?? existingConfig?.activeModel,
+            connectedAt: existingConfig?.connectedAt ?? new Date().toISOString(),
+            favoriteModels: existingConfig?.favoriteModels ?? [],
+            recentModels: existingConfig?.recentModels ?? [],
+        };
+        return new ProviderConfig({
+            ...this.toJson(),
+            providers: {
+                ...this.providers,
+                [providerId]: newProviderConfig,
+            },
+        });
+    }
+    /**
+     * Create a new config with a provider disconnected.
+     */
+    withProviderDisconnected(providerId) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { [providerId]: _removed, ...remainingProviders } = this.providers;
+        const newActiveProvider = this.activeProvider === providerId ? 'byterover' : this.activeProvider;
+        return new ProviderConfig({
+            activeProvider: newActiveProvider,
+            providers: remainingProviders,
+        });
+    }
+}

package/dist/core/domain/entities/provider-registry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Provider Registry
+ *
+ * Defines available LLM providers that can be connected to byterover-cli.
+ * Inspired by OpenCode's provider system.
+ */
+/**
+ * Definition for an LLM provider.
+ */
+export interface ProviderDefinition {
+    /** URL where users can get an API key */
+    readonly apiKeyUrl?: string;
+    /** API base URL (empty for internal providers) */
+    readonly baseUrl: string;
+    /** Category for grouping in UI */
+    readonly category: 'other' | 'popular';
+    /** Default model to use when first connected */
+    readonly defaultModel?: string;
+    /** Short description */
+    readonly description: string;
+    /** Default headers for API requests */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Unique provider identifier */
+    readonly id: string;
+    /** Endpoint to fetch available models */
+    readonly modelsEndpoint: string;
+    /** Display name */
+    readonly name: string;
+    /** Priority for display order (lower = higher priority) */
+    readonly priority: number;
+}
+/**
+ * Registry of all available providers.
+ * Order by priority for consistent display.
+ */
+export declare const PROVIDER_REGISTRY: Readonly<Record<string, ProviderDefinition>>;
+/**
+ * Get all providers sorted by priority.
+ */
+export declare function getProvidersSortedByPriority(): ProviderDefinition[];
+/**
+ * Get providers grouped by category.
+ */
+export declare function getProvidersGroupedByCategory(): {
+    other: ProviderDefinition[];
+    popular: ProviderDefinition[];
+};
+/**
+ * Get a provider by ID.
+ */
+export declare function getProviderById(id: string): ProviderDefinition | undefined;
+/**
+ * Check if a provider requires an API key.
+ */
+export declare function providerRequiresApiKey(id: string): boolean;