grok-cli-hurry-mode 1.0.0

package/.grok/settings.json

@@ -0,0 +1,3 @@
+{
+  "model": "grok-code-fast-1"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [copyright holders]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission statement shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,452 @@
+# Grok CLI
+
+A conversational AI CLI tool powered by Grok with intelligent text editor capabilities and tool usage.
+
+<img width="980" height="435" alt="Grok CLI Logo with HURRY MODE and Version" src="https://github.com/hinetapora/grok-cli-hurry-mode/releases/download/v0.0.33/grok-logo-screenshot.png" />
+
+## Features
+
+- **🤖 Conversational AI**: Natural language interface powered by Grok-3
+- **📝 Smart File Operations**: AI automatically uses tools to view, create, and edit files
+- **⚡ Bash Integration**: Execute shell commands through natural conversation
+- **🔧 Automatic Tool Selection**: AI intelligently chooses the right tools for your requests
+- **🚀 Morph Fast Apply**: Optional high-speed code editing at 4,500+ tokens/sec with 98% accuracy
+- **🔌 MCP Tools**: Extend capabilities with Model Context Protocol servers (Linear, GitHub, etc.)
+- **💬 Interactive UI**: Beautiful terminal interface built with Ink
+- **🌍 Global Installation**: Install and use anywhere with `bun add -g grok-cli-hurry-mode`
+
+## Installation
+
+### Prerequisites
+- Node.js 20+ (Bun 1.0+ recommended for development)
+- Grok API key from X.AI
+- (Optional, Recommended) Morph API key for Fast Apply editing
+
+### Global Installation (Recommended)
+```bash
+bun add -g grok-cli-hurry-mode
+```
+
+Or with npm (fallback):
+```bash
+npm install -g grok-cli-hurry-mode
+```
+
+### Local Development
+```bash
+git clone <repository>
+cd grok-cli
+npm install
+npm run build
+npm link
+```
+
+## Setup
+
+1. Get your Grok API key from [X.AI](https://x.ai)
+
+2. Set up your API key (choose one method):
+
+**Method 1: Environment Variable**
+```bash
+export GROK_API_KEY=your_api_key_here
+```
+
+**Method 2: .env File**
+```bash
+cp .env.example .env
+# Edit .env and add your API key
+```
+
+**Method 3: Command Line Flag**
+```bash
+grok --api-key your_api_key_here
+```
+
+**Method 4: User Settings File**
+Create `~/.grok/user-settings.json`:
+```json
+{
+  "apiKey": "your_api_key_here"
+}
+```
+
+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):
+
+**Method 1: Environment Variable**
+```bash
+export MORPH_API_KEY=your_morph_api_key_here
+```
+
+**Method 2: .env File**
+```bash
+# Add to your .env file
+MORPH_API_KEY=your_morph_api_key_here
+```
+
+### Custom Base URL (Optional)
+
+By default, the CLI uses `https://api.x.ai/v1` as the Grok API endpoint. You can configure a custom endpoint if needed (choose one method):
+
+**Method 1: Environment Variable**
+```bash
+export GROK_BASE_URL=https://your-custom-endpoint.com/v1
+```
+
+**Method 2: Command Line Flag**
+```bash
+grok --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`:
+```json
+{
+  "apiKey": "your_api_key_here",
+  "baseURL": "https://your-custom-endpoint.com/v1"
+}
+```
+
+## Configuration Files
+
+Grok CLI uses two types of configuration files to manage settings:
+
+### User-Level Settings (`~/.grok/user-settings.json`)
+
+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)
+- **Default Model**: Your preferred model (e.g., `grok-code-fast-1`)
+- **Available Models**: List of models you can use
+
+**Example:**
+```json
+{
+  "apiKey": "your_api_key_here",
+  "baseURL": "https://api.x.ai/v1",
+  "defaultModel": "grok-code-fast-1",
+  "models": [
+    "grok-code-fast-1",
+    "grok-4-latest",
+    "grok-3-latest",
+    "grok-3-fast",
+    "grok-3-mini-fast"
+  ]
+}
+```
+
+### Project-Level Settings (`.grok/settings.json`)
+
+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
+
+**Example:**
+```json
+{
+  "model": "grok-3-fast",
+  "mcpServers": {
+    "linear": {
+      "name": "linear",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["@linear/mcp-server"]
+    }
+  }
+}
+```
+
+### How It Works
+
+1. **Global Defaults**: User-level settings provide your default preferences
+2. **Project Override**: Project-level settings override defaults for specific projects
+3. **Directory-Specific**: When you change directories, project settings are loaded automatically
+4. **Fallback Logic**: Project model → User default model → System default (`grok-code-fast-1`)
+
+This means you can have different models for different projects while maintaining consistent global settings like your API key.
+
+### Using Other API Providers
+
+**Important**: Grok CLI uses **OpenAI-compatible APIs**. You can use any provider that implements the OpenAI chat completions standard.
+
+**Popular Providers**:
+- **X.AI (Grok)**: `https://api.x.ai/v1` (default)
+- **OpenAI**: `https://api.openai.com/v1`
+- **OpenRouter**: `https://openrouter.ai/api/v1`
+- **Groq**: `https://api.groq.com/openai/v1`
+
+**Example with OpenRouter**:
+```json
+{
+  "apiKey": "your_openrouter_key",
+  "baseURL": "https://openrouter.ai/api/v1",
+  "defaultModel": "anthropic/claude-3.5-sonnet",
+  "models": [
+    "anthropic/claude-3.5-sonnet",
+    "openai/gpt-4o",
+    "meta-llama/llama-3.1-70b-instruct"
+  ]
+}
+```
+
+## Usage
+
+### Interactive Mode
+
+Start the conversational AI assistant:
+```bash
+grok
+```
+
+Or specify a working directory:
+```bash
+grok -d /path/to/project
+```
+
+### Headless Mode
+
+Process a single prompt and exit (useful for scripting and automation):
+```bash
+grok --prompt "show me the package.json file"
+grok -p "create a new file called example.js with a hello world function"
+grok --prompt "run bun test and show me the results" --directory /path/to/project
+grok --prompt "complex task" --max-tool-rounds 50  # Limit tool usage for faster execution
+```
+
+This mode is particularly useful for:
+- **CI/CD pipelines**: Automate code analysis and file operations
+- **Scripting**: Integrate AI assistance into shell scripts
+- **Terminal benchmarks**: Perfect for tools like Terminal Bench that need non-interactive execution
+- **Batch processing**: Process multiple prompts programmatically
+
+### Tool Execution Control
+
+By default, Grok CLI allows up to 400 tool execution rounds to handle complex multi-step tasks. You can control this behavior:
+
+```bash
+# Limit tool rounds for faster execution on simple tasks
+grok --max-tool-rounds 10 --prompt "show me the current directory"
+
+# Increase limit for very complex tasks (use with caution)
+grok --max-tool-rounds 1000 --prompt "comprehensive code refactoring"
+
+# Works with all modes
+grok --max-tool-rounds 20  # Interactive mode
+grok git commit-and-push --max-tool-rounds 30  # Git commands
+```
+
+**Use Cases**:
+- **Fast responses**: Lower limits (10-50) for simple queries
+- **Complex automation**: Higher limits (500+) for comprehensive tasks
+- **Resource control**: Prevent runaway executions in automated environments
+
+### Model Selection
+
+You can specify which AI model to use with the `--model` parameter or `GROK_MODEL` environment variable:
+
+**Method 1: Command Line Flag**
+```bash
+# Use Grok models
+grok --model grok-code-fast-1
+grok --model grok-4-latest
+grok --model grok-3-latest
+grok --model grok-3-fast
+
+# Use other models (with appropriate API endpoint)
+grok --model gemini-2.5-pro --base-url https://api-endpoint.com/v1
+grok --model claude-sonnet-4-20250514 --base-url https://api-endpoint.com/v1
+```
+
+**Method 2: Environment Variable**
+```bash
+export GROK_MODEL=grok-code-fast-1
+grok
+```
+
+**Method 3: User Settings File**
+Add to `~/.grok/user-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)
+
+### Command Line Options
+
+```bash
+grok [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)
+  -u, --base-url <url>   Grok 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)
+  -p, --prompt <prompt>  process a single prompt and exit (headless mode)
+  --max-tool-rounds <rounds>  maximum number of tool execution rounds (default: 400)
+  -h, --help             display help for command
+```
+
+### Custom Instructions
+
+You can provide custom instructions to tailor Grok's behavior to your project by creating a `.grok/GROK.md` file in your project directory:
+
+```bash
+mkdir .grok
+```
+
+Create `.grok/GROK.md` with your custom instructions:
+```markdown
+# Custom Instructions for Grok CLI
+
+Always use TypeScript for any new code files.
+When creating React components, use functional components with hooks.
+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.
+```
+
+Grok will automatically load and follow these instructions when working in your project directory. The custom instructions are added to Grok's system prompt and take priority over default behavior.
+
+## Morph Fast Apply (Optional)
+
+Grok 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.
+
+### How It Works
+
+When `MORPH_API_KEY` is configured:
+- **`edit_file` tool becomes available** alongside the standard `str_replace_editor`
+- **Optimized for complex edits**: Use for multi-line changes, refactoring, and large modifications
+- **Intelligent editing**: Uses abbreviated edit format with `// ... existing code ...` comments
+- **Fallback support**: Standard tools remain available if Morph is unavailable
+
+**When to use each tool:**
+- **`edit_file`** (Morph): Complex edits, refactoring, multi-line changes
+- **`str_replace_editor`**: Simple text replacements, single-line edits
+
+### Example Usage
+
+With Morph Fast Apply configured, you can request complex code changes:
+
+```bash
+grok --prompt "refactor this function to use async/await and add error handling"
+grok -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.
+
+## MCP Tools
+
+Grok CLI supports MCP (Model Context Protocol) servers, allowing you to extend the AI assistant with additional tools and capabilities.
+
+### Adding MCP Tools
+
+#### Add a custom MCP server:
+```bash
+# Add an stdio-based MCP server
+grok mcp add my-server --transport stdio --command "bun" --args server.js
+
+# Add an HTTP-based MCP server
+grok mcp add my-server --transport http --url "http://localhost:3000"
+
+# Add with environment variables
+grok mcp add my-server --transport stdio --command "python" --args "-m" "my_mcp_server" --env "API_KEY=your_key"
+```
+
+#### Add from JSON configuration:
+```bash
+grok mcp add-json my-server '{"command": "bun", "args": ["server.js"], "env": {"API_KEY": "your_key"}}'
+```
+
+### Linear Integration Example
+
+To add Linear MCP tools for project management:
+
+```bash
+# Add Linear MCP server
+grok mcp add linear --transport sse --url "https://mcp.linear.app/sse"
+```
+
+This enables Linear tools like:
+- Create and manage Linear issues
+- Search and filter issues
+- Update issue status and assignees
+- Access team and project information
+
+### Managing MCP Servers
+
+```bash
+# List all configured servers
+grok mcp list
+
+# Test server connection
+grok mcp test server-name
+
+# Remove a server
+grok mcp remove server-name
+```
+
+### Available Transport Types
+
+- **stdio**: Run MCP server as a subprocess (most common)
+- **http**: Connect to HTTP-based MCP server
+- **sse**: Connect via Server-Sent Events
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Development mode
+bun run dev
+
+# Build project
+npm run build
+
+# Run linter
+bun run lint
+
+# Type check
+bun run typecheck
+```
+
+## Architecture
+
+- **Agent**: Core command processing and execution logic
+- **Tools**: Text editor and bash tool implementations
+- **UI**: Ink-based terminal interface components
+- **Types**: TypeScript definitions for the entire system
+
+## License
+
+MIT
+
+## Troubleshooting
+
+### Tool Execution Errors
+
+If you encounter errors like `fs.readFile is not a function` or `fs.stat is not a function` when using file operations:
+
+1. **This is a known issue** with the tool infrastructure
+2. **Automatic fallback**: The CLI will automatically fall back to bash commands for file operations
+3. **Warning messages**: You may see console warnings like "str_replace_editor tool failed, falling back to bash"
+4. **Functionality**: Despite the warnings, operations should still work via bash fallbacks
+
+This issue is being tracked and the fallbacks ensure the CLI remains functional.
+
+### Common Issues
+
+- **File operations fail**: Check that the file path exists and is accessible
+- **Bash commands fail**: Ensure you have the necessary permissions
+- **Tool timeouts**: Complex operations may take time; the spinner indicates progress
+

package/dist/agent/grok-agent.d.ts

@@ -0,0 +1,54 @@
+import { GrokToolCall } from "../grok/client.js";
+import { ToolResult } from "../types/index.js";
+import { EventEmitter } from "events";
+export interface ChatEntry {
+    type: "user" | "assistant" | "tool_result" | "tool_call";
+    content: string;
+    timestamp: Date;
+    toolCalls?: GrokToolCall[];
+    toolCall?: GrokToolCall;
+    toolResult?: {
+        success: boolean;
+        output?: string;
+        error?: string;
+    };
+    isStreaming?: boolean;
+}
+export interface StreamingChunk {
+    type: "content" | "tool_calls" | "tool_result" | "done" | "token_count";
+    content?: string;
+    toolCalls?: GrokToolCall[];
+    toolCall?: GrokToolCall;
+    toolResult?: ToolResult;
+    tokenCount?: number;
+}
+export declare class GrokAgent extends EventEmitter {
+    private grokClient;
+    private textEditor;
+    private morphEditor;
+    private bash;
+    private todoTool;
+    private confirmationTool;
+    private search;
+    private chatHistory;
+    private messages;
+    private tokenCounter;
+    private abortController;
+    private mcpInitialized;
+    private maxToolRounds;
+    constructor(apiKey: string, baseURL?: string, model?: string, maxToolRounds?: number);
+    private initializeMCP;
+    private isGrokModel;
+    private shouldUseSearchFor;
+    processUserMessage(message: string): Promise<ChatEntry[]>;
+    private messageReducer;
+    processUserMessageStream(message: string): AsyncGenerator<StreamingChunk, void, unknown>;
+    private executeTool;
+    private executeMCPTool;
+    getChatHistory(): ChatEntry[];
+    getCurrentDirectory(): string;
+    executeBashCommand(command: string): Promise<ToolResult>;
+    getCurrentModel(): string;
+    setModel(model: string): void;
+    abortCurrentOperation(): void;
+}