@zds-ai/cli 0.1.7 → 0.1.10

package/README.md

@@ -1,12 +1,12 @@
-# ZDS AI CLI (forked from Grok CLI)
+# ZDS AI CLI
 
-A conversational AI CLI tool powered by Grok with intelligent text editor capabilities and tool usage.
+A multi-backend conversational AI CLI tool with intelligent text editor capabilities and tool usage.  Supports OpenAI, Anthropic Claude, X.AI Grok, Ollama, and other OpenAI-compatible providers.
 
 <img width="720" height="528" alt="Image" src="https://github.com/user-attachments/assets/f697a273-141e-4f02-8c15-37143aa7ec0e" />
 
 ## Features
 
-- **🤖 Conversational AI**: Natural language interface powered by grok, others
+- **⚡ Multi-Backend Support**: Works with OpenAI, Anthropic Claude, X.AI Grok, Ollama, OpenRouter, and any OpenAI-compatible API
 - **📝 Smart File Operations**: AI automatically uses tools to view, create, and edit files
 - **⚡ Zsh Integration**: Execute shell commands through natural conversation
 - **🔧 Automatic Tool Selection**: AI intelligently chooses the right tools for your requests
@@ -18,8 +18,14 @@ A conversational AI CLI tool powered by Grok with intelligent text editor capabi
 ## Installation
 
 ### Prerequisites
+
 - Bun 1.0+ (or Node.js 18+ as fallback)
-- GROK API key from X.AI
+- API key from your chosen provider:
+  - X.AI Grok: Get from [X.AI](https://x.ai)
+  - OpenAI: Get from [OpenAI Platform](https://platform.openai.com)
+  - Anthropic Claude: Get from [Anthropic Console](https://console.anthropic.com)
+  - Ollama: Self-hosted (no API key needed) or Ollama Cloud (get from [Ollama Cloud](https://ollama.com))
+  - OpenRouter: Get from [OpenRouter](https://openrouter.ai)
 - (Optional, Recommended) Morph API key for Fast Apply editing
 
 ### System Dependencies
@@ -46,12 +52,14 @@ zai-cli requires the following system tools for certain features:
 
 ```sh
 bun add -g @zds-ai/cli
+
 ```
 
 Or with npm (fallback):
 
 ```sh
 npm install -g @zds-ai/cli
+
 ```
 
 ### Local Development
@@ -62,58 +70,108 @@ cd zds-ai-cli
 bun install
 bun run build
 bun link
+
 ```
 
 ## Setup
 
-1. Get your GROK API key from [X.AI](https://x.ai)
+### Quick Start with X.AI Grok (Default)
+
+> **Note**: Environment variables use `GROK_*` prefixes (legacy naming from the original fork), but they work with **all backends**, not just Grok.  See "[Using Other Providers](#using-other-providers)" below to configure different backends.
+
+> **Important**: As of December 15, 2025, Grok's `search_parameters` API has been deprecated.  zai-cli now uses the new Agent Tools API for web search functionality.  Old code using `search_parameters` is automatically converted to the new format for backward compatibility.  See [Grok's Agent Tools documentation](https://docs.x.ai/docs/guides/tools/search-tools) for details.
+
+1.  Get your API key from [X.AI](https://x.ai)
+
+2.  Set up your API key (choose one method):
 
-2. Set up your API key (choose one method):
-    
     **Method 1: Environment Variable**
-    
+
     ```sh
     export GROK_API_KEY=your_api_key_here
+
     ```
-    
+
     **Method 2: .env File**
-    
+
     ```sh
     cp .env.example .env
+
     # Edit .env and add your API key
+
+
     ```
-    
+
     **Method 3: Command Line Flag**
-    
+
     ```sh
     zai-cli --api-key your_api_key_here
+
     ```
-    
+
     **Method 4: User Settings File**
-    
-    Create `~/.grok/user-settings.json`:
-    
+
+    Create `~/.zds-ai/cli-settings.json`:
+
     ```json
     {
       "apiKey": "your_api_key_here"
     }
+
     ```
 
+### Using Other Providers
+
+zai-cli supports any OpenAI-compatible API.  Set your provider's API key and base URL:
+
+**OpenAI:**
+
+```sh
+export GROK_API_KEY=your_openai_key
+export GROK_BASE_URL=https://api.openai.com/v1
+export GROK_MODEL=gpt-4o
+
+```
+
+**Ollama (Local):**
+
+```sh
+export GROK_BASE_URL=http://localhost:11434/v1
+export GROK_MODEL=llama3
+
+# No API key needed for local Ollama
+
+
+```
+
+**OpenRouter:**
+
+```sh
+export GROK_API_KEY=your_openrouter_key
+export GROK_BASE_URL=https://openrouter.ai/api/v1
+export GROK_MODEL=anthropic/claude-4.5-sonnet
+
+```
+
 3. (Optional, Recommended) Get your Morph API key from [Morph Dashboard](https://morphllm.com/dashboard/api-keys)
 
-4. Set up your Morph API key for Fast Apply editing (choose one method):
+4.  Set up your Morph API key for Fast Apply editing (choose one method):
 
     **Method 1: Environment Variable**
     
     ```sh
     export MORPH_API_KEY=your_morph_api_key_here
+
     ```
     
     **Method 2: .env File**
     
     ```sh
+
     # Add to your .env file
+
     MORPH_API_KEY=your_morph_api_key_here
+
     ```
 
 ### Custom Base URL (Optional)
@@ -124,35 +182,38 @@ By default, the CLI uses `https://api.x.ai/v1` as the API endpoint.  You can con
 
 ```sh
 export GROK_BASE_URL=https://your-custom-endpoint.com/v1
+
 ```
 
 **Method 2: Command Line Flag**
 
 ```sh
 zai-cli --api-key your_api_key_here --base-url https://your-custom-endpoint.com/v1
+
 ```
 
 **Method 3: User Settings File**
 
-Add to `~/.grok/user-settings.json`:
+Add to `~/.zds-ai/cli-settings.json`:
 
 ```json
 {
   "apiKey": "your_api_key_here",
   "baseURL": "https://your-custom-endpoint.com/v1"
 }
+
 ```
 
 ## Configuration Files
 
 zai-cli uses two types of configuration files to manage settings:
 
-### User-Level Settings (`~/.grok/user-settings.json`)
+### User-Level Settings (`~/.zds-ai/cli-settings.json`)
 
-This file stores **global settings** that apply across all projects. These settings rarely change and include:
+This file stores **global settings** that apply across all projects.  These settings rarely change and include:
 
-- **API Key**: Your GROK API key
-- **Base URL**: Custom API endpoint (if needed)
+- **API Key**: Your API key (works with any backend)
+- **Base URL**: API endpoint (determines which backend you use)
 - **Default Model**: Your preferred model (e.g., `grok-code-fast-1`)
 - **Available Models**: List of models you can use
 
@@ -172,6 +233,7 @@ This file stores **global settings** that apply across all projects. These setti
   ],
   "startupHook": "date"
 }
+
 ```
 
 #### Startup Hook
@@ -181,15 +243,13 @@ You can configure a **startup hook** command that runs when zai-cli starts.  The
 **Example use cases:**
 
 - Show current date/time: `"startupHook": "date"`
-- Display git status: `"startupHook": "git status --short"`
-- Show active branches: `"startupHook": "git branch --show-current"`
 - Custom environment info: `"startupHook": "/path/to/your/script.sh"`
 
 The command runs with a 10-second timeout and the output appears in the AI's context before custom instructions.
 
-### Project-Level Settings (`.grok/settings.json`)
+### Project-Level Settings (`.zds-ai/project-settings.json`)
 
-This file stores **project-specific settings** in your current working directory. It includes:
+This file stores **project-specific settings** in your current working directory.  It includes:
 
 - **Current Model**: The model currently in use for this project
 - **MCP Servers**: Model Context Protocol server configurations
@@ -208,6 +268,7 @@ This file stores **project-specific settings** in your current working directory
     }
   }
 }
+
 ```
 
 ### How It Works
@@ -221,7 +282,7 @@ This means you can have different models for different projects while maintainin
 
 ### Using Other API Providers
 
-**Important**: zai-cli uses **OpenAI-compatible APIs**. You can use any provider that implements the OpenAI chat completions standard.
+**Important**: zai-cli uses **OpenAI-compatible APIs**.  You can use any provider that implements the OpenAI chat completions standard.
 
 **Popular Providers**:
 
@@ -243,6 +304,7 @@ This means you can have different models for different projects while maintainin
     "meta-llama/llama-3.1-70b-instruct"
   ]
 }
+
 ```
 
 ## Usage
@@ -253,12 +315,14 @@ Start the conversational AI assistant:
 
 ```sh
 zai-cli
+
 ```
 
 Or specify a working directory:
 
 ```sh
 zai-cli -d /path/to/project
+
 ```
 
 ### Headless Mode
@@ -270,6 +334,7 @@ zai-cli --prompt "show me the package.json file"
 zai-cli -p "create a new file called example.js with a hello world function"
 zai-cli --prompt "run bun test and show me the results" --directory /path/to/project
 zai-cli --prompt "complex task" --max-tool-rounds 50  # Limit tool usage for faster execution
+
 ```
 
 This mode is particularly useful for:
@@ -281,18 +346,22 @@ This mode is particularly useful for:
 
 ### Tool Execution Control
 
-By default, zai-cli allows up to 400 tool execution rounds to handle complex multi-step tasks. You can control this behavior:
+By default, zai-cli allows up to 400 tool execution rounds to handle complex multi-step tasks.  You can control this behavior:
 
 ```sh
+
 # Limit tool rounds for faster execution on simple tasks
+
 zai-cli --max-tool-rounds 10 --prompt "show me the current directory"
 
 # Increase limit for very complex tasks (use with caution)
+
 zai-cli --max-tool-rounds 1000 --prompt "comprehensive code refactoring"
 
 # Works with all modes
+
 zai-cli --max-tool-rounds 20  # Interactive mode
-zai-cli git commit-and-push --max-tool-rounds 30  # Git commands
+
 ```
 
 **Use Cases**:
@@ -308,15 +377,19 @@ You can specify which AI model to use with the `--model` parameter or `GROK_MODE
 **Method 1: Command Line Flag**
 
 ```sh
+
 # Use grok models
+
 zai-cli --model grok-code-fast-1
 zai-cli --model grok-4-latest
 zai-cli --model grok-3-latest
 zai-cli --model grok-3-fast
 
 # Use other models (with appropriate API endpoint)
+
 zai-cli --model gemini-2.5-pro --base-url https://api-endpoint.com/v1
 zai-cli --model claude-sonnet-4-20250514 --base-url https://api-endpoint.com/v1
+
 ```
 
 **Method 2: Environment Variable**
@@ -324,17 +397,19 @@ zai-cli --model claude-sonnet-4-20250514 --base-url https://api-endpoint.com/v1
 ```sh
 export GROK_MODEL=grok-code-fast-1
 zai-cli
+
 ```
 
 **Method 3: User Settings File**
 
-Add to `~/.grok/user-settings.json`:
+Add to `~/.zds-ai/cli-settings.json`:
 
 ```json
 {
   "apiKey": "your_api_key_here",
   "defaultModel": "grok-code-fast-1"
 }
+
 ```
 
 **Model Priority**: `--model` flag > `GROK_MODEL` environment variable > user default model > system default (grok-code-fast-1)
@@ -344,20 +419,27 @@ Add to `~/.grok/user-settings.json`:
 zai-cli supports sending images to vision-capable AI models.  Use the `@` prefix to reference image files in your messages:
 
 ```sh
+
 # Absolute path
+
 zai-cli --prompt "What's in this image? @/Users/joseph/photos/image.jpg"
 
 # Relative path
+
 zai-cli --prompt "Analyze @./screenshot.png"
 
 # Tilde expansion
+
 zai-cli --prompt "Describe @~/Pictures/photo.jpg"
 
 # Paths with spaces (quoted)
+
 zai-cli --prompt 'Compare these images: @"~/My Pictures/photo1.jpg" @"~/My Pictures/photo2.jpg"'
 
 # Paths with spaces (escaped)
+
 zai-cli --prompt "What's here? @/Users/joseph/My\ Documents/image.png"
+
 ```
 
 **Supported Image Formats**: .jpg, .jpeg, .png, .gif, .webp, .bmp
@@ -379,30 +461,33 @@ zai-cli [options]
 Options:
   -V, --version                       output the version number
   -d, --directory <dir>               set working directory
-  -k, --api-key <key>                 Grok API key (or set GROK_API_KEY env var)
+  -k, --api-key <key>                 API key for your backend (or set GROK_API_KEY env var -- works with all backends)
   -b, --backend <name>                Backend display name (e.g., grok, openai, claude)
   -u, --base-url <url>                API base URL (or set GROK_BASE_URL env var)
   -m, --model <model>                 AI model to use (e.g., grok-code-fast-1, grok-4-latest) (or set GROK_MODEL env
                                       var)
   -t, --temperature <temp>            temperature for API requests (0.0-2.0, default: 0.7) (default: "0.7")
   --max-tokens <tokens>               maximum tokens for API responses (positive integer, no default = API default)
-  -p, --prompt [prompt]               process a single prompt and exit (headless mode). If no prompt provided, reads
+  -p, --prompt [prompt]               process a single prompt and exit (headless mode).  If no prompt provided, reads
                                       from stdin
   --max-tool-rounds <rounds>          maximum number of tool execution rounds (default: 400) (default: "400")
   --fresh                             start with a fresh session (don't load previous chat history)
   --auto-approve                      auto-approve all operations without confirmation prompts
   --auto-approve-commands <commands>  comma-separated list of commands to auto-approve (e.g.,
                                       'chdir,list_files,pwd')
-  -c, --context <file>                path to context persistence file (default: ~/.grok/chat-history.json)
+  -c, --context <file>                path to context persistence file (default: ~/.zds-ai/context.json)
   --no-ink                            disable Ink UI and use plain console input/output
   --debug-log <file>                  redirect MCP server debug output to log file instead of suppressing
   --show-all-tools                    list all available tools (internal and MCP) and exit
   --show-context-stats                display token usage stats for the specified context file and exit
   -h, --help                          display help for command
+
 ```
 
 ### Custom Instructions
 
+> **Note**: Custom instructions still use the legacy `.grok/` directory paths (not `.zds-ai/`).  This is for backwards compatibility with the original fork.
+
 You can provide custom instructions to tailor zai-cli's behavior by creating `GROK.md` files in two locations:
 
 - **Global instructions** (apply to all projects): `~/.grok/GROK.md`
@@ -414,11 +499,13 @@ To create project-specific instructions:
 
 ```sh
 mkdir .grok
+
 ```
 
 Create `.grok/GROK.md` with your custom instructions:
 
 ```markdown
+
 # Custom Instructions for zai-cli
 
 - Always use TypeScript for any new code files.
@@ -426,13 +513,14 @@ Create `.grok/GROK.md` with your custom instructions:
 - Prefer const assertions and explicit typing over inference where it improves clarity.
 - Always add JSDoc comments for public functions and interfaces.
 - Follow the existing code style and patterns in this project.
+
 ```
 
 zai-cli will automatically load and follow these instructions when working in your project directory.  The custom instructions are added to zai-cli's system prompt and take priority over default behavior.
 
 ## Morph Fast Apply (Optional)
 
-zai-cli supports Morph's Fast Apply model for high-speed code editing at **4,500+ tokens/sec with 98% accuracy**. This is an optional feature that provides lightning-fast file editing capabilities.
+zai-cli supports Morph's Fast Apply model for high-speed code editing at **4,500+ tokens/sec with 98% accuracy**.  This is an optional feature that provides lightning-fast file editing capabilities.
 
 **Setup**: Configure your Morph API key following the [setup instructions](#setup) above.
 
@@ -455,6 +543,7 @@ With Morph Fast Apply configured, you can request complex code changes:
 ```sh
 zai-cli --prompt "refactor this function to use async/await and add error handling"
 zai-cli -p "convert this class to TypeScript and add proper type annotations"
+
 ```
 
 The AI will automatically choose between `edit_file` (Morph) for complex changes or `str_replace_editor` for simple replacements.
@@ -468,20 +557,26 @@ zai-cli supports MCP (Model Context Protocol) servers, allowing you to extend th
 #### Add a custom MCP server:
 
 ```sh
+
 # Add an stdio-based MCP server
+
 zai-cli mcp add my-server --transport stdio --command "bun" --args server.js
 
 # Add an HTTP-based MCP server
+
 zai-cli mcp add my-server --transport http --url "http://localhost:3000"
 
 # Add with environment variables
+
 zai-cli mcp add my-server --transport stdio --command "python" --args "-m" "my_mcp_server" --env "API_KEY=your_key"
+
 ```
 
 #### Add from JSON configuration:
 
 ```sh
 zai-cli mcp add-json my-server '{"command": "bun", "args": ["server.js"], "env": {"API_KEY": "your_key"}}'
+
 ```
 
 ### Linear Integration Example
@@ -489,8 +584,11 @@ zai-cli mcp add-json my-server '{"command": "bun", "args": ["server.js"], "env":
 To add Linear MCP tools for project management:
 
 ```sh
+
 # Add Linear MCP server
+
 zai-cli mcp add linear --transport sse --url "https://mcp.linear.app/sse"
+
 ```
 
 This enables Linear tools like:
@@ -502,14 +600,19 @@ This enables Linear tools like:
 ### Managing MCP Servers
 
 ```sh
+
 # List all configured servers
+
 zai-cli mcp list
 
 # Test server connection
+
 zai-cli mcp test server-name
 
 # Remove a server
+
 zai-cli mcp remove server-name
+
 ```
 
 ### Available Transport Types
@@ -518,23 +621,273 @@ zai-cli mcp remove server-name
 - **http**: Connect to HTTP-based MCP server
 - **sse**: Connect via Server-Sent Events
 
+## Hooks System
+
+zai-cli includes a powerful hooks system for customizing behavior at various points in the execution lifecycle.  Hooks are shell commands that can modify context, set variables, or control execution flow.
+
+### Configuring Hooks
+
+Add hooks to `~/.zds-ai/cli-settings.json` or `.zds-ai/project-settings.json`:
+
+```json
+{
+  "startupHook": "echo 'Session started'",
+  "instanceHook": "/path/to/script.sh",
+  "personaHook": "validate-persona.sh",
+  "personaHookMandatory": true
+}
+
+```
+
+### Available Hooks
+
+**Lifecycle Hooks:**
+- `startupHook` - Runs at session start, output added to system prompt
+- `instanceHook` - Runs for every instance (new and resumed sessions)
+
+**Operation Hooks:**
+- `postUserInputHook` - Runs after user input received
+- `preLLMResponseHook` - Runs before prompt sent to LLM
+- `postLLMResponseHook` - Runs after LLM response
+- `preToolCallHook` - Runs before tool execution
+- `postToolCallHook` - Runs after tool execution
+
+**Validation Hooks:**
+- `taskApprovalHook` - Validates task operations (start/transition/stop)
+- `toolApprovalHook` - Validates tool execution before running
+- `personaHook` - Validates persona changes
+- `moodHook` - Validates mood changes
+
+**Context Helpers:**
+- `contextViewHelper` / `contextViewHelperGui` - Custom context viewing
+- `contextEditHelper` / `contextEditHelperGui` - Custom context editing
+
+### Hook Commands
+
+Hooks can output special commands to control the CLI:
+
+```sh
+
+# Set environment variables
+
+ENV VAR_NAME=value
+
+# Set prompt variables
+
+SET VAR:NAME=value
+SET_FILE VAR:NAME=/path/to/file
+
+# Add system messages
+
+SYSTEM This message appears in the system prompt
+
+# Test backend configurations (persona/mood hooks)
+
+TEST_BACKEND backend_name base_url model api_key_env_var
+
+# Model/backend selection
+
+MODEL model_name
+BACKEND backend_name
+BASE_URL https://api.example.com/v1
+API_KEY_ENV_VAR ENV_VAR_NAME
+
+```
+
+## Personas and Moods
+
+Customize the AI's behavior and context with personas and moods.
+
+### Using Personas
+
+```sh
+
+# Set persona
+
+/persona debugging red
+/persona architect blue
+
+# With hook validation (if personaHook configured)
+
+/persona production-review yellow
+
+```
+
+Personas can:
+- Change the AI's behavior and focus
+- Switch backends/models via hooks
+- Set environment variables
+- Add context to the system prompt
+
+### Using Moods
+
+```sh
+
+# Set mood
+
+/mood focused green
+/mood exploratory purple
+
+```
+
+Moods provide additional behavioral context without changing the fundamental persona.
+
+### Configuring Persona/Mood Hooks
+
+```json
+{
+  "personaHook": "persona-validator.sh",
+  "personaHookMandatory": true,
+  "moodHook": "mood-setter.sh",
+  "moodHookMandatory": false
+}
+
+```
+
+Hook validation can switch backends, set variables, or reject invalid personas/moods.
+
+## Active Tasks
+
+Track and manage active tasks with documentation support.
+
+### Task Commands
+
+```sh
+
+# Start a task
+
+/task start "Implement feature X" "designing" blue
+
+# Update task status
+
+/task status "implementing" yellow
+
+# Stop task and document
+
+/task stop "Feature complete" docs/feature-x.md green
+
+```
+
+### Task Tool Usage
+
+The AI can also manage tasks via tools:
+- `startActiveTask(name, action, color)` - Begin tracking a task
+- `transitionActiveTaskStatus(action, color)` - Update task status
+- `stopActiveTask(reason, documentationFile, color)` - Complete and document task
+
+Tasks persist across sessions and appear in the system prompt.
+
+## Session Persistence
+
+zai-cli automatically saves and restores session state between runs.
+
+### What Gets Saved
+
+- Chat history
+- Active persona and mood
+- Current task
+- Backend and model selection
+- Working directory
+- Prompt variables
+- System prompt
+
+### Session Management
+
+```sh
+
+# Start fresh session (ignore saved state)
+
+zai-cli --fresh
+
+# View current context
+
+/context
+
+# Edit context manually
+
+/context edit
+
+# Reload context from file
+
+/context reload
+
+# Compact context (keep last 20 messages)
+
+/compact
+
+```
+
+Context is automatically saved to `~/.zds-ai/context.json`
+
+## Slash Commands Reference
+
+### Help and Information
+
+- `/?` - Introspect tools and environment (alias for `/introspect`)
+- `/help` - Show command help
+- `/introspect` - List all available tools and environment info
+
+### History Management
+
+- `/clear` - Clear chat history (current session + persisted)
+- `/compact` - Reduce context size (keep last 20 messages)
+
+### Context Operations
+
+- `/context` - Show context usage info
+- `/context view` - View full context in pager (markdown format)
+- `/context edit` - Edit context JSON file (opens in $EDITOR)
+- `/context reload` - Reload context from file immediately
+
+### Model and Backend
+
+- `/models` - Interactive model selection menu
+- `/models <model>` - Switch to specific model directly
+
+### State Management
+
+- `/persona <text> [color]` - Set current persona
+- `/mood <text> [color]` - Set current mood
+
+### Response Control
+
+- `/rephrase [text]` - Request rephrasing of last response
+- `/system rephrase [text]` - Same as /rephrase but as system message
+
+### UI Control
+
+- `/ink` - Switch to Ink UI mode (restart required)
+- `/no-ink` - Switch to plain console mode (restart required)
+
+### Session Control
+
+- `/restart` - Restart the application (exit code 51)
+- `/exit` or `exit` or `quit` - Exit application
+
 ## Development
 
 ```sh
+
 # Install dependencies
+
 bun install
 
 # Development mode
+
 bun run dev
 
 # Build project
+
 bun run build
 
 # Run linter
+
 bun run lint
 
 # Type check
+
 bun run typecheck
+
 ```
 
 ## Architecture