echo-ai-cli

v1.0.0

Published

21 days ago

Echo - The Resilient Agentic Terminal with multi-provider AI, auto-failover, and plugin sync

0High
0Medium
0Low

qdevhub

cli ai chat openai gemini anthropic assistant

Echoctl - The Ultimate AI CLI Agent

Your thoughts. My echo. Infinite possibility.

A resilient, multi-provider AI CLI tool with ReAct agent capabilities, automatic failover, and local code execution. Echo supports 14+ AI providers and includes a Second Brain knowledge base, HITL approvals, and development track isolation.

✨ Features

🎯 Core Capabilities

| Feature | Description | |---------|-------------| | 14+ Providers | OpenAI, Gemini, Claude, Groq, Ollama, and 9 more with auto-failover | | ReAct Agent | Reason → Act → Observe loop for autonomous task completion | | Second Brain | Persistent knowledge base with tags and search | | HITL Approvals | Human-in-the-loop for dangerous operations | | Track Isolation | Separate contexts for different projects | | Interactive TUI | Real-time dashboard with Ink (React for CLI) | | Smart Mode | Auto-selects best provider based on task type | | Security First | Encrypted config, dangerous command blocking, rate limiting |

🧠 ReAct Agent Mode

Echo follows the Reason + Act pattern:

Reason - Thinks about what needs to be done
Act - Executes tools (shell, files, code, web, browser)
Observe - Analyzes results
Repeat - Until task is complete

🔄 Automatic Failover

If your primary provider fails (rate limit, API error), Echo automatically switches to your backup provider. No interrupted workflows.

🚀 Quick Start

Installation

# From npm (coming soon)
npm install -g @chieji/echo-ai-cli

# From source
git clone https://github.com/chieji/echoctl.git
cd echoctl
npm install
npm run build
npm link

# Now you can run 'echo' from anywhere
echo "Hello, Echo!"

1. Authenticate

# Auto-detect existing credentials (gcloud, aliyun, env vars)
echo auth sync

# Or interactive setup
echo auth login

# View status
echo auth status

Supported Providers: | Provider | Status | Free Tier | |----------|--------|-----------| | 🟩 Google Gemini | ✅ Configured | 60 req/min | | 🟦 OpenAI | ✅ Configured | Paid | | 🟪 Anthropic Claude | ✅ Configured | Paid | | 🟥 Alibaba Qwen | ✅ Configured | Free via Aliyun | | 🟢 Groq | ✅ Configured | Free tier | | 🟨 Ollama | ✅ Configured | Free (local) | | 🔵 DeepSeek | ✅ Configured | Paid | | 🔴 Kimi | ✅ Configured | Paid | | 🔷 OpenRouter | ✅ Configured | Varies | | 🟠 Together AI | ✅ Configured | Free tier | | 🔴 ModelScope | ✅ Configured | Free tier | | 🟣 Mistral | ✅ Configured | Paid | | 🟡 Hugging Face | ✅ Configured | Free tier | | ⬛ GitHub Models | ✅ Configured | Free tier |

2. Standard Chat

# Quick message
echo "What is TypeScript?"

# With options
echo chat "Explain closures" --provider openai

3. Agent Mode (ReAct)

Echo can autonomously complete tasks using tools:

# Agent mode - Echo will execute tools to complete tasks
echo chat "Count the lines of code in all .ts files" --agent

# Git operations
echo chat "Check git status and commit changes" --agent

# Multi-file operations
echo chat "Rename all getUser() to fetchUser() in the project" --agent

# Web search (no API key needed!)
echo chat "Search for latest TypeScript news" --agent
echo chat "Get latest tech news" --agent

# YOLO mode - No confirmation prompts
echo chat "Create a new file called test.js with console.log('hello')" --agent --yolo

Available Tools:

🛠️ Shell: run_command - Execute any shell command
📁 Files: readFile, writeFile, listFiles, deleteFile
💻 Code: executePython, executeNode
🌐 Web: searchWeb, scrapeUrl, getNews
🌍 Browser: navigate, screenshot, click, type, extract
📦 Git: getGitStatus, gitAdd, gitCommit, gitPush, gitLog
📝 Multi-File: findAndReplace, searchInFiles, createFiles
🔬 LSP: findSymbolReferences, renameSymbol, findSymbolDefinition

📚 Command Reference

Agent Management

# Show agent health status
echo agent health

# List all available tools
echo agent tools

# Show agent memory and sessions
echo agent memory

# Run agent with a task
echo agent run "my task"

# Show current agent plan
echo agent plan

# View event logs
echo agent logs

# Configure settings
echo agent config --status        # Show current config
echo agent config --plan          # Enable plan mode
echo agent config --auto-accept   # Auto-confirm actions

Authentication

echo auth login              # Interactive API key setup
echo auth sync               # Auto-detect from gcloud, aliyun, env
echo auth status             # Show configured providers
echo auth logout [provider]  # Remove a provider

Chat & Sessions

# Standard chat
echo "message"
echo chat "message"

# Options:
#   -p, --provider    Specify provider (openai, gemini, anthropic)
#   -s, --smart       Use smart mode (auto-select provider)
#   --session <id>    Use specific session
#   -r, --raw         Raw output mode
#   -a, --agent       Agent mode (ReAct with tools)
#   --yolo            Execute without confirmation (use with --agent)

echo chat "Debug this" --provider openai
echo chat "Write a poem" --smart
echo chat "Analyze this codebase" --agent

# Session management
echo new-session "Project X"   # Start new session
echo sessions                  # List sessions
echo stats                     # Show statistics

Second Brain (Knowledge Base)

# Save a memory
echo brain save "api-key" "sk-123456" --tag credentials --tag openai

# Retrieve a memory
echo brain get "api-key"

# Search memories
echo brain search "api"
echo brain search "credentials" --tag openai

# List all memories
echo brain list

# Delete a memory
echo brain delete "api-key"

# Statistics
echo brain stats

# Export/Import
echo brain export -o backup.json
echo brain import backup.json

HITL Approvals

# List pending approvals
echo approve list

# Approve or deny
echo approve <id> --yes
echo approve <id> --no

# Statistics
echo approve stats

# Auto-approve rules
echo approve add-rule "readFile"
echo approve remove-rule "readFile"
echo approve enable-rule "readFile"
echo approve disable-rule "readFile"

# Clear pending
echo approve clear

Development Tracks

# Create a new track
echo track new "project-x" --description "Project X development"

# List tracks
echo track list

# Switch to a track
echo track switch "project-x"

# Show current track
echo track status

# Configure track
echo track config "project-x" --provider openai --context-length 20

# Delete a track
echo track delete "project-x"

# Export/Import
echo track export "project-x" -o track.json
echo track import track.json

Dashboard

# Launch interactive TUI dashboard
echo dashboard

Clear History

echo clear history    # Clear current session
echo clear session    # Delete current session entirely
echo clear all        # Delete everything (irreversible!)

MCP (Model Context Protocol)

echo mcp list                  # List MCP servers
echo mcp add github https://...  # Add server
echo mcp enable github         # Enable server
echo mcp disable github        # Disable server
echo mcp remove github         # Remove server
echo mcp install @echo/github  # Install skill package
echo mcp skills                # List installed skills

Plugins

# Sync from other AI CLIs
echo plugin sync-all           # Sync from Claude, Gemini, Qwen
echo plugin sync-from claude   # Sync from Claude only
echo plugin sync-from gemini   # Sync from Gemini only
echo plugin sync-from qwen     # Sync from Qwen only

# Manage plugins
echo plugin list               # List installed plugins
echo plugin install <package>  # Install from npm
echo plugin uninstall <name>   # Remove a plugin
echo plugin enable <name>      # Enable a plugin
echo plugin disable <name>     # Disable a plugin

Configuration

echo config show                    # Show config
echo config set default-provider gemini
echo config set smart-mode true
echo config set context-length 10

📁 ECHO.md Context

Place an ECHO.md file in your project root to define:

Tech stack
Coding standards
Project rules
Custom instructions

Echo reads this automatically and adapts its responses.

Template:

## Project Name
My API Service

## Description
REST API with authentication

## Tech Stack
- Node.js
- Express
- PostgreSQL
- TypeScript

## Project Rules
- Always use async/await
- Write tests first
- Use ESLint

## Coding Standards
- 2 space indentation
- Single quotes
- Semicolons required

🔒 Security

Command Execution Safety

Echo blocks these patterns by default:

rm -rf /
rm -rf *
dd if=/dev/zero
Fork bombs
Format commands
wget | sh (download and execute)

Confirmation Prompts

By default, Echo asks for confirmation before:

Running shell commands
Writing files
Deleting files
Executing code

Use --yolo mode only when you trust the task completely.

API Key Security

Keys stored with machine-specific encryption
Never logged or displayed in full
Can be rotated anytime with echo auth logout

🏗 Architecture

echoctl/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── commands/             # CLI commands
│   │   ├── auth.ts           # Authentication
│   │   ├── chat.ts           # Chat & sessions
│   │   ├── agent.ts          # Agent management
│   │   ├── brain.ts          # Second Brain
│   │   ├── approve.ts        # HITL approvals
│   │   ├── track.ts          # Development tracks
│   │   ├── plugin.ts         # Plugin sync
│   │   └── tui.ts            # Dashboard
│   ├── core/
│   │   └── engine.ts         # ReAct engine
│   ├── providers/            # AI providers (14)
│   ├── tools/                # Tool executors
│   ├── storage/              # Data persistence
│   │   ├── sessions.ts       # Session storage
│   │   ├── brain.ts          # Knowledge base
│   │   ├── approvals.ts      # HITL queue
│   │   ├── tracks.ts         # Track isolation
│   │   └── mcp.ts            # MCP servers
│   ├── utils/                # Utilities
│   │   ├── config.ts         # Config management
│   │   ├── smart-mode.ts     # Task classifier
│   │   └── security.ts       # Security checks
│   └── tui/                  # TUI components
│       └── dashboard.tsx     # Ink dashboard
├── tests/                    # Jest tests
└── ECHO.md.template          # Context template

🧪 Testing

# Run all tests
npm test

# With coverage
npm run test:coverage

# Watch mode
npm run test:watch

Current Coverage: ~40% (target: 60%+)

🛠 Development

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Test
npm test

# Lint (coming soon)
npm run lint

📊 Roadmap

Completed (v1.0.0)

✅ 14 provider implementations
✅ Session storage with persistence
✅ Second Brain knowledge base
✅ HITL approval system
✅ Development track isolation
✅ Interactive TUI dashboard
✅ Security hardening (encryption, rate limiting)
✅ Smart mode task classification
✅ Comprehensive test suite

Planned (v2.0)

[ ] Voice input support
[ ] Image generation tools
[ ] Database tools (SQL, NoSQL)
[ ] Enhanced LSP integration
[ ] Multi-agent collaboration
[ ] WebSocket real-time updates
[ ] Plugin marketplace

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests: npm test
Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

ReAct pattern inspired by Google's ReAct paper
MCP integration following Model Context Protocol spec
TUI built with Ink - React for CLI