Omni CLI

Unified CLI wrapper for AI models - one interface for Claude, Codex/OpenAI, Gemini, and more.

Key Features: Multi-provider support • Hierarchical organization (Namespaces → Projects → Chats + Summaries) • Chat summarization & archiving • Context sharing • Persistent memory • Full-text search

Quick Start

Important: Omni CLI is a wrapper - you must install at least one AI provider first!

Step 1: Install an AI Provider

Choose at least one (recommended: start with Claude Code):

Claude Code (Recommended):

# Download from https://claude.ai/download
# Or install via package manager:
brew install --cask claude  # macOS

# Verify installation:
claude --version

OpenAI/Codex CLI:

# Install OpenAI CLI
pip install openai-cli

# Set API key:
export OPENAI_API_KEY="your-api-key"

# Verify:
openai --version

Google Gemini CLI:

# Install Gemini CLI
pip install google-generativeai

# Verify:
gemini --version

Step 2: Install Omni CLI

# Clone the repository
git clone https://github.com/yourusername/omni-cli.git
cd omni-cli

# Install dependencies
pip install -r requirements.txt

# Make executable
chmod +x src/main.py

# Run directly
python3 src/main.py

# Or create an alias in your ~/.bashrc or ~/.zshrc:
alias omni='python3 /path/to/omni-cli/src/main.py'

Step 3: Start Chatting

omni
omni> hello, can you help me with Python?

---

Commands Reference

Getting Started

Start a conversation:

omni
omni> hello, can you help me with Python?

Just type naturally - no command needed. Your chat is auto-saved with a generated name.

Get help:

omni> /help

Exit:

omni> /exit    # or /quit

---

Chat Management

Create a Named Chat

omni> /new my-feature-chat

Creates a new chat with a specific name instead of auto-generated.

With a project:

omni> /new authentication --project my-webapp

Creates a chat and adds it to a project in one command.

Browse & Manage with /list

omni> /list

Interactive browser for all your namespaces, projects, chats, and summaries:

📦 work-projects (2 projects)
  📁 api-service (3 chats, 1 summaries)
    💬 authentication               claude   5 msgs
    💬 user-management             claude   3 msgs
    📄 research-summary            claude   long summary
  📁 webapp (2 chats, 0 summaries)
    💬 frontend-design             claude   7 msgs

📦 learning (0 projects)

📁 Standalone Projects
  📁 side-project (1 chats, 0 summaries)

💬 Standalone Chats
  quick-question                   claude   1 msg

Interactive controls:

• ↑/↓: Navigate through items
• Enter: Resume chat or view summary (with formatted markdown)
• d: Delete item (with confirmation)
• r: Rename namespaces, projects, or chats
• Esc: Exit back to prompt

All actions loop back to the list, making it easy to manage multiple items!

Resume a Previous Chat

omni> /resume

Interactive menu with arrow keys to select which chat to continue:

• ↑/↓ to navigate
• Enter to select
• Esc to cancel

Filter by keyword:

omni> /resume authentication    # Shows only chats matching "authentication"
omni> /resume claude            # Shows only chats using Claude provider

Search Chats

omni> /find OAuth              # or /search OAuth

Searches through all chat content for "OAuth" and shows matching chats.

Delete a Chat

omni> /delete abc123           # By chat ID
omni> /delete my-chat-name     # By name

Shows confirmation before deleting.

Summarize & Archive Chats

omni> /summary my-chat-name
omni> /summary abc123 --type short

Condenses a chat into an AI-generated summary and archives it:

• Two summary types:
  • short: 50-100 word concise summary
  • long (default): Detailed summary with topics, solutions, code examples, and conclusions
• Original chat is deleted and replaced with a markdown summary file
• Summaries appear in /list with a 📄 icon
• Press Enter in /list to view summary with formatted markdown

Example workflow:

# Have a long research conversation
omni> /new oauth-research --project backend
omni> explain OAuth 2.0 flow in detail
# ... many messages ...

# Summarize when done to save space
omni> /summary oauth-research --type long
✓ Summary created: oauth-research
  Type: long
  Words: 234
  Original chat deleted

# View later in /list or search for it
omni> /list
# Press Enter on the summary to read it

Benefits:

• Saves storage space by condensing long conversations
• Creates searchable knowledge base of key insights
• Maintains project organization (summaries stay in their projects)
• AI-powered distillation captures important details

---

Organization: Namespaces & Projects

Organize your work with a four-level hierarchy:

• Namespaces → Group of related projects (e.g., "work-projects", "personal")
• Projects → Group of related chats and summaries (e.g., "api-service", "webapp")
• Chats → Individual active conversations
• Summaries → Archived, condensed versions of chats

Namespace Commands

Create a namespace:

omni> /namespace create work-projects
omni> /namespace create personal --description "Personal projects and learning"

List all namespaces:

omni> /namespace list

Add a project to a namespace:

omni> /namespace add work-projects my-webapp

List projects in a namespace:

omni> /namespace projects work-projects

Remove a project from a namespace:

omni> /namespace remove work-projects my-webapp

Delete a namespace:

omni> /namespace delete work-projects

Note: Deletes the namespace but preserves all projects.

Project Commands

Create a project:

omni> /project create my-webapp

Create a project in a namespace:

omni> /project create api-service --namespace work-projects

List all projects:

omni> /project list

Add a chat to a project:

omni> /project add my-webapp abc123

List chats in a project:

omni> /project chats my-webapp

Remove a chat from a project:

omni> /project remove my-webapp abc123

Delete a project:

omni> /project delete my-webapp

Note: Deletes the project but preserves all chats.

---

Provider Management

List Available Providers

omni> /providers

Shows which AI providers are installed and available:

Available Providers:
→ claude     ✓ installed
  codex      ✓ installed (OpenAI CLI)
  gemini     ✗ not installed

Switch Providers

omni> /use codex

Switches to Codex for subsequent messages. The new provider sees the full conversation history!

Example workflow:

omni> explain async/await in JavaScript
# Claude responds...

omni> /use codex
omni> can you give me a code example?
# Codex sees Claude's explanation and builds on it!

Consult Multiple Providers

omni> /consult codex explain the difference between async and defer

Sends your question to BOTH your current provider (e.g., Claude) and the specified provider (Codex), then:

1. Collects both responses
2. Uses your current provider to synthesize a merged answer
3. Shows you both individual responses for comparison

Perfect for complex questions where you want multiple perspectives!

---

Common Workflows

Workflow 1: Organized Project Development

# 1. Create a namespace for work projects
omni> /namespace create work-projects

# 2. Create projects in the namespace
omni> /project create api-service --namespace work-projects
omni> /project create webapp --namespace work-projects

# 3. Create chats within projects
omni> /new authentication --project api-service
omni> how do I implement OAuth 2.0 in Node.js?
# ... conversation continues ...

omni> /new database-design --project api-service
omni> what's the best schema for user authentication?

# 4. Later, resume to continue work
omni> /resume
# Navigate to your chat and press Enter

Workflow 2: Multi-Provider Comparison

# Ask Claude first
omni> what are the best practices for React state management?
# Claude responds...

# Get Codex's opinion
omni> /use codex
omni> what do you think about Redux vs Context API?
# Codex sees the full conversation and responds

# Get a merged perspective
omni> /use claude
omni> /consult codex summarize the key differences
# Get a synthesized answer from both providers

Workflow 3: Research and Knowledge Management

# Create a namespace for learning
omni> /namespace create learning --description "Personal learning projects"

# Create topic-specific projects
omni> /project create machine-learning --namespace learning
omni> /project create web3 --namespace learning

# Create focused chats for deep research
omni> /new neural-networks --project machine-learning
omni> explain backpropagation in simple terms
omni> how does gradient descent work?
omni> show me a simple neural network implementation
# ... lengthy conversation with code examples ...

# Summarize the research session to save space
omni> /summary neural-networks --type long
✓ Summary created: neural-networks
  Type: long
  Words: 312
  Original chat deleted

# Create more research chats
omni> /new transformers --project machine-learning
omni> explain transformer architecture
# ... another long conversation ...

# View all summaries in your project
omni> /list
# Navigate to machine-learning project
# See both chats and summaries organized together

# Later, search across summaries and chats
omni> /find "gradient descent"

---

Installation

Prerequisites

Required:

• Python 3.9 or higher
• pip (Python package manager)
• At least one AI provider installed (see Quick Start above)

Optional:

• Git for cloning the repository

Installation Steps

See the Quick Start section above for complete installation instructions, including:

1. Installing an AI provider (Claude Code, OpenAI CLI, or Gemini CLI)
2. Cloning and setting up Omni CLI
3. Creating an alias for easy access

Verify Installation

# Check Python version
python3 --version  # Should be 3.9+

# Check AI provider is installed
claude --version   # or openai --version, or gemini --version

# Run Omni CLI
python3 src/main.py

# Or if you created an alias:
omni

Troubleshooting

"No AI provider available" error:

• Make sure you've installed at least one AI provider
• Verify it's in your PATH: which claude (or which openai)
• Try running the provider directly: claude --version

Permission errors:

• Make sure main.py is executable: chmod +x src/main.py
• Check Python permissions: ls -la $(which python3)

Import errors:

• Install dependencies: pip install -r requirements.txt
• Use a virtual environment if needed:

  python3 -m venv venv
  source venv/bin/activate  # On Windows: venv\Scripts\activate
  pip install -r requirements.txt

---

Storage

All data is stored in ~/.omni/ as human-readable Markdown files with JSON indexes:

~/.omni/
├── chats/permanent/           # Standalone chats
├── summaries/                 # Standalone summaries
├── projects/                  # Project folders
│   └── my-webapp/
│       ├── chats/            # Chats in this project
│       └── summaries/        # Summaries in this project
├── namespaces/               # Namespace folders
├── index.json               # Chat index
├── summary_index.json       # Summary index
├── projects.json            # Project index
└── namespace_index.json     # Namespace index

File naming formats:

• Chats: YYYYMMDD-HHMMSS_chat-name.md
• Summaries: YYYYMMDD-HHMMSS_chat-name_summary.md

Summary file structure:

---
summary_id: abc12345
name: oauth-research
original_chat_id: xyz789
type: long
provider: claude
created_at: 2025-11-26T10:30:00
project: backend
word_count: 234
---

# Summary: oauth-research

**Type:** Long
**Generated:** 2025-11-26
**Original Chat:** xyz789

---

[AI-generated summary content with markdown formatting]

---

Tips & Tricks

1. Use descriptive names:

omni> /new api-authentication-research --project backend

2. Organize as you go: Create namespaces and projects early to keep things organized.

3. Summarize long conversations: After research or exploratory chats, use /summary to condense into searchable knowledge:

omni> /summary my-research --type long

4. Use keywords in /resume:

omni> /resume auth    # Quickly find authentication-related chats

5. Search is powerful:

omni> /find "error handling"    # Finds all discussions about errors

6. Browse with /list: Use the interactive /list command to navigate, view summaries, and manage everything in one place.

7. Switch providers for different tasks:

• Claude: Great for explanations and discussions
• Codex: Excellent for code generation
• Gemini: Good for diverse perspectives

---

Coming Soon

• /add-note - Add manual notes to chats, projects, or namespaces
• /ask --project - Ask questions scoped to specific projects
• /archive - Archive old chats without summarizing
• /merge - Merge and summarize multiple chats
• Artifacts support - Store code snippets, configs, and files in projects

See todo.md for full roadmap.

---

License

MIT

Contributing

Contributions welcome! Please open an issue or PR at github.com/omni-cli/omni