Skip to main content

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

Project description

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.

GitHub stars License Python LangGraph Textual


โœจ Why Commandor?

Commandor keeps coding work inside one terminal surface: describe a task in plain English, attach files with @, let the agent inspect and edit the project, and keep shell/git/session workflows close at hand. It is built for practical developer loops rather than a separate chat window.


๐ŸŽฏ Agent Modes

Commandor defaults to natural agent tasks in the TUI. Type what you want done, or use slash commands when you want a specific mode.

Mode Command Description
Agent Plain text or /agent <task> Autonomous AI that uses all available tools to complete tasks. The AI decides how to accomplish the goal and executes autonomously.
Assist /assist <task> Agent mode with confirmation before tool execution.
Plan /plan <task> Generate a plan first, then execute after approval.
Chat /chat <message> Pure conversation โ€” no tool access. Use for questions, explanations, code reviews, or brainstorming.

What's new in 0.3.0

  • Natural TUI input: plain messages run as agent tasks by default.
  • @ file references with live file suggestions and Tab completion.
  • More providers: Ollama, Groq, DeepSeek, and OpenAI-compatible endpoints.
  • Plugin tools via the commandor.tools entry-point group.
  • Sub-agent delegation tools for focused or parallel work.
  • Web/HTTP, git, multimodal image, JSON/HTML export, .commandorignore, and side-by-side diff support.

๐Ÿง  Intelligent Context Management

@File References

Inline file contents directly into your prompts without manual copying:

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

Supports glob patterns too:

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

In the TUI, type @ to browse project files. Continue typing to narrow the list and press Tab to complete the active file reference. Paths with spaces are inserted as quoted references, for example @"docs/My File.md".

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
Ollama Local models such as llama3.1, qwen2.5-coder, codellama No API key; local Ollama server
Groq llama-3.3-70b-versatile, mixtral-8x7b-32768 GROQ_API_KEY
DeepSeek deepseek-chat, deepseek-reasoner DEEPSEEK_API_KEY
OpenAI-compatible LM Studio, vLLM, llama.cpp server, custom endpoints Base URL + optional 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

Web, Git & Delegation

  • fetch_url_tool โ€” Fetch web pages as text for documentation and research
  • http_request_tool โ€” Send HTTP requests to APIs and webhooks
  • git_status_tool, git_diff_tool, git_commit_tool, git_log_tool โ€” Inspect and manage git state
  • delegate_task_tool โ€” Spawn a focused sub-agent for a self-contained task
  • parallel_delegate_tool โ€” Run multiple focused sub-agent tasks concurrently

Session & Project

  • get_project_files_tool โ€” Enumerate project source files
  • Session management via /sessions commands (see below)
  • Plugin tools loaded from installed packages using the commandor.tools entry-point group

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 hosted provider, or a local Ollama server for keyless local models

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"
export GROQ_API_KEY="your-key"
export DEEPSEEK_API_KEY="your-key"

๐Ÿš€ Usage

Interactive Terminal (TUI)

Launch the full Textual UI:

commandor

Features:

  • Single-pane terminal: natural agent tasks, shell commands, and AI chat coexist
  • Real-time streaming of AI responses and tool outputs
  • Command history (โ†‘/โ†“)
  • Tab completion for slash commands and @ file references
  • Rich syntax highlighting and markdown rendering

Quick start:

# Ask the agent naturally
read the unit tests and explain the structure

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

# Autonomous task
refactor this codebase to use type hints

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

# Run a shell command
$ ls -la

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
Plain text Agent Execute a task naturally using all tools
/agent <task> Agent Execute task independently using all tools
/assist <task> Assist Execute with confirmations before tool calls
/plan <task> Plan Produce a plan before execution
/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, ollama, groq, deepseek, openai_compat)
/model <id> Set model for current provider (e.g., claude-3-7-sonnet-20250219)
/api show Show provider configuration
/api set <provider> <key> Save an API key
/api url <provider> <url> Set a custom provider base URL
/api test [provider] Test provider connectivity

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
/diff [--staged] [path] Show git diff in the TUI
/image <path> [path ...] Attach image(s) to the next AI run
/plugins [reload] List or reload plugin tools
`/export [md json

Shell Commands

Plain text runs the agent. Prefix shell commands with $ or ! to execute them 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 and active @ file references
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, ollama, groq, deepseek, openai_compat)
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
    base_url: https://openrouter.ai/api/v1

  ollama:
    enabled: true
    api_key: null
    default_model: llama3.1
    base_url: http://localhost:11434

  groq:
    enabled: true
    api_key: null
    default_model: llama-3.3-70b-versatile

  deepseek:
    enabled: true
    api_key: null
    default_model: deepseek-chat
    base_url: https://api.deepseek.com/v1

  openai_compat:
    enabled: true
    api_key: null
    default_model: local-model
    base_url: http://localhost:1234/v1

# 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 \
  -e GROQ_API_KEY=your_key \
  -e DEEPSEEK_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
โ”‚   โ”‚   โ”œโ”€โ”€ plugins.py            # Entry-point plugin discovery
โ”‚   โ”‚   โ”œโ”€โ”€ subagent.py           # Delegate/parallel sub-agent execution
โ”‚   โ”‚   โ””โ”€โ”€ modes.py              # Mode descriptions
โ”‚   โ”‚
โ”‚   โ”œโ”€โ”€ providers/                # AI provider integrations
โ”‚   โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ”‚   โ””โ”€โ”€ base.py               # AgentResult dataclass, provider base
โ”‚   โ”‚   # Provider-specific logic is handled by LangChain integrations in agent/lc_models.py
โ”‚   โ”‚
โ”‚   โ”œโ”€โ”€ utils/                    # Utility modules
โ”‚   โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ”‚   โ”œโ”€โ”€ diff_side_by_side.py  # Side-by-side syntax-highlighted diffs
โ”‚   โ”‚   โ”œโ”€โ”€ exporter.py           # Markdown/JSON/HTML export helpers
โ”‚   โ”‚   โ”œโ”€โ”€ file_ops.py           # Low-level file read/write/edit/patch
โ”‚   โ”‚   โ”œโ”€โ”€ git_ops.py            # Git status/diff/log/commit helpers
โ”‚   โ”‚   โ”œโ”€โ”€ ignore.py             # .commandorignore matcher
โ”‚   โ”‚   โ”œโ”€โ”€ multimodal.py         # Image encoding for vision models
โ”‚   โ”‚   โ”œโ”€โ”€ shell.py              # Shell execution, cd, git, env info
โ”‚   โ”‚   โ”œโ”€โ”€ tokenizer.py          # tiktoken-based token counting
โ”‚   โ”‚   โ”œโ”€โ”€ web_ops.py            # URL fetch and HTTP request helpers
โ”‚   โ”‚   โ””โ”€โ”€ diff_display.py       # Rich diff rendering for file changes
โ”‚   โ”‚
โ”‚   โ””โ”€โ”€ widgets/                  # Textual UI components
โ”‚       โ”œโ”€โ”€ __init__.py
โ”‚       โ””โ”€โ”€ terminal_widget.py    # Main unified terminal (shell + AI)
โ”‚
โ”œโ”€โ”€ tests/                        # Pytest suite
โ”œโ”€โ”€ 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:

  • Provider logic for Gemini, Anthropic, OpenAI, OpenRouter, Ollama, Groq, DeepSeek, and OpenAI-compatible endpoints is in agent/lc_models.py
  • Uses LangChain's ChatGoogleGenerativeAI, ChatAnthropic, ChatOpenAI, ChatOllama, and ChatGroq 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
create a new module @utils/helpers.py with functions for validation

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

# Apply a patch
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
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
resolve the git conflicts in @src/auth.py

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

Complex Agent Task

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

  • PDF export
  • More plugin examples and templates
  • Provider presets for Together, Mistral, and other OpenAI-compatible APIs
  • 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:


๐Ÿ“ž Contact

Author: Ravin D


โญ 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! ๐Ÿš€

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

commandor_ai-0.3.0.tar.gz (115.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

commandor_ai-0.3.0-py3-none-any.whl (103.0 kB view details)

Uploaded Python 3

File details

Details for the file commandor_ai-0.3.0.tar.gz.

File metadata

  • Download URL: commandor_ai-0.3.0.tar.gz
  • Upload date:
  • Size: 115.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for commandor_ai-0.3.0.tar.gz
Algorithm Hash digest
SHA256 18177af55b90f59ed3f9d6274a181413ba9a923fe792788776a786b46bb324ab
MD5 cd38d483453c9f7697f307f81d85ec0c
BLAKE2b-256 94d7e0ad670d5c5c9a43b776122eaf1e6548b0d8ff4880a7e78a84121d8ed082

See more details on using hashes here.

File details

Details for the file commandor_ai-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: commandor_ai-0.3.0-py3-none-any.whl
  • Upload date:
  • Size: 103.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for commandor_ai-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c5b6bbda1ef8209744d49c0f1a31701b7a8ce76417058a7ba7754b670c6fa528
MD5 c7eb1834c709299d08626f3572fdfe41
BLAKE2b-256 829d883b59ee6eeeb40601565c19adf04878781fbca2a933ce53427a0e197ddd

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page