Skip to main content

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

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.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 files

0.2.1

2 files

0.2.0

2 files

0.0.1

2 files

Supported by

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