Metadata-Version: 2.4
Name: codecortex-ai
Version: 0.1.2
Summary: CodeCortex AI — autonomous coding agent for the terminal
Author: Tanishq Shukla
License: MIT
Keywords: ai,coding,agent,cli,openai,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openai
Requires-Dist: click
Requires-Dist: rich
Requires-Dist: pydantic
Requires-Dist: tomli
Requires-Dist: platformdirs
Requires-Dist: tiktoken
Requires-Dist: fastmcp
Requires-Dist: httpx
Requires-Dist: duckduckgo-search
Requires-Dist: python-dotenv

# 🧠 CodeCortex AI

**An autonomous AI coding agent that lives in your terminal.**

CodeCortex AI reads your code, writes files, runs commands, fixes bugs, and builds features — all from a simple chat interface.

[![PyPI version](https://img.shields.io/pypi/v/codecortex-ai.svg)](https://pypi.org/project/codecortex-ai/)
[![Python](https://img.shields.io/pypi/pyversions/codecortex-ai.svg)](https://pypi.org/project/codecortex-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 📦 Installation

```bash
pip install codecortex-ai
```

That's it! Now you can use `codecortex` from anywhere in your terminal.

---

## 🚀 Quick Setup (Step by Step)

When you run `codecortex` for the **first time**, it will ask you 3 things:

### Step 1: Get an API Key

You need an API key from any AI provider. We recommend **OpenRouter** because it has **free models**:

1. Go to [openrouter.ai/keys](https://openrouter.ai/keys)
2. Sign up / Log in (you can use Google)
3. Click **"Create Key"**
4. Copy the key (starts with `sk-or-...`)

> 💡 **Other providers also work:** OpenAI (`sk-proj-...`), Anthropic, Groq, Together AI — any OpenAI-compatible API.
>
> ⚠️ **Note:** OpenAI requires billing credits ($5 minimum). OpenRouter has free models — no payment needed.

### Step 2: Run CodeCortex

```bash
codecortex
```

It will show you a setup wizard:

```
╭──────────────────────────────────────────────╮
│       Welcome to CodeCortex AI               │
│       First-time setup                       │
╰──────────────────────────────────────────────╯

  Enter API Key: sk-or-v1-xxxxxxxxxxxx

  Enter Base URL (or press Enter to skip): https://openrouter.ai/api/v1

  Enter Model Name (or press Enter for default): mistralai/devstral-2512:free

  ✅ Configuration saved!
```

### Step 3: What to Enter

| Field | What to Enter | Example |
|-------|--------------|---------|
| **API Key** | Your API key from the provider | `sk-or-v1-abc123...` |
| **Base URL** | The API endpoint URL | `https://openrouter.ai/api/v1` |
| **Model Name** | Which AI model to use | `mistralai/devstral-2512:free` |

### 📋 Setup Examples for Different Providers

<details>
<summary><b>🟢 OpenRouter (Recommended — FREE models available)</b></summary>

```
API Key:    sk-or-v1-your-key-here
Base URL:   https://openrouter.ai/api/v1
Model:      mistralai/devstral-2512:free
```

**Free models on OpenRouter:**
| Model | Best For |
|-------|----------|
| `mistralai/devstral-2512:free` | Coding tasks (recommended) |
| `google/gemini-2.0-flash-exp:free` | General + coding |
| `meta-llama/llama-4-maverick:free` | General purpose |
| `qwen/qwen3-235b-a22b:free` | Coding + reasoning |

Get your key: [openrouter.ai/keys](https://openrouter.ai/keys)

</details>

<details>
<summary><b>🔵 OpenAI (Paid — requires $5+ credits)</b></summary>

```
API Key:    sk-proj-your-key-here
Base URL:   (leave empty, press Enter)
Model:      gpt-4o-mini
```

**Available models:**
| Model | Cost |
|-------|------|
| `gpt-4o-mini` | Cheapest, great for most tasks |
| `gpt-4o` | More powerful, costs more |
| `gpt-3.5-turbo` | Budget option |

> ⚠️ You must add billing credits at [platform.openai.com/settings/organization/billing](https://platform.openai.com/settings/organization/billing)

Get your key: [platform.openai.com/api-keys](https://platform.openai.com/api-keys)

</details>

<details>
<summary><b>🟡 Groq (Free tier available)</b></summary>

```
API Key:    gsk_your-key-here
Base URL:   https://api.groq.com/openai/v1
Model:      llama-3.3-70b-versatile
```

Get your key: [console.groq.com/keys](https://console.groq.com/keys)

</details>

<details>
<summary><b>🟠 Together AI</b></summary>

```
API Key:    your-key-here
Base URL:   https://api.together.xyz/v1
Model:      meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo
```

Get your key: [api.together.ai/settings/api-keys](https://api.together.ai/settings/api-keys)

</details>

---

## 💬 Usage

### Interactive Mode (chat with the agent)

```bash
codecortex
```

Then just type what you want:
```
> fix the bug in main.py
> add a login page to my app
> explain how this codebase works
> write unit tests for utils.py
```

### Single Command Mode

```bash
codecortex "fix the type error in app.py"
```

### Set Working Directory

```bash
codecortex --cwd ./my-project
```

---

## 🔧 All Commands

### Terminal Commands

| Command | What It Does |
|---------|-------------|
| `codecortex` | Start interactive chat mode |
| `codecortex "prompt"` | Run a single prompt and exit |
| `codecortex --cwd ./path` | Set working directory |
| `codecortex --reset` | **Delete saved config and re-enter API key, model, etc.** |
| `codecortex --help` | Show help |

### Chat Commands (type inside CodeCortex)

| Command | What It Does |
|---------|-------------|
| `/help` | Show all available commands |
| `/config` | Show current configuration (model, temperature, etc.) |
| `/model <name>` | **Change model** (e.g., `/model gpt-4o`) |
| `/approval <policy>` | Change approval policy (`auto`, `on-request`, `never`) |
| `/tools` | List all available tools the agent can use |
| `/mcp` | List connected MCP servers |
| `/stats` | Show session statistics (turns, tokens used) |
| `/save` | Save current session |
| `/sessions` | List all saved sessions |
| `/resume <id>` | Resume a saved session |
| `/checkpoint` | Create a checkpoint (snapshot) |
| `/restore <id>` | Restore from a checkpoint |
| `/clear` | Clear conversation history |
| `/exit` | Quit CodeCortex |

---

## ❓ Troubleshooting

### "Wrong API key" / Want to change settings?

```bash
codecortex --reset
```

This deletes your saved config and asks for everything again.

### "Model does not exist" error?

You entered a wrong model name. Common mistakes:
- ❌ `chatgpt` → ✅ `gpt-4o-mini`
- ❌ `gpt4` → ✅ `gpt-4o`
- ❌ `claude` → ✅ `anthropic/claude-3.5-sonnet` (on OpenRouter)

Fix it:
```bash
codecortex --reset
```

### "No API key found" error?

Run setup again:
```bash
codecortex --reset
```

### "Insufficient quota" / "billing" error?

Your OpenAI account has no credits. Either:
1. Add $5 credits at [platform.openai.com](https://platform.openai.com/settings/organization/billing)
2. **OR** switch to OpenRouter (free): `codecortex --reset`

### Where is my config saved?

Your configuration is saved at:
```
~/.codecortex/config.json
```

You can also manually edit this file.

---

## 🛠️ What Can CodeCortex Do?

CodeCortex AI can autonomously:

- 📝 **Read & Write Files** — edit code, create new files, modify configs
- 🖥️ **Run Terminal Commands** — install packages, run tests, build projects
- 🔍 **Search Code** — find functions, grep patterns, understand codebase
- 🐛 **Fix Bugs** — analyze errors, debug issues, apply patches
- 🌐 **Web Search** — look up documentation, find solutions online
- 🔌 **MCP Servers** — connect to external tools and services
- 💾 **Session Management** — save, resume, and checkpoint conversations

---

## 🤝 Contributing

GitHub: [Tanishq-S-Dev05/CodeCortex-AI](https://github.com/Tanishq-S-Dev05/CodeCortex-AI)

---

## 📄 License

MIT License — use it however you want!
