Metadata-Version: 2.4
Name: commandor-ai
Version: 0.2.1
Summary: Agentic CLI - Autonomous coding assistant with multi-provider AI support
Home-page: https://github.com/ravin-d-27/Commandor
Author: Ravin D
Author-email: Ravin D <ravin.d3107@outlook.com>
License: MIT
Project-URL: Homepage, https://github.com/ravin-d-27/Commandor
Project-URL: BugReports, https://github.com/ravin-d-27/Commandor/issues
Project-URL: Source, https://github.com/ravin-d-27/Commandor
Project-URL: Documentation, https://github.com/ravin-d-27/Commandor#readme
Keywords: terminal,ai,shell,command-line,natural-language,gemini,claude,gpt,assistant,automation,cli,productivity,agent,opencode,codex
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Classifier: Topic :: System :: System Shells
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-genai>=1.0.0
Requires-Dist: anthropic>=0.40.0
Requires-Dist: openai>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: langchain-core>=1.2.0
Requires-Dist: langgraph>=1.0.0
Requires-Dist: langchain-google-genai>=4.2.0
Requires-Dist: langchain-anthropic>=1.3.0
Requires-Dist: langchain-openai>=1.1.0
Requires-Dist: langgraph-checkpoint-sqlite>=3.0.0
Requires-Dist: prompt_toolkit>=3.0.0
Requires-Dist: textual>=0.80.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: windows
Requires-Dist: pyreadline3>=3.4.1; extra == "windows"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Commandor

<h3 align="center">🤖 Agentic CLI — Autonomous Coding Assistant</h3>

<p align="center">
  <strong>AI-powered terminal assistant</strong> that autonomously implements features, fixes bugs, refactors code, writes tests, and manages files — all from a single unified terminal interface.
</p>

[![GitHub stars](https://img.shields.io/github/stars/ravin-d-27/Commandor?style=social)](https://github.com/ravin-d-27/Commandor/stargazers)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://python.org)
[![LangGraph](https://img.shields.io/badge/LangGraph-ReAct-blue)](https://langchain-ai.github.io/langgraph/)
[![Textual](https://img.shields.io/badge/Textual-TUI-green)](https://textual.textualize.io/)

---

## ✨ 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:

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

Supports glob patterns too:
```bash
/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)
```bash
pip install commandor-ai
```

### From Source (Development)
```bash
git clone https://github.com/ravin-d-27/Commandor.git
cd Commandor
pip install -e .
```

### Optional Dependencies
For enhanced experience, install additional packages:
```bash
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:
```bash
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:
```bash
# Create the config directory
mkdir -p ~/.commandor

# Edit config
nano ~/.commandor/config
```

Example config:
```yaml
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):

```bash
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:
```bash
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:**
```bash
# 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:

```bash
# 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:
```bash
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:
```bash
# 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

```yaml
# 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
```bash
docker pull ravind2704/commandor:latest
```

### Run Interactively
```bash
docker run -it ravind2704/commandor
```

### With API Keys (Recommended)
```bash
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
```bash
# Mount current directory into container
docker run -it \
  -v $(pwd):/workspace \
  -w /workspace \
  -e OPENAI_API_KEY=your_key \
  ravind2704/commandor
```

### Build from Source
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
/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
```bash
# 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**:
```bash
# 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
```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# With coverage
pytest --cov=commandor
```

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

### Test provider connectivity
```bash
# 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
```bash
# 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)
```bash
pip install pre-commit
pre-commit install
# Runs ruff, mypy, etc. on staged files
```

### Building & Publishing
```bash
# 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](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](https://langchain-ai.github.io/langgraph/) — Agent orchestration
- [Textual](https://textual.textualize.io/) — TUI framework
- [Rich](https://rich.readthedocs.io/) — Terminal formatting
- [LangChain](https://www.langchain.com/) — LLM abstractions
- [OpenAI / Anthropic / Google](https://github.com) — 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! 🚀
