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?

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:

List available providers
Prompt for API keys (or skip if you'll use environment variables)
Let you choose a default provider
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

Config file (api_key field) — if set and non-null
Environment variable — GEMINI_API_KEY, ANTHROPIC_API_KEY, etc.
.env file — Legacy support: ~/.commandor/.env
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:

terminal_widget.py → _run_ai() → spawns worker thread
Worker calls agent_bridge.stream_agent_events()
stream_agent_events() builds LLM via lc_models.py, constructs graph via lc_graph.py, calls _iter_graph()
Events (ThinkingEvent, ToolCallEvent, ToolResultEvent, etc.) yielded back to UI
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:

Run /setup inside Commandor and enter your key
Set the environment variable (export GEMINI_API_KEY=...)
Edit ~/.commandor/config and add the key under the provider
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

Report bugs: Open an issue with steps to reproduce, expected vs actual behavior, environment details
Request features: Describe the use case and proposed solution
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:

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: ravin.d3107@outlook.com
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! 🚀

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets		assets
commandor		commandor
examples/commandor_weather		examples/commandor_weather
tests		tests
.gitignore		.gitignore
CONCEPT.md		CONCEPT.md
Dockerfile		Dockerfile
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation

Commandor

🤖 Agentic CLI — Autonomous Coding Assistant

✨ Why Commandor?

🎯 Agent Modes

What's new in 0.3.0

🧠 Intelligent Context Management

@File References

Persistent Sessions

Real-time Metrics

🤖 Multi-Provider Support

🔧 Built-in Tools

File Operations

Search & Discovery

Shell & System

Web, Git & Delegation

Session & Project

📦 Installation

Prerequisites

From PyPI (Recommended)

From Source (Development)

Optional Dependencies

🔑 API Key Setup

Interactive Setup (Recommended)

Manual Configuration

Environment Variables

🚀 Usage

Interactive Terminal (TUI)

Command-Line Mode (Non-Interactive)

⌨️ Command Reference

AI Commands

Provider & Model Management

Session Management

Configuration & Help

Export & Utilities

Shell Commands

🎨 User Interface

Visual Design

Key Bindings

Context Window Bar

⚙️ Configuration

Config File Location

Configuration Schema

Precedence Order for API Keys

📦 Docker Support

Pull the Image

Run Interactively

With API Keys (Recommended)

Mount Your Project

Build from Source

🏗️ Project Structure

Key Architecture Insights

🧪 Examples

Basic File Operations

Project Exploration

Shell + AI Hybrid

Complex Agent Task

Session Management

🐛 Troubleshooting

"No API key found for provider 'X'"

"Command not found" after installation

Context window exceeded / Memory issues

"Corrupt checkpoint" errors

Tool execution fails (permission denied, file not found)

Textual UI glitches / display issues

Provider-specific errors

🧪 Testing

Run the test suite

Manual smoke test

Test provider connectivity

🛠️ Development

Setting Up a Dev Environment

Code Style

Pre-commit Hooks (optional)

Building & Publishing

🤝 Contributing

How to Contribute