codecortex-ai 0.1.2

CodeCortex AI — autonomous coding agent for the terminal

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

---

📦 Installation

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

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

🟢 OpenRouter (Recommended — FREE models available)

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

🔵 OpenAI (Paid — requires $5+ credits)

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

Get your key: platform.openai.com/api-keys

🟡 Groq (Free tier available)

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

🟠 Together AI

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

---

💬 Usage

Interactive Mode (chat with the agent)

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

codecortex "fix the type error in app.py"

Set Working Directory

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?

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:

codecortex --reset

"No API key found" error?

Run setup again:

codecortex --reset

"Insufficient quota" / "billing" error?

Your OpenAI account has no credits. Either:

1. Add $5 credits at platform.openai.com
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

---

📄 License

MIT License — use it however you want!