goatchain-cli 0.0.2-beta.7 → 0.0.2-beta.9

package/README.md

@@ -0,0 +1,357 @@
+# GoatChain CLI 🐐
+
+> Interactive AI agent CLI for software engineering tasks with built-in file operations, web search, and planning capabilities
+
+[![npm version](https://badge.fury.io/js/goatchain-cli.svg)](https://badge.fury.io/js/goatchain-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- **🤖 Interactive AI Agent** - Real-time conversation with AI assistant for coding tasks
+- **📁 File Operations** - Read, write, edit files with built-in safety checks
+- **🔍 Code Navigation** - Glob search, grep, and AST-aware code analysis
+- **🌐 Web Search** - Integrated web search for up-to-date information
+- **📋 Plan Mode** - Structured planning workflow (plan → confirm → execute)
+- **💾 Session Management** - Save and restore conversation sessions
+- **🔧 Tool Integration** - Built-in tools for common development tasks
+- **🖼️ Image Support** - Attach and analyze images in conversations
+- **⚙️ Configurable** - Flexible configuration via environment and config files
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install globally via npm
+npm install -g goatchain-cli
+
+# Or use npx (recommended for first-time use)
+npx goatchain-cli
+
+# Or install locally in your project
+npm install --save-dev goatchain-cli
+```
+
+### Basic Usage
+
+```bash
+# Set your OpenAI API key
+export OPENAI_API_KEY=your-api-key-here
+
+# Start the CLI
+goatchain
+
+# Or with npx
+npx goatchain-cli
+```
+
+### First Conversation
+
+```bash
+$ goatchain
+🤖 GoatChain CLI v0.0.2-beta.6
+
+Welcome! I'm your AI assistant. Type /help for commands or ask me anything.
+
+> Can you help me understand this TypeScript project?
+```
+
+## 📦 Installation Methods
+
+### Method 1: Global Installation (Recommended)
+
+```bash
+npm install -g goatchain-cli
+```
+
+### Method 2: Project-based Installation
+
+```bash
+# Add to your project
+npm install --save-dev goatchain-cli
+
+# Run from project directory
+npx goatchain
+```
+
+### Method 3: Direct from GitHub
+
+```bash
+# Run directly from GitHub repository
+npx github:zjywill/GoatChain#main:packages/cli
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+```bash
+# Required: OpenAI API key
+export OPENAI_API_KEY=sk-...
+
+# Optional: Web search (Serper API)
+export SERPER_API_KEY=your-serper-key
+
+# Optional: Default model
+export GOATCHAIN_DEFAULT_MODEL=gpt-4o
+
+# Optional: Enable plan mode by default
+export GOATCHAIN_PLAN_MODE=1
+```
+
+### Local Configuration File
+
+Create `.goatchain/config.json` in your project:
+
+```json
+{
+  "model": {
+    "provider": "openai",
+    "modelId": "gpt-4o"
+  },
+  "tools": {
+    "webSearch": {
+      "apiKey": "your-serper-key",
+      "numResults": 10
+    }
+  },
+  "planMode": "on"
+}
+```
+
+## 🎯 Commands Reference
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show help information |
+| `/model <id>` | Switch model (e.g., `gpt-4o`, `gpt-3.5-turbo`) |
+| `/plan [on|off|toggle]` | Toggle plan mode |
+| `/approvals` | Select approval mode |
+| `/set <key> <value>` | Set request parameters |
+| `/unset <key>` | Clear a parameter |
+| `/params` | Show current parameters |
+
+### Session Management
+
+| Command | Description |
+|---------|-------------|
+| `/sessions` | List saved sessions |
+| `/use <sessionId>` | Restore a session |
+| `/save` | Save current session |
+| `/new` | Start new conversation |
+| `/status` | Show current status |
+
+### Tool Configuration
+
+| Command | Description |
+|---------|-------------|
+| `/tools` | List enabled tools |
+| `/base-url <url>` | Set API base URL |
+| `/api-key <key>` | Set API key |
+| `/web-search-key <key>` | Set web search API key |
+
+## 🔧 Built-in Tools
+
+### File Operations
+
+- **Read** - Read files and directories
+- **Write** - Create new files
+- **Edit** - Modify existing files
+- **Glob** - Pattern-based file search
+- **Grep** - Content search across files
+
+### Development Tools
+
+- **WebSearch** - Internet search for current information
+- **AskUserQuestion** - Interactive user prompts for decisions
+- **TodoWrite** - Structured task planning
+- **Bash** - Execute shell commands
+
+### Code Analysis
+
+- **ast_grep_search** - AST-aware code pattern matching
+- **ast_grep_replace** - AST-aware code refactoring
+
+## 📋 Plan Mode
+
+Plan mode enables a structured workflow for complex tasks:
+
+```bash
+# Enable plan mode
+/plan on
+
+# Workflow:
+# 1. Agent explores codebase and researches request
+# 2. May ask clarifying questions
+# 3. Creates structured plan (3-8 steps)
+# 4. You review and approve plan
+# 5. Agent executes approved plan
+
+# File modifications are blocked during planning phase
+```
+
+## 💾 Session Management
+
+Sessions preserve conversation history and context:
+
+```bash
+# List available sessions
+/sessions
+
+# Restore a specific session
+/use session-id-here
+
+# Save current session
+/save
+
+# Start fresh
+/new
+```
+
+Sessions are stored in `.goatchain/sessions/` (gitignored).
+
+## 🔍 Web Search Integration
+
+Enable web search for current information:
+
+```bash
+# Set web search API key
+/web-search-key your-serper-api-key
+
+# Or set environment variable
+export SERPER_API_KEY=your-key
+
+# Web search will be available for weather, news, and current events
+```
+
+## 🖼️ Image Support
+
+Attach images to conversations for analysis:
+
+```bash
+# The agent can analyze images you attach
+# Supported formats: PNG, JPG, JPEG
+```
+
+## 🚀 Advanced Usage
+
+### Command Line Arguments
+
+```bash
+# Set API key via command line
+goatchain --api-key sk-...
+
+# Specify model
+goatchain --model gpt-4o
+
+# Set custom base URL
+goatchain --base-url https://api.openai.com/v1
+
+# Configure request parameters
+goatchain --max-tokens 2000 --temperature 0.7
+```
+
+### Integration with Projects
+
+```bash
+# Run in specific directory
+cd /path/to/your/project
+goatchain
+
+# The agent will automatically detect and analyze your codebase
+```
+
+### Environment-Specific Configuration
+
+```bash
+# Development environment
+export GOATCHAIN_PLAN_MODE=1
+export GOATCHAIN_DEFAULT_MODEL=gpt-4o
+
+# Production-like environment (more conservative)
+export GOATCHAIN_PLAN_MODE=0
+export GOATCHAIN_DEFAULT_MODEL=gpt-3.5-turbo
+```
+
+## 🛠️ Development
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/zjywill/GoatChain.git
+cd GoatChain/packages/cli
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Test the CLI
+npm run smoke
+```
+
+### Project Structure
+
+```
+packages/cli/
+├── src/
+│   ├── index.ts          # Main CLI entry point
+│   ├── args.ts           # Command line argument parsing
+│   ├── sdk.ts            # GoatChain SDK integration
+│   ├── repl.ts           # Interactive REPL implementation
+│   ├── turn.ts           # Turn processing logic
+│   └── tools/            # Built-in tool implementations
+├── dist/                 # Built output
+└── package.json
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**"API key not found"**
+```bash
+# Set OpenAI API key
+export OPENAI_API_KEY=your-key
+```
+
+**"Model not available"**
+```bash
+# Switch to available model
+/model gpt-3.5-turbo
+```
+
+**Web search not working**
+```bash
+# Set Serper API key
+/web-search-key your-key
+```
+
+**File operations failing**
+- Check file permissions
+- Ensure files exist and are accessible
+- Verify path correctness
+
+### Debug Mode
+
+Enable verbose logging:
+```bash
+export DEBUG=goatchain:*
+goatchain
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see the main [GoatChain repository](https://github.com/zjywill/GoatChain) for contribution guidelines.
+
+## 📄 License
+
+MIT © [Simon He](https://github.com/Simon-He95)
+
+---
+
+**Need help?** Type `/help` in the CLI or open an issue on GitHub.