Epsilon CLI brings the power of agentic AI directly to your terminal. It goes beyond simple chat — it reads your code, writes files, runs commands, and searches your codebase semantically, all through an interactive TUI powered by Google Gemini.

✨ Highlights

• 🤖 Agentic Loop — Automatically plans and executes multi-step tasks (up to 15 iterations)
• 🔧 8 Built-in Tools — File I/O, folder operations, command execution, and semantic search
• 🔍 Local Semantic Search — Find code by meaning, not just keywords, using transformer-based embeddings
• 💬 Interactive TUI — Beautiful terminal interface built with Ink and React
• 🔐 Secure Auth — Authenticate via the Epsilon web platform using device authorization flow
• 🌐 Cloud & Local Modes — Use your Epsilon account or a local Gemini API key

Installation

npm install -g @lwshakib/epsilon-cli

Or with your preferred package manager:

# pnpm
pnpm add -g @lwshakib/epsilon-cli

# yarn
yarn global add @lwshakib/epsilon-cli

Requires Node.js ≥ 20

Quick Start

# 1. Authenticate with the Epsilon platform (opens browser)
epsilon configure

# — or use a local Gemini API key instead —
epsilon local-configure

# 2. Launch the interactive AI shell
epsilon

That's it. Start typing prompts and watch Epsilon work.

Commands

| Command | Description | |---|---| | epsilon | Launch the interactive AI agent shell | | epsilon configure | Authenticate with the Epsilon web platform via device authorization | | epsilon local-configure | Set up a local Google Gemini API key | | epsilon logout | Sign out and clear locally stored session tokens |

Built-in Tools

When you give Epsilon a task, the AI agent can autonomously use these tools to get the job done:

| Tool | Description | |---|---| | read_file | Read file contents, with optional line-range selection | | write_file | Create or overwrite files (auto-creates directories) | | update_file | Surgically update specific line ranges in a file | | delete_file | Delete a file | | create_folder | Create directories (recursive) | | list_folder | List directory contents with file/directory type info | | execute_command | Run terminal commands with optional working directory | | semantic_search | Search code by meaning using local transformer embeddings |

How It Works

┌──────────────────────────────────────────────────┐
│                  Your Terminal                    │
│                                                  │
│  You: "Add error handling to the auth module"    │
│                                                  │
│  ┌────────────────────────────────────────────┐  │
│  │           Epsilon Agent Loop               │  │
│  │                                            │  │
│  │  1. Understand the task                    │  │
│  │  2. semantic_search → find auth files      │  │
│  │  3. read_file → inspect current code       │  │
│  │  4. update_file → add try/catch blocks     │  │
│  │  5. read_file → verify changes             │  │
│  │  6. Return summary to you                  │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
│  ✅ Done! Added error handling to 3 files.       │
└──────────────────────────────────────────────────┘

The agent loop runs for up to 15 iterations per task, giving the AI enough room to plan, execute, and verify multi-step changes.

Configuration

All configuration is stored in ~/.epsilon/cli/.

| File | Purpose | |---|---| | config.json | API keys, auth tokens, and session data |

Authentication Options

Option A — Epsilon Platform (recommended):

epsilon configure

Opens your browser for secure device authorization with the Epsilon web platform. Your session token is stored locally.

Option B — Local API Key:

epsilon local-configure

Paste your Google Gemini API key directly. No account required.

Tech Stack

| Component | Technology | |---|---| | CLI Framework | Commander.js | | Terminal UI | Ink + React | | AI Model | Google Gemini via @google/genai | | Embeddings | @xenova/transformers | | Auth | better-auth device flow | | Language | TypeScript |

Part of the Epsilon Ecosystem

Epsilon CLI is one piece of a larger platform:

| App | Description | |---|---| | Epsilon Web | Dashboard for managing agents, billing, and settings | | Epsilon IDE | Electron-based desktop code editor | | Epsilon CLI | ← You are here |

Contributing

We welcome contributions! Please see the Contributing Guide and Code of Conduct.

License

MIT © Shakib Khan