centaurus-cli 2.5.3 → 2.6.0

package/README.md

@@ -1,501 +0,0 @@
-# Centaurus CLI
-
-> A powerful command-line AI coding assistant powered by Google Gemini
-
-[![npm version](https://img.shields.io/npm/v/centaurus-cli.svg)](https://www.npmjs.com/package/centaurus-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js Version](https://img.shields.io/node/v/centaurus-cli.svg)](https://nodejs.org)
-
-## Features
-
-✨ **AI-Powered Coding Assistant**
-- Support for Google Gemini (2.5 Flash, 2.5 Pro, 2.0 Flash, and more)
-- Intelligent code generation and editing
-- Context-aware file operations
-- **Enhanced Agentic Loop** - Autonomous multi-turn task completion
-
-🔧 **Developer Tools**
-- Read, write, and edit files with AI assistance
-- Execute shell commands safely
-- Search codebases with grep
-- Web search capabilities (requires authentication)
-- Diff viewer for code changes
-
-🎨 **Beautiful Terminal UI**
-- Built with Ink (React for CLIs)
-- Syntax highlighting for code blocks
-- Interactive pickers and prompts
-- Real-time streaming responses
-- Markdown rendering
-
-☁️ **Cloud Sync**
-- Conversation history across devices
-- Settings synchronization
-- Seamless authentication with Google
-- Secure backend-managed AI access
-
-🤖 **Autonomous Operation**
-- Continuous multi-turn execution until task completion
-- Automatic detection of incomplete work
-- Smart continuation without manual prompting
-- Handles complex multi-file projects seamlessly
-
-## Installation
-
-### Global Installation (Recommended)
-
-```bash
-npm install -g centaurus-cli
-```
-
-After installation, you can run Centaurus from any directory:
-
-```bash
-centaurus
-```
-
-### Local Installation
-
-```bash
-npm install centaurus-cli
-npx centaurus
-```
-
-## Quick Start
-
-### 1. Prerequisites
-
-Before using Centaurus CLI, ensure the backend service is running and accessible. The backend handles all AI model interactions.
-
-**Backend Setup:**
-- The backend must be deployed and configured with Google API keys
-- Set the backend URL in your `.env` file (see Configuration section)
-- Default: `http://localhost:3000/api`
-
-### 2. First Launch
-
-When you first run Centaurus, you'll see a beautiful welcome screen:
-
-```bash
-centaurus
-```
-
-You'll be prompted to sign in with Google. **Authentication is required** to use AI features.
-
-### 3. Start Chatting
-
-Once authenticated, just type your message and press Enter:
-
-```
-> Create a React component for a todo list
-```
-
-The AI will help you with code generation, file operations, and more!
-
-## Configuration
-
-### Environment Setup
-
-Create a `.env` file in your project directory:
-
-```env
-# Backend API URL (required for all AI features)
-BACKEND_API_URL=http://localhost:3000/api
-```
-
-**Important:** The backend URL is required for the CLI to function. All AI model calls are proxied through the backend service.
-
-### User Configuration
-
-Your settings are stored in `~/.centaurus/config.json`:
-- Preferred model
-- Theme settings
-- Auto-accept preferences
-- Plan mode settings
-
-**Note:** API keys and system prompts are managed centrally by the backend service. This ensures:
-- Consistent AI behavior across all Centaurus clients (CLI, Desktop, Web)
-- Easy updates to AI instructions without client changes
-- Secure credential management
-- Environment-aware responses (OS, shell, working directory)
-
-## Commands
-
-### Slash Commands
-
-```bash
-/help                              # Show all commands
-/config                            # View current configuration
-/model                             # Select AI model
-/plan                              # Toggle plan mode
-/clear                             # Clear conversation history
-/logout                            # Sign out and exit
-/exit                              # Exit the application
-```
-
-### Examples
-
-```bash
-# Change model
-/model gemini-2.5-flash
-
-# Enable plan mode for complex tasks
-/plan
-
-# Clear conversation history
-/clear
-```
-
-## Features in Detail
-
-### Enhanced Agentic Loop
-
-Centaurus CLI features a robust autonomous operation system that works continuously until your task is complete:
-
-**How It Works:**
-- The AI executes multiple turns automatically without manual prompting
-- Detects when work is incomplete and continues autonomously
-- Handles complex multi-file projects in a single session
-- Supports up to 100 turns for complex tasks
-- Automatically stops when the task is complete
-
-**Example - Multi-File Project:**
-```
-> Create a landing page with HTML, CSS, and JavaScript
-```
-
-The AI will:
-1. Create `index.html` with structure
-2. Create `styles.css` with styling
-3. Create `script.js` with interactivity
-4. Complete the task automatically without additional prompts
-
-**Smart Continuation:**
-- Detects incomplete responses (e.g., "I created the HTML file...")
-- Automatically prompts the AI to continue with remaining steps
-- Prevents premature stopping on complex tasks
-
-**Safety Features:**
-- 500ms delay between turns to prevent rate limiting
-- Maximum 100 turns to prevent infinite loops
-- Long-running command protection (blocks `npm run dev`, etc.)
-- 30-second timeout for command executions
-
-### File Operations
-
-Centaurus can read, write, and edit files in your project:
-
-```
-> Read the package.json file
-> Create a new file called utils.ts with helper functions
-> Edit the README.md to add installation instructions
-```
-
-### Code Generation
-
-Generate code in any language:
-
-```
-> Create a Python script to parse CSV files
-> Write a TypeScript interface for a user object
-> Generate a SQL query to find duplicate records
-```
-
-### Web Search
-
-Search the web for documentation and solutions (requires authentication):
-
-```
-> Search for the latest React hooks best practices
-> Find documentation for the Axios library
-```
-
-### Command Execution
-
-Execute shell commands safely:
-
-```
-> Run npm install
-> List all files in the current directory
-> Check the git status
-```
-
-**Note:** Long-running commands (like `npm run dev`, `yarn start`, or development servers) are automatically blocked. Run these manually in a separate terminal.
-
-### Plan Mode
-
-For complex tasks, enable plan mode to see the implementation plan before execution:
-
-```bash
-/plan
-> Build a REST API with Express and TypeScript
-```
-
-The AI will create a detailed plan and ask for approval before implementing.
-
-## Authentication
-
-### Sign In (Required)
-
-Authentication with Google is required to use Centaurus CLI:
-
-1. Start Centaurus
-2. Select "Sign in with Google"
-3. Complete authentication in browser
-4. Start using AI features!
-
-### Features
-
-- **Conversation History**: Access your chats from any device
-- **Settings Sync**: Your preferences follow you everywhere
-- **Secure AI Access**: Backend-managed API keys for security
-- **Web Search**: Powered by backend API
-
-### Backend Connectivity
-
-Centaurus CLI requires a connection to the backend service:
-- All AI model calls are proxied through the backend
-- Authentication tokens are validated by the backend
-- Ensures secure and centralized API key management
-- No local API key storage required
-
-### System Prompt Management
-
-System prompts (the foundational AI instructions) are managed entirely by the backend:
-
-**Benefits:**
-- **Consistency**: All Centaurus clients use the same AI behavior
-- **Easy Updates**: Prompt improvements are deployed instantly without client updates
-- **Environment Awareness**: Backend injects your OS, shell, and working directory context
-- **Mode Support**: Different prompts for default, plan, and command modes
-
-**How It Works:**
-1. CLI sends your message and environment context to the backend
-2. Backend injects the appropriate system prompt with your environment details
-3. AI receives complete context and responds appropriately
-4. No prompt management needed on your end!
-
-**Environment Context Sent:**
-- Operating system (Windows, macOS, Linux)
-- Shell type (cmd, PowerShell, bash, zsh)
-- Current working directory
-- Home directory path
-- Current mode (default, plan, command)
-
-## Advanced Usage
-
-### Custom Backend
-
-Set up your own backend instance:
-
-```env
-BACKEND_API_URL=https://your-backend.com/api
-```
-
-**Backend Requirements:**
-- Must be configured with Google API keys
-- Must support the `/api/ai/chat` endpoint
-- Must handle authentication and session management
-
-### Keyboard Shortcuts
-
-- `Ctrl+C` - Cancel current operation
-- `Ctrl+D` - Exit (when input is empty)
-- `Arrow Keys` - Navigate pickers
-- `Enter` - Confirm selection
-
-## Troubleshooting
-
-### "Authentication required"
-
-Sign in with Google:
-1. Restart the CLI
-2. Choose "Yes" when prompted to sign in
-3. Complete the authentication flow in your browser
-
-### "Backend API is not reachable"
-
-Check your `.env` file and ensure the backend is running:
-
-```env
-BACKEND_API_URL=http://localhost:3000/api
-```
-
-Verify backend is running:
-```bash
-cd backend
-npm start
-```
-
-**Common Issues:**
-- Backend service is not running
-- Incorrect backend URL in `.env`
-- Network connectivity issues
-- Firewall blocking the connection
-
-### "Rate limit exceeded"
-
-The backend has exhausted its API quota. This is managed by the backend administrator. Wait a few moments and try again.
-
-### AI Stops Before Task is Complete
-
-If the AI stops working before finishing your task:
-
-**Possible Causes:**
-1. **Network interruption** - Check your internet connection
-2. **Backend timeout** - The backend may have timed out; try again
-3. **Turn limit reached** - Very complex tasks may hit the 100-turn safety limit
-
-**Solutions:**
-- For simple continuation: Send a follow-up message like "Continue with the remaining steps"
-- For complex tasks: Break the task into smaller, more specific requests
-- Check backend logs for errors if the issue persists
-
-### AI Keeps Working After Task is Done
-
-The enhanced agentic loop should automatically detect completion. If it continues unnecessarily:
-
-**What to Do:**
-- Press `Ctrl+C` to stop the current operation
-- The AI should detect completion within 2-3 turns after finishing
-- If this happens frequently, report it as a bug with your task description
-
-### Long-Running Commands Blocked
-
-Commands like `npm run dev`, `yarn start`, or `python -m http.server` are automatically blocked:
-
-**Why:**
-- These commands don't terminate and would hang the CLI
-- They're meant to run in separate terminal sessions
-
-**Solution:**
-- Run development servers manually in a separate terminal
-- The AI will inform you when you need to run these commands yourself
-
-### Slow Response or Timeouts
-
-If responses are slow or timing out:
-
-**Troubleshooting Steps:**
-1. Check your internet connection speed
-2. Verify backend is responsive: `curl http://localhost:3000/api/health`
-3. Check backend logs for rate limiting or API errors
-4. Try a simpler query to test connectivity
-5. Restart the CLI and try again
-
-### Commands Timing Out
-
-Individual commands have a 30-second timeout:
-
-**If a command times out:**
-- The command may be too slow or hanging
-- Check if the command works when run manually
-- Consider breaking complex commands into smaller steps
-- Some operations (large file processing) may need to be done outside the CLI
-
-### Environment Context Issues
-
-If the AI doesn't seem aware of your OS or environment:
-
-**Check:**
-1. Backend is receiving environment context (check backend logs)
-2. Your shell environment variables are set correctly
-3. Backend system prompt service is functioning
-
-**Verify:**
-```bash
-# Check environment variables
-echo $SHELL          # macOS/Linux
-echo %ComSpec%       # Windows
-```
-
-### Reset Configuration
-
-Delete the config file to start fresh:
-
-**Windows:**
-```cmd
-del %USERPROFILE%\.centaurus\config.json
-```
-
-**macOS/Linux:**
-```bash
-rm ~/.centaurus/config.json
-```
-
-**Note:** This will clear your model preferences and settings, but you'll need to re-authenticate.
-
-### Getting Help
-
-If you're still experiencing issues:
-
-1. **Check Backend Logs**: Most issues originate from backend connectivity or configuration
-2. **Enable Debug Logging**: Set `DEBUG=centaurus:*` environment variable
-3. **Report Issues**: Include your OS, Node version, and error messages
-4. **Community Support**: Check discussions for similar issues and solutions
-
-## Requirements
-
-- Node.js >= 18.0.0
-- npm or yarn
-- Terminal with color support
-- **Backend service running and accessible**
-- **Google account for authentication**
-
-## Development
-
-### Clone and Build
-
-```bash
-git clone https://github.com/yourusername/centaurus-cli.git
-cd centaurus-cli
-npm install
-npm run build
-npm start
-```
-
-### Project Structure
-
-```
-centaurus-cli/
-├── src/
-│   ├── ai/              # AI provider implementations
-│   ├── commands/        # Command parser
-│   ├── config/          # Configuration management
-│   ├── services/        # API client and services
-│   ├── tools/           # Tool implementations
-│   ├── ui/              # Ink UI components
-│   └── index.ts         # Entry point
-├── dist/                # Compiled JavaScript
-└── package.json
-```
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## License
-
-MIT © [Your Name]
-
-## Support
-
-- 📖 [Documentation](./CONFIG_GUIDE.md)
-- 🐛 [Report Issues](https://github.com/yourusername/centaurus-cli/issues)
-- 💬 [Discussions](https://github.com/yourusername/centaurus-cli/discussions)
-
-## Acknowledgments
-
-- Built with [Ink](https://github.com/vadimdemedes/ink) - React for CLIs
-- Powered by [Google Gemini](https://ai.google.dev/)
-- Inspired by modern AI coding assistants
-
----
-
-Made with ❤️ by developers, for developers