AIdex

AIdex AI Coding Agent

   ___    ____    __
  / _ |  /  _/___/ /__ __
 / __ | _/ // _  / -_) \ /
/_/ |_|/___/\_,_/\__/_\_\

CLI AI Coding Agent v1.5.1

AIdex is a fully-featured, professional CLI AI coding agent that runs in your terminal. It connects to multiple AI providers with free and paid models, and can actually create, edit, delete files, run commands, manage git, and more — just like professional AI coding tools.

AIdex is built to run everywhere — from a fresh Windows 11 64-bit machine down to a 32-bit Windows XP box, an old Linux netbook, or a Raspberry Pi. When the enhanced terminal UI’s dependencies aren’t available, AIdex automatically drops into a zero-dependency plain-text interface with the exact same features, so it never just refuses to start.

Formerly known as Nexus. Renamed to AIdex. Old nexus.py / nexus/nexus.bat launchers and config still work — see Migration below.

🧠 Contributing or picking this project back up? Read BRAIN.md first — it’s a dense project-context file (architecture, tool system, web security model, API reference, known design decisions) meant to replace re-reading the whole codebase.

License Python Platform

RepoRanker

✨ Features

🚀 Quick Start

Requirements

Installation

# Clone or download
git clone https://github.com/Zelvior/AIdex
cd AIdex

# Run the installer (handles dependencies where possible, never hard-fails)
python install.py

# Start AIdex
python aidex.py

Windows

python install.py
aidex.bat

Linux/macOS

python3 install.py
./aidex
# or
python3 aidex.py

Forcing a specific interface

python aidex.py --plain   # zero-dependency text UI (XP, 32-bit, minimal Python)
python aidex.py --full    # Rich/prompt_toolkit UI (requires those packages)
python aidex.py --web     # browser-based UI (opens automatically)

🌐 Web UI

python aidex.py --web                       # opens in your default browser
python aidex.py --web --port 9000           # specific port
python aidex.py --web --no-browser          # don't auto-open a tab

Runs entirely on 127.0.0.1 (your own machine) using a zero-dependency stdlib HTTP server — no Flask, no extra pip install. It’s the same Agent/Config/provider code as the terminal app, just with a browser front end:

For safety, the web UI confines file access to your configured workspace (no escaping via /etc/passwd-style absolute paths or ../ traversal) and does not let the AI run shell commands or Python code through the browser unless you explicitly opt in via web_allow_shell_tools in config.

🔑 API Keys (17 Free Options!)

You do not need any API key to use AIdex — it works out of the box. Run /config any time to switch — providers are grouped the same way in every UI: no signup needed, then free tier with a quick signup, then paid/custom.

No signup needed:

Provider Notes
Pollinations (default) Chat + images, works immediately
Ollama Fully local — install ollama.com, no key
LLM7.io Free without a key; a free token raises your limit

Free tier, quick signup:

Provider Get a Key
OpenRouter openrouter.ai/keys
Groq console.groq.com/keys — fastest inference
Cerebras cloud.cerebras.ai — also very fast
Mistral AI console.mistral.ai/api-keys
Cohere dashboard.cohere.com/api-keys
GitHub Models github.com/marketplace/models — uses a GitHub token
NVIDIA NIM build.nvidia.com
Hugging Face huggingface.co/settings/tokens
Zhipu AI (GLM) open.bigmodel.cn
Kluster AI platform.kluster.ai/apikeys
Gemini aistudio.google.com/apikey — 1M token context

Paid / custom:

Provider Notes
Anthropic console.anthropic.com — no free tier
OpenAI platform.openai.com — no free tier
Custom Any OpenAI-compatible API — set its URL/key in /config

After starting AIdex, type /config to switch providers or enter an API key — the wizard shows each provider’s notes and a direct signup link. Ollama runs fully on your own machine — ideal for low-end or offline devices, no internet or account required (install Ollama separately, then point AIdex at it).

💬 Commands

Command Description
/help Show all commands
/config Configure API key, provider, model, workspace
/provider <name> Switch provider (openrouter/groq/anthropic/openai/ollama/pollinations/gemini/custom)
/model <name> Switch AI model
/models List available models
/workspace <path> Set working directory
/clear Clear conversation history
/save [file] Save conversation to JSON
/load <file> Load saved conversation
/status Show current config
/tools List all available tools
/run <cmd> Run shell command directly
/read <file> Read file directly
/ls [path] List directory
/analyze Analyze project structure
/safemode Toggle safe mode
/docs Show documentation
/credits Show credits
/terms Terms and conditions
/privacy Privacy policy
/license Apache 2.0 license
/disk [path] Show disk usage and directory size
/env Show Python/OS/architecture info
/which <name> Locate an executable on PATH
/image <prompt> Generate an image (free by default, no API key needed)
/ralph Show the Ralph task loop status
/ralph add <title> Add a task to the Ralph loop
/ralph run [n] Run the Ralph loop autonomously (default cap: 35 iterations)
/ralph clear Clear all Ralph tasks
/exit Exit AIdex

🌀 Ralph: the autonomous task loop

A dashboard-driven task loop modeled on the “Ralph” autonomous-agent pattern: add a list of tasks — with optional description, acceptance criteria, and priority, just like real user stories — then let AIdex work through them one at a time. Each task gets its own focused turn with the agent, and progress is saved after every step so you can stop and resume later without losing anything.

/ralph add Build a login page
/ralph view US-001
/ralph run

/ralph add will also prompt you for an optional description, acceptance criteria (one per line), priority, and type — or just hit Enter to skip and add a bare title. Tasks get structured IDs (US-001, US-002, …) automatically.

🛠️ Available Tools

The AI automatically calls these tools to perform real actions:

Tool Description
read_file Read file with line numbers
write_file Create or overwrite file
edit_file Replace specific text (str_replace)
patch_lines Replace line range
append_file Append to file
delete_file Delete file/directory
move_file Move/rename
copy_file Copy file
create_directory Create directories
list_directory List directory tree
search_files Find files by name/content
grep_file Search inside file
run_command Execute shell command
run_python Execute Python code
git_status Git status
git_diff Git diff
git_log Git history
git_add Stage files
git_commit Commit changes
git_init Init repository
analyze_project Project structure analysis
get_file_info File metadata
read_file_lines Read a specific line range (memory-efficient)
head_file Read first N lines
tail_file Read last N lines (memory-bounded, huge-file safe)
count_lines Count lines/words/chars in a file
disk_usage Disk free/used/total + directory size
env_info Python/OS/CPU architecture report
find_replace_in_files Bulk find/replace across files (dry-run by default)
git_branch List git branches
git_checkout Switch/create git branch
which Locate an executable on PATH
list_models Live model list with real pricing for any provider
generate_image Generate an image from a text prompt (free by default)

💡 Example Prompts

> Create a Python Flask REST API with CRUD operations for a todo list

> Read main.py and fix any bugs you find

> Analyze this project and suggest improvements

> Create a Dockerfile for this Python application

> Write unit tests for all functions in utils.py, then run them

> Refactor this JavaScript code to use modern ES6+ features

> Set up a basic Next.js project structure

> Find all TODO comments in the codebase

> Create a .gitignore file for a Python project

> Read package.json and update all dependencies to latest versions

📁 Project Structure

aidex/
├── aidex.py              ← Main entry point (auto-detects UI)
├── nexus.py              ← Legacy alias, forwards to aidex.py
├── install.py            ← Universal installer (never hard-fails)
├── setup.py              ← pip install support
├── README.md
├── LICENSE
├── CHANGELOG.md
└── src/
    ├── core/
    │   ├── agent.py      ← AI agent orchestrator, native tool-calling loop
    │   ├── config.py     ← Configuration manager
    │   ├── models.py     ← Live model registry (fetch/cache/fallback)
    │   ├── imagegen.py   ← Free image generation (Pollinations / custom)
    │   └── ralph.py      ← Ralph autonomous task-loop orchestrator
    ├── providers/
    │   └── base.py       ← OpenRouter, Groq, Anthropic, OpenAI, Ollama,
    │                        Pollinations, Gemini, custom
    ├── tools/
    │   └── file_tools.py ← All file/shell/git/image tools
    ├── tui/
    │   ├── app.py        ← Enhanced UI (Rich + prompt_toolkit)
    │   └── plain.py      ← Zero-dependency fallback UI (Python 2.7+)
    └── web/
        ├── server.py     ← Stdlib-only local web server (REST + SSE chat + Ralph)
        └── static/       ← Browser UI (HTML/CSS/JS, no build step)

🔒 Safe Mode

Safe mode (enabled by default) blocks destructive commands like rm -rf /. Toggle with /safemode. When OFF, all commands execute without restriction.

In the web UI, shell command and Python execution tools are disabled for the AI by default regardless of safe mode, since a browser-reachable endpoint is a different trust boundary than your own terminal. Set web_allow_shell_tools: true in your config file to allow them there too. File access from the web UI is always confined to your configured workspace — absolute paths and ../ traversal outside it are rejected.

⚙️ Configuration

Config stored at:

Migrating from Nexus

If you previously used Nexus, AIdex automatically migrates your old nexus-agent config (provider, API keys, model, settings) into the new aidex location the first time it runs — nothing is lost, no action needed.

🌍 Compatibility

OS Version 32-bit 64-bit Interface
Windows XP, Vista, 7, 8, 10, 11 ✅ ✅ Plain (XP/old) → Full (7+)
Linux Any (Ubuntu, Debian, Fedora, Arch…) ✅ ✅ Full (or Plain if deps missing)
macOS 10.9+ ✅ ✅ Full (or Plain if deps missing)

The enhanced Rich/prompt_toolkit interface needs Python 3.7+. On anything older — including Windows XP and many 32-bit-only Python installs — AIdex automatically uses its built-in plain-text interface, which needs no third-party packages at all and supports Python 2.7+. You get the exact same commands and tools either way.

📄 License

Apache License 2.0 — See LICENSE file.

Copyright 2024-2026 AIdex Contributors (originally Nexus AI Coding Agent)

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

🔗 Links

This site is open source. Improve this page.