Centaurus CLI

A powerful command-line AI coding assistant powered by Google Gemini

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)

npm install -g centaurus-cli

After installation, you can run Centaurus from any directory:

centaurus

Local Installation

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:

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:

# 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

/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

# 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:

/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:

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:

BACKEND_API_URL=http://localhost:3000/api

Verify backend is running:

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:

# Check environment variables
echo $SHELL          # macOS/Linux
echo %ComSpec%       # Windows

Reset Configuration

Delete the config file to start fresh:

Windows:

del %USERPROFILE%\.centaurus\config.json

macOS/Linux:

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

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
• 🐛 Report Issues
• 💬 Discussions

Acknowledgments

• Built with Ink - React for CLIs
• Powered by Google Gemini
• Inspired by modern AI coding assistants

Made with ❤️ by developers, for developers