commandor-ai 0.2.1

Agentic CLI - Autonomous coding assistant with multi-provider AI support

Commandor

🤖 Agentic CLI — Autonomous Coding Assistant

AI-powered terminal assistant that autonomously implements features, fixes bugs, refactors code, writes tests, and manages files — all from a single unified terminal interface.

---

✨ Why Commandor?

---

🎯 Agent Modes

Commandor offers two distinct interaction modes:

Mode	Command	Description
Agent	/agent <task>	Autonomous AI that uses all available tools to complete tasks. The AI decides how to accomplish the goal and executes autonomously.
Chat	/chat <message>	Pure conversation — no tool access. Use for questions, explanations, code reviews, or brainstorming.

---

🧠 Intelligent Context Management

@File References

Inline file contents directly into your prompts without manual copying:

/agent refactor this function: @src/utils.py
/agent write tests for @app/models.py
/chat explain @Dockerfile

Supports glob patterns too:

/agent fix all type errors in @**/*.py

Persistent Sessions

• Auto-save: Every conversation is automatically saved with a unique thread ID
• Name & organize: Use /sessions save <name> to name important sessions
• Resume later: /sessions resume <name> continues where you left off
• Multiple sessions: Keep separate contexts for different projects or tasks
• Checkpoint storage: Uses SQLite (~/.commandor/checkpoints.db) for durability

Real-time Metrics

Watch token usage and performance as you work:

• Context window usage (with visual progress bar)
• Input/output token counts
• Context condensation events (when history is summarized to save space)
• Model name and execution time

---

🤖 Multi-Provider Support

Commandor works with the leading AI providers. Configure one or all:

Provider	Models	Setup
Google Gemini	gemini-2.5-flash, gemini-2.5-pro, gemini-1.5-pro, gemini-1.5-flash	GEMINI_API_KEY
Anthropic Claude	claude-3-5-sonnet-20241022, claude-3-7-sonnet-20250219, claude-3-opus-20240229, claude-3-5-haiku-20241022	ANTHROPIC_API_KEY
OpenAI GPT	gpt-4o, gpt-4o-mini, gpt-4-turbo, o1, o3-mini	OPENAI_API_KEY
OpenRouter	100+ models (including anthropic/claude-3.5-sonnet, google/gemini-2.5-pro)	OPENROUTER_API_KEY

Switch providers on the fly with /provider <name> and models with /model <id>.

---

🔧 Built-in Tools

The agent has access to a comprehensive toolkit for software development:

File Operations

• read_file_tool — Read files with optional line ranges
• write_file_tool — Create or overwrite files (with diff preview)
• edit_file_tool — Surgical string replacement (preserves formatting)
• patch_file_tool — Apply unified diffs (uses patch command or pure-Python fallback)

Search & Discovery

• glob_tool — Find files by pattern (e.g., **/*.py, *.ts)
• grep_tool — Search file contents with regex
• list_directory_tool — Explore directory structure
• get_project_files_tool — List all source files by extension

Shell & System

• run_command_tool — Execute shell commands (with timeout protection)
• cd_tool — Change working directory (native support, updates prompt)
• get_directory_tool — Get current working directory
• get_git_info_tool — Git status, branch, recent commits
• get_environment_tool — OS, Python version, shell, user info

Session & Project

• get_project_files_tool — Enumerate project source files
• Session management via /sessions commands (see below)

All tools include rich diff displays when modifying files, so you always see exactly what changed.

---

📦 Installation

Prerequisites

• Python 3.9 or higher
• API key from at least one supported provider (Gemini, Anthropic, OpenAI, or OpenRouter)

From PyPI (Recommended)

pip install commandor-ai

From Source (Development)

git clone https://github.com/ravin-d-27/Commandor.git
cd Commandor
pip install -e .

Optional Dependencies

For enhanced experience, install additional packages:

pip install commandor-ai[dev]  # Testing & linting tools

On Windows, pyreadline3 is automatically installed for better command-line editing.

---

🔑 API Key Setup

Interactive Setup (Recommended)

Launch Commandor and run the setup wizard:

commandor
/setup

The wizard will:

1. List available providers
2. Prompt for API keys (or skip if you'll use environment variables)
3. Let you choose a default provider
4. Save everything to ~/.commandor/config

Manual Configuration

Edit the config file directly:

# Create the config directory
mkdir -p ~/.commandor

# Edit config
nano ~/.commandor/config

Example config:

default_provider: openrouter

providers:
  gemini:
    enabled: true
    api_key: null  # Will fall back to GEMINI_API_KEY env var
    default_model: gemini-2.5-flash
  
  anthropic:
    enabled: true
    api_key: "your-key-here"  # Can store directly (file protected at 600)
    default_model: claude-3.5-sonnet-20241022
  
  openai:
    enabled: true
    api_key: null
    default_model: gpt-4o
  
  openrouter:
    enabled: true
    api_key: null
    default_model: anthropic/claude-3.5-sonnet

agent:
  max_iterations: 50
  max_tokens_per_response: 4096
  confirm_destructive: true
  auto_scroll: true

ui:
  color_scheme: auto
  show_thinking: true
  verbose: true

Environment Variables

You can also set API keys via environment variables (takes precedence over config file):

export GEMINI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export OPENROUTER_API_KEY="your-key"

---

🚀 Usage

Interactive Terminal (TUI)

Launch the full Textual UI:

commandor

Features:

• Single-pane terminal: shell commands and AI chat coexist
• Real-time streaming of AI responses and tool outputs
• Command history (↑/↓)
• Tab completion for slash commands
• Rich syntax highlighting and markdown rendering

Quick start:

# Run a shell command
ls -la

# Ask a question
/chat what's the difference between async/await and threads?

# Autonomous task
/agent refactor this codebase to use type hints

# Use file references
/agent write tests for @src/main.py

Command-Line Mode (Non-Interactive)

Run a single task without entering the TUI:

# Autonomous agent
commandor -a "fix the bug in main.py"
commandor --agent "add comprehensive tests for the auth module"

# Chat mode
commandor --chat "explain how LangGraph works"

Options:

• -p, --provider <name> — Override the default provider
• -m, --model <id> — Use a specific model
• --setup — Run the interactive configuration wizard
• --version — Show version information

Examples with provider/model selection:

commandor -a "review this PR" -p anthropic -m claude-3-7-sonnet-20250219
commandor --chat "explain quantum computing" -p openai -m o1

---

⌨️ Command Reference

AI Commands

Command	Mode	Description
/agent <task>	Agent	Execute task independently using all tools
/chat <message>	Chat	Conversational Q&A (no tools)
/retry	Any	Re-run the last AI command
/reset	Any	Clear conversation memory, start fresh session

Provider & Model Management

Command	Description
/providers	List all providers with configuration status
/provider <name>	Switch active provider (gemini, anthropic, openai, openrouter)
/model <id>	Set model for current provider (e.g., claude-3-7-sonnet-20250219)

Session Management

Command	Description
/sessions	List all saved sessions with metadata
/sessions save <name>	Name the current session
/sessions new <name>	Create fresh named session and switch to it
/sessions resume <name>	Switch to a saved session (loads its conversation history)
/sessions rename <old> <new>	Rename a session
/sessions delete <name>	Delete a session and its checkpoints

Configuration & Help

Command	Description
/setup	Interactive API key configuration wizard
/setup <provider>	Configure a specific provider (e.g., /setup anthropic)
/help	Show comprehensive help with all commands
/clear or Ctrl+L	Clear the terminal screen
/exit or Ctrl+Q	Exit Commandor

Export & Utilities

Command	Description
/export [filename]	Save conversation as Markdown (default: commandor-YYYYMMDD-HHMMSS.md)

---

Shell Commands

Any input that doesn't start with / is executed as a shell command in the current working directory.

Special handling:

• cd <path> — Changes the working directory natively (no subprocess). Supports ~, relative paths, and environment variable expansion.
• All other commands run in your default shell ($SHELL or /bin/bash)

Examples:

# Navigate
cd ~/projects/myapp

# Git operations
git status
git diff HEAD~1

# Package managers
npm install
pip install -r requirements.txt

# Build & test
pytest tests/
python -m pytest --cov

# Project exploration
find . -name "*.py" | head -20
ls -R | grep ".js"

---

🎨 User Interface

Visual Design

• Theme: Batman-inspired dark mode (black background, gold accents)
• Layout: Single-pane terminal with input at bottom
• Streaming: Real-time token-by-token response rendering
• Panels:
  • Status bar (top): provider, model, context usage, session name
  • Log area (center): conversation history, tool outputs, errors
  • Stream preview (bottom, temporary): live "thinking" indicator

Key Bindings

Key	Action
↑ / ↓	Navigate command history
Tab	Auto-complete slash commands
Ctrl+L	Clear screen
Ctrl+Q	Quit

Context Window Bar

The status bar displays context usage with a visual progress bar:

▓▓▓▓▓░░░░ 12.3k/128k (9%)  ← 12.3k tokens used of 128k limit

• Automatically detects model context limits
• Shows percentage of context window used
• Updates in real-time as conversation grows

When usage exceeds 80% of the context window, Commandor automatically summarizes the conversation history to free up space (you'll see a small ↻ context condensed indicator).

---

⚙️ Configuration

Config File Location

• Linux/macOS: ~/.commandor/config
• Windows: %USERPROFILE%\.commandor\config

Configuration Schema

# Default provider (gemini, anthropic, openai, openrouter)
default_provider: openrouter

# Provider-specific settings
providers:
  gemini:
    enabled: true              # Enable/disable this provider
    api_key: null             # null = use GEMINI_API_KEY env var
    default_model: gemini-2.5-flash
  
  anthropic:
    enabled: true
    api_key: null             # or set directly (file permissions: 600)
    default_model: claude-3.5-sonnet-20241022
  
  openai:
    enabled: true
    api_key: null
    default_model: gpt-4o
  
  openrouter:
    enabled: true
    api_key: null
    default_model: anthropic/claude-3.5-sonnet

# Agent behavior
agent:
  max_iterations: 50          # Maximum tool calls per task
  max_tokens_per_response: 4096  # Max tokens per LLM response
  confirm_destructive: true   # Always ask before rm, drop_db, etc.
  auto_scroll: true           # Auto-scroll log during streaming

# UI settings
ui:
  color_scheme: auto          # auto/dark/light (Textual theme)
  show_thinking: true         # Show AI reasoning blocks
  verbose: true               # Show detailed tool output

Precedence Order for API Keys

1. Config file (api_key field) — if set and non-null
2. Environment variable — GEMINI_API_KEY, ANTHROPIC_API_KEY, etc.
3. .env file — Legacy support: ~/.commandor/.env
4. None — Provider will be marked as unconfigured

---

📦 Docker Support

Pull the Image

docker pull ravind2704/commandor:latest

Run Interactively

docker run -it ravind2704/commandor

With API Keys (Recommended)

docker run -it \
  -e GEMINI_API_KEY=your_key \
  -e ANTHROPIC_API_KEY=your_key \
  -e OPENAI_API_KEY=your_key \
  -e OPENROUTER_API_KEY=your_key \
  ravind2704/commandor

Mount Your Project

# Mount current directory into container
docker run -it \
  -v $(pwd):/workspace \
  -w /workspace \
  -e OPENAI_API_KEY=your_key \
  ravind2704/commandor

Build from Source

docker build -t commandor .
docker run -it commandor

---

🏗️ Project Structure

Commandor/
├── commandor/                    # Main package
│   ├── __init__.py               # Package metadata
│   ├── __main__.py               # CLI entry point (argparse, TUI launcher)
│   ├── main.py                   # Legacy terminal entry (kept for compatibility)
│   ├── textual_app.py            # Textual TUI application
│   ├── agent_bridge.py           # Streaming event bridge (TUI ↔ LangGraph)
│   ├── config.py                 # ConfigManager, setup wizard, API key resolution
│   ├── api_manager.py            # (deprecated — functionality moved to config.py)
│   ├── session_manager.py        # Named session persistence (JSON registry)
│   │
│   ├── agent/                    # Agent core (singular, not plural)
│   │   ├── __init__.py
│   │   ├── executor.py           # run_agent(), _run_* mode runners, metrics
│   │   ├── lc_graph.py           # LangGraph factory (build_agent_graph, etc.)
│   │   ├── lc_models.py          # build_model() — provider model factory
│   │   ├── lc_tools.py           # All @tool-decorated functions
│   │   └── modes.py              # Mode descriptions
│   │
│   ├── providers/                # AI provider integrations
│   │   ├── __init__.py
│   │   └── base.py               # AgentResult dataclass, provider base
│   │   # Note: Provider-specific logic (gemini, anthropic, openai, openrouter)
│   │   # is handled by LangChain integrations in agent/lc_models.py
│   │
│   ├── utils/                    # Utility modules
│   │   ├── __init__.py
│   │   ├── file_ops.py           # Low-level file read/write/edit/patch
│   │   ├── shell.py              # Shell execution, cd, git, env info
│   │   └── diff_display.py       # Rich diff rendering for file changes
│   │
│   └── widgets/                  # Textual UI components
│       ├── __init__.py
│       └── terminal_widget.py    # Main unified terminal (shell + AI)
│
├── tests/                        # Test suite (if exists)
├── pyproject.toml                # Modern Python packaging
├── setup.py                      # Legacy setuptools (still used for install)
├── requirements.txt              # Dev dependencies (optional)
├── Dockerfile                    # Container image definition
├── LICENSE                       # MIT License
└── README.md                     # This file

Key Architecture Insights

LangGraph Integration:

• Uses create_react_agent() from LangGraph for ReAct pattern
• Checkpointer: SqliteSaver at ~/.commandor/checkpoints.db for persistence
• Thread IDs scoped by mode: {mode}_{uuid} to separate chat/agent/plan histories

Provider Integration:

• All provider logic (Gemini, Anthropic, OpenAI, OpenRouter) is in agent/lc_models.py
• Uses LangChain's ChatGoogleGenerativeAI, ChatAnthropic, ChatOpenAI integrations
• No separate provider modules — single factory function build_model() handles all providers

Streaming Pipeline:

1. terminal_widget.py → _run_ai() → spawns worker thread
2. Worker calls agent_bridge.stream_agent_events()
3. stream_agent_events() builds LLM via lc_models.py, constructs graph via lc_graph.py, calls _iter_graph()
4. Events (ThinkingEvent, ToolCallEvent, ToolResultEvent, etc.) yielded back to UI
5. TerminalWidget._on_ai_event() renders each event type with Rich formatting

Context Summarization:

• Hook _make_summarize_hook() runs before each LLM call
• Checks _approx_tokens(messages) against threshold (80% of context window)
• If exceeded, summarizes old messages into a single HumanMessage with summary
• Prevents context overflow while preserving key information

Session Management:

• session_manager.py maintains a JSON registry at ~/.commandor/sessions.json
• Maps human-readable names to thread IDs (UUIDs)
• Checkpoints are stored in SQLite and survive restarts
• Sessions can be saved, resumed, renamed, and deleted via /sessions commands

---

🧪 Examples

Basic File Operations

# Read a file
/chat show me the contents of @commandor/config.py

# Create a new module
/agent create a new module @utils/helpers.py with functions for validation

# Edit a file
/agent in @app/main.py, replace the print statement with proper logging

# Apply a patch
/agent apply this diff to @src/components/Button.tsx:
# --- a/src/components/Button.tsx
# +++ b/src/components/Button.tsx
# @@ -10,7 +10,7 @@
# -  return <button className="btn">{children}</button>
# +  return <button className="btn primary">{children}</button>

Project Exploration

# Find all test files
/agent find all test files in the project

# Search for a function
/chat where is the authenticate_user function defined?

# Understand architecture
/plan analyze the project structure and document the main components

Shell + AI Hybrid

# Check git status first
git status

# Then ask AI to fix conflicts
/agent resolve the git conflicts in @src/auth.py

# Run tests, then fix failures
pytest tests/ -v
/agent fix the failing tests and re-run

Complex Agent Task

/agent implement OAuth2 login

# The agent will autonomously:
# 1. Explore the codebase
# 2. Create necessary files
# 3. Implement the feature
# 4. Run tests to verify

Session Management

# Start a task
/agent implement OAuth2 login

# Name it for later
/sessions save oauth-login

# Later, resume
/sessions resume oauth-login

# List all sessions
/sessions

# Delete old session
/sessions delete old-project

---

🐛 Troubleshooting

"No API key found for provider 'X'"

Cause: The provider isn't configured with an API key.

Solutions:

1. Run /setup inside Commandor and enter your key
2. Set the environment variable (export GEMINI_API_KEY=...)
3. Edit ~/.commandor/config and add the key under the provider
4. Test status: /providers (shows ✓/✗ for each)

"Command not found" after installation

Cause: Scripts directory not in PATH or virtual environment not activated.

Solutions:

# Check if installed
pip show commandor-ai

# If in venv, activate it
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Or use full path
python -m commandor

Context window exceeded / Memory issues

Cause: Very long conversations can hit model token limits.

Solutions:

• Commandor auto-summarizes at 80% capacity, but you can also:
  • Use /reset to start fresh
  • Start a new session: /sessions new <name>
  • Use a model with larger context (e.g., gemini-2.5-pro has 2M tokens)

"Corrupt checkpoint" errors

Cause: SQLite database corruption (rare, usually from abrupt termination).

Solutions:

• Delete ~/.commandor/checkpoints.db — Commandor will recreate it
• Sessions themselves (in ~/.commandor/sessions.json) are safe to keep

Tool execution fails (permission denied, file not found)

Tips:

• Always use cd_tool to navigate to the correct project directory first
• Check file paths are relative to CWD (shown in prompt)
• Some tools require files to exist; use list_directory_tool to verify
• For shell commands, ensure you have execute permissions

Textual UI glitches / display issues

Solutions:

• Update Textual: pip install -U textual
• Try a different color scheme: edit ~/.commandor/config, set ui.color_scheme: dark
• Disable live streaming: set ui.verbose: false
• Run with TERM=xterm-256color if colors are broken

Provider-specific errors

• Gemini: Ensure API key has Generative Language API enabled
• Anthropic: Check you're using an API key from console.anthropic.com
• OpenAI: Verify organization and billing are set up
• OpenRouter: Some models require credits; check your balance

---

🧪 Testing

Run the test suite

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# With coverage
pytest --cov=commandor

Manual smoke test

# Quick interactive test
commandor
/setup  # configure a provider
/agent create a simple Python hello world script

Test provider connectivity

# From Python
from commandor.agent.executor import test_providers
results = test_providers()
print(results)
# Output: {'gemini': {'status': 'ok'}, 'anthropic': {'status': 'no_api_key'}, ...}

---

🛠️ Development

Setting Up a Dev Environment

# Clone
git clone https://github.com/ravin-d-27/Commandor.git
cd Commandor

# Create venv
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install in editable mode with dev deps
pip install -e ".[dev]"

# Run locally
commandor --version

Code Style

• Python: Follow PEP 8, use ruff for linting
• Imports: Sort with ruff or isort
• Types: Use type hints (checked with mypy)
• Commits: Conventional Commits recommended (feat:, fix:, docs:, etc.)

Pre-commit Hooks (optional)

pip install pre-commit
pre-commit install
# Runs ruff, mypy, etc. on staged files

Building & Publishing

# Build distribution
pip install build
python -m build

# Check
twine check dist/*

# Upload to PyPI (maintainers only)
twine upload dist/*

---

🤝 Contributing

Contributions are welcome and appreciated!

How to Contribute

1. Report bugs: Open an issue with steps to reproduce, expected vs actual behavior, environment details
2. Request features: Describe the use case and proposed solution
3. Submit PRs:
   • Fork the repo
   • Create a feature branch (git checkout -b feat/amazing-feature)
   • Make changes, add tests if applicable
   • Ensure tests pass (pytest)
   • Open a PR with clear description

Areas Needing Help

• Support for more providers (Groq, Together, etc.)
• Enhanced diff viewer (side-by-side, syntax highlighting)
• Export formats (JSON, HTML, PDF)
• Plugin system for custom tools
• Windows-specific improvements
• Performance optimizations for large repos
• Better error recovery and retry logic

Code of Conduct

Please be respectful and constructive. Harassment or toxic behavior will not be tolerated.

---

📜 License

MIT License — see LICENSE file for full text.

Short version: Use this software for any purpose, modify it, distribute it. Just include the original license and copyright notice.

---

🙏 Acknowledgments

Built with these amazing open-source projects:

• LangGraph — Agent orchestration
• Textual — TUI framework
• Rich — Terminal formatting
• LangChain — LLM abstractions
• OpenAI / Anthropic / Google — Model providers

---

📞 Contact

Author: Ravin D

• GitHub: https://github.com/ravin-d-27
• Email: [e-mail]
• Issues: https://github.com/ravin-d-27/Commandor/issues

---

⭐ Support

If you find Commandor useful, please consider:

• Starring the repository on GitHub
• Reporting bugs and suggesting improvements
• Sharing with your network
• Contributing code or documentation

Your support helps keep the project alive! 🚀