grok-dev 1.0.0-rc1

package/.cursor/rules/development-workflow.mdc

@@ -0,0 +1,66 @@
+---
+description: Development workflow and common commands
+globs: "**/*"
+alwaysApply: true
+---
+
+# Development Workflow
+
+## Prerequisites
+
+- Bun 1.0+ (required)
+
+## Common Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Development (runs from source with Bun)
+bun run dev
+
+# Build (compile TypeScript to dist/)
+bun run build
+
+# Type checking (no emit)
+bun run typecheck
+
+# Linting
+bun run lint
+
+# Format (check / write)
+bun run format
+bun run format:fix
+
+# Run the built CLI
+bun run start
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----|----|----|
+| `GROK_API_KEY` | Yes | API key for xAI Grok |
+| `GROK_BASE_URL` | No | Custom API endpoint (default: `https://api.x.ai/v1`) |
+| `GROK_MODEL` | No | Model override (default: `grok-4-1-fast`) |
+| `GROK_MAX_TOKENS` | No | Max tokens per response (default: 16384) |
+
+Copy `.env.example` to `.env` and fill in your values.
+
+## Git hooks
+
+After `bun install`, **Husky** installs a **pre-commit** hook that runs **`lint-staged`**: Biome **format + lint** (`check --write`) on staged `*.{ts,tsx,js,mjs,cjs,json}` files. Fixes are written to disk and re-staged automatically when possible.
+
+## Before Submitting Changes
+
+1. Run `bun run typecheck` — CI enforces this on every PR.
+2. Run `bun run lint` — fix any Biome issues (or let pre-commit apply safe fixes).
+3. Ensure no secrets or `.env` files are committed.
+4. Follow the PR template in `.github/pull_request_template.md`.
+
+## Project Structure Conventions
+
+- Source code lives in `src/`, compiled output in `dist/` (gitignored).
+- The CLI entry point is `src/index.ts` which uses Commander.js for argument parsing.
+- UI is built with OpenTUI React (`@opentui/react`).
+- Only tool is bash — all file operations happen through shell commands.

package/.cursor/rules/project-overview.mdc

@@ -0,0 +1,66 @@
+---
+description: Project overview and architecture reference
+globs: "**/*"
+alwaysApply: true
+---
+
+# Grok CLI — Project Overview
+
+Grok CLI (`@vibe-kit/grok-cli`) is an open-source AI coding agent powered by Grok that brings AI assistance directly into the terminal.
+
+## Tech Stack
+
+- **Language**: TypeScript (ES2022, ESNext modules)
+- **Runtime**: Bun (primary)
+- **UI Framework**: React with [OpenTUI](https://github.com/anomalyco/opentui) for terminal rendering
+- **Build**: `tsc` (TypeScript compiler)
+- **Package Manager**: Bun
+- **API Client**: OpenAI SDK (for OpenAI-compatible xAI API)
+- **Tools**: Bash-only (all file operations via shell commands)
+- **Search**: X Search API + Web Search via xAI Responses API
+
+## Architecture
+
+```
+src/
+├── index.ts          # CLI entry point (Commander.js + OpenTUI)
+├── agent/
+│   └── agent.ts      # Agent — orchestrates client, bash tool, search
+├── grok/
+│   ├── client.ts     # Grok API client (Chat Completions + Responses API)
+│   ├── models.ts     # Model definitions and metadata
+│   └── tools.ts      # Tool schemas (bash, search_web, search_x)
+├── tools/
+│   └── bash.ts       # Bash command execution
+├── ui/
+│   └── app.tsx       # OpenTUI React terminal UI
+├── utils/
+│   ├── settings.ts   # User and project settings
+│   ├── git-root.ts   # Resolve git repository root for AGENTS.md discovery
+│   └── instructions.ts # AGENTS.md (ecosystem) + .grok/GROK.md
+└── types/
+    └── index.ts      # Shared TypeScript types
+```
+
+## Key Patterns
+
+- **Agent loop**: `Agent.processMessage()` is an async generator that yields `StreamChunk` objects — the LLM responds, tools execute, results feed back until no more tool calls remain.
+- **Bash-only tools**: The agent uses bash for everything (file editing, searching, git, builds, etc.).
+- **X Search & Web Search**: Integrated via the xAI Responses API for real-time information.
+- **Settings hierarchy**: Environment variables → User-level (`~/.grok/user-settings.json`) → Project-level (`.grok/settings.json`).
+- **Custom instructions**: `~/.grok/AGENTS.md`, then `AGENTS.override.md` / `AGENTS.md` per directory from git root through the workspace cwd (Codex-style merge), then `.grok/GROK.md` or `~/.grok/GROK.md` last.
+- **ESM only**: The project uses `"type": "module"` — all imports use `.js` extensions for compiled output.
+
+## Latest Grok Models
+
+- grok-4-0709 (flagship reasoning)
+- grok-4.20-beta-0309 (multi-agent, 2M context)
+- grok-4-fast (fast reasoning, 2M context)
+- grok-4-1-fast (latest fast, 2M context)
+- grok-code-fast-1 (code optimized)
+- grok-3, grok-3-mini
+
+## CI/CD
+
+- **typecheck.yml**: Runs `tsc --noEmit` on push/PR to `main`/`develop`.
+- **security.yml**: Runs `npm audit` and TruffleHog secret scanning.

package/.cursor/rules/react-ink-components.mdc

@@ -0,0 +1,45 @@
+---
+description: Guidelines for React components using Ink for terminal UI
+globs: "src/ui/**/*.tsx,src/hooks/**/*.ts"
+alwaysApply: false
+---
+
+# React + Ink Terminal UI
+
+## Framework
+
+This project uses [Ink](https://github.com/vadimdemedes/ink) v4 to render React components in the terminal. Ink provides `<Box>`, `<Text>`, and other primitives instead of HTML elements.
+
+## Component Patterns
+
+- Use **functional components** with hooks — no class components.
+- JSX is compiled with `"jsx": "react"` (classic transform), so `import React from "react"` is required in every `.tsx` file.
+- Components are in `src/ui/components/` and follow kebab-case naming (`chat-interface.tsx`, `diff-renderer.tsx`).
+
+## Key Components
+
+| Component | Purpose |
+|-----------|---------|
+| `ChatInterface` | Main chat loop, orchestrates agent interaction |
+| `ChatHistory` | Renders conversation entries |
+| `ChatInput` | User text input with key bindings |
+| `DiffRenderer` | Displays file diffs |
+| `ModelSelection` | Model picker UI |
+| `LoadingSpinner` | Animated loading indicator |
+| `ConfirmationDialog` | User confirmation prompts for tool operations |
+| `McpStatus` | MCP server connection status |
+| `CommandSuggestions` | Autocomplete suggestions |
+| `ApiKeyInput` | API key entry prompt |
+
+## Ink-Specific Guidelines
+
+- Use `<Box>` for layout (flexbox model) and `<Text>` for styled text.
+- Use Ink's `useInput` hook for keyboard handling.
+- Use `chalk` for color utilities in `src/ui/utils/colors.ts`.
+- Markdown rendering for chat output uses `marked` + `marked-terminal`.
+- The app is rendered via `render(React.createElement(ChatInterface, { agent, initialMessage }))` in the entry point.
+
+## Hooks
+
+- Custom hooks live in `src/hooks/`.
+- Follow the `use` prefix convention (`useInput`, `useChat`, etc.).

package/.cursor/rules/tools-and-agent.mdc

@@ -0,0 +1,62 @@
+---
+description: Guidelines for the agent system and tool implementations
+globs: "src/agent/**/*.ts,src/tools/**/*.ts,src/grok/**/*.ts"
+alwaysApply: false
+---
+
+# Agent & Tools System
+
+## Agent
+
+`Agent` (in `src/agent/agent.ts`) is the core orchestrator. It manages:
+
+- The Grok API client (`GrokClient`)
+- Bash tool for all shell operations
+- Web search and X search via the Responses API
+- Chat history and message accumulation
+- Abort/cancellation support
+
+### Agent Loop
+
+The agent uses an iterative tool-call pattern via `processMessage` (async generator):
+
+1. Send messages to the LLM via Chat Completions API (streaming).
+2. If the response contains `tool_calls`, execute each tool.
+3. Append tool results to the message history.
+4. Repeat until no tool calls remain or `maxToolRounds` is reached.
+5. Yield `StreamChunk` objects for real-time UI updates.
+
+## Tool Interface
+
+All tools return a `ToolResult`:
+
+```typescript
+interface ToolResult {
+  success: boolean;
+  output?: string;
+  error?: string;
+}
+```
+
+Tools should never throw — wrap errors in `{ success: false, error: "..." }`.
+
+## Built-in Tools
+
+| Tool | File | Purpose |
+|------|------|---------|
+| `BashTool` | `src/tools/bash.ts` | Execute any shell command |
+| `search_web` | via `GrokClient.searchWeb()` | Web search using Responses API |
+| `search_x` | via `GrokClient.searchX()` | X/Twitter search using Responses API |
+
+## Grok Client
+
+`GrokClient` (in `src/grok/client.ts`) handles two API endpoints:
+
+- **Chat Completions** (`/v1/chat/completions`): Main agent loop with streaming and tool calling
+- **Responses API** (`/v1/responses`): X Search and Web Search with server-side tools
+
+## Adding a New Tool
+
+1. Add the tool schema to `src/grok/tools.ts` (in the `TOOLS` array).
+2. Add the execution case in `Agent.executeTool()`.
+3. Update the system prompt in `Agent` to document the tool.

package/.cursor/rules/typescript-conventions.mdc

@@ -0,0 +1,54 @@
+---
+description: TypeScript coding conventions and style guidelines
+globs: "**/*.ts,**/*.tsx"
+alwaysApply: false
+---
+
+# TypeScript Conventions
+
+## Module System
+
+- This is an ESM project (`"type": "module"` in package.json).
+- Always use ES module `import`/`export` syntax — never `require()`.
+- When importing local modules, include the `.js` extension (TypeScript compiles `.ts` → `.js`):
+  ```typescript
+  import { GrokAgent } from "./agent/grok-agent.js";
+  ```
+
+## TypeScript Configuration
+
+- Target: ES2022, Module: ESNext, JSX: react
+- `strict: false` and `noImplicitAny: false` — the codebase does not enforce strict mode.
+- `moduleResolution: "Bundler"` is used.
+- Source files live in `src/`, compiled output goes to `dist/`.
+
+## Type Practices
+
+- Prefer explicit interfaces for public API boundaries (e.g. `ChatEntry`, `ToolResult`, `GrokToolCall`).
+- Use `type` imports when importing only types:
+  ```typescript
+  import type { ChatCompletionMessageParam } from "openai/resources/chat";
+  ```
+- `any` is acceptable where strict typing would add friction, but prefer narrower types when practical.
+- Shared types belong in `src/types/index.ts`.
+
+## Naming Conventions
+
+- **Files**: kebab-case (`grok-agent.ts`, `chat-interface.tsx`, `settings-manager.ts`).
+- **Classes**: PascalCase (`GrokAgent`, `TextEditorTool`, `BashTool`).
+- **Interfaces/Types**: PascalCase (`ChatEntry`, `ToolResult`, `StreamingChunk`).
+- **Functions/variables**: camelCase (`processUserMessage`, `loadApiKey`).
+- **Constants**: camelCase or UPPER_SNAKE_CASE for true constants (`GROK_TOOLS`).
+
+## Error Handling
+
+- Catch errors as `error: any` and access `.message` for display.
+- Tool execution methods return `ToolResult` objects (`{ success, output?, error? }`) rather than throwing.
+- Use `process.exit(1)` for fatal CLI errors.
+
+## ESLint Rules
+
+- `@typescript-eslint/no-unused-vars`: error
+- `@typescript-eslint/no-explicit-any`: warn
+
+Run `bun run lint` to check and `bun run typecheck` to verify types.

package/.grok/settings.json

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

package/.husky/pre-commit

@@ -0,0 +1 @@
+bun run pre-commit

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.