🤖 CoderAI

Autonomous AI Pair Programming in Your Terminal

Key Features • Quickstart • Interactive CLI • Core Tools • Architecture • Security • Configuration • Development

Overview

CoderAI is a terminal coding agent built with a clean, decoupled architecture: a UI-agnostic engine (coderai.core) paired with an interactive terminal UI (coderai.cli).

CoderAI is designed from the ground up for safety, deterministic execution, and developer velocity:

• Snippet-Scoped File Editing: read yields an anchored snippet_id; edit strictly targets that snippet with real-time file-version checks to prevent hallucinations, out-of-context changes, and stale overwrites.
• Bounded Agent Loop: Deterministic agent turns (stream → tool_calls → permissions → execute → loop) with loop-guards and token-threshold compaction.
• Granular Side-Effect Permissions: 10 fine-grained permission scopes (read-in-cwd, write-in-cwd, mutate-git-log, network, mcp, etc.) evaluated before any tool executes.
• Plan Mode: Enforces a strict read-only boundary during exploration, planning, and task breakdown.
• GitFileHistory Checkpointing & Instant Undo: Every turn is automatically snapshotted into .git_history, allowing one-command rollback (/undo) and diff inspection (/diff).
• Frontier LLM Support with Thinking Mode: Native routing and reasoning token rendering for OpenAI (gpt-5.6-sol, gpt-5.6-luna, gpt-4o), Anthropic (claude-3-7-sonnet, claude-3-5-sonnet), DeepSeek (deepseek-v4-pro, deepseek-r1), Google Gemini (gemini-2.5-pro, gemini-2.5-flash), and local Ollama/OpenRouter endpoints.
• Model Context Protocol (MCP): Native stdio MCP client for connecting external custom tools.
• Context Expansion via @file: Seamlessly reference workspace files in your prompts with auto-attached context.
• Minimal Core Dependencies: Pruned to rich, openai, and requests.

Installation

From Source (Editable Mode)

# Clone the repository
git clone https://github.com/adityaanilraut/CoderAI.git
cd CoderAI

# Install in editable mode
pip install -e .

# Verify installation
coderai --version

Install with Development Dependencies

pip install -e ".[dev]"

Quickstart

1. Set Your API Key

# Standard OpenAI API Key
export OPENAI_API_KEY="sk-..."

# Or specify a custom base URL (e.g. OpenRouter, DeepSeek, Ollama, Gemini)
export OPENAI_BASE_URL="https://api.openai.com/v1"

You can also create a .env file or configure settings in ~/.coderai/settings.json or .coderai/settings.json.

2. Launch Interactive REPL

coderai

3. Launch in Plan Mode

coderai --plan

4. Run a One-Shot Task

coderai "Refactor auth middleware to support JWT refresh tokens"

5. Auto-Approve Permissions for CI / Scripting

coderai --yes "Run unit tests and fix any failing assertions in tests/test_core.py"

Interactive CLI & Slash Commands

When running coderai, you enter an interactive REPL featuring an ASCII banner, real-time token status bar, thinking block display, and live diff rendering.

Slash Commands

Tab Autocompletion & Command History

CoderAI comes with full readline integration:

• Tab autocompletion: Press Tab on / commands, /model targets, and @ file paths.
• Persistent history: Arrow Up / Down to cycle through previous prompts across sessions (persisted at ~/.coderai/history).

Context Expansion (@file Mentions)

You can mention files directly anywhere in your prompts:

coderai> Explain the architecture in @coderai/core/session.py and how it connects to @coderai/core/permissions.py

CoderAI automatically detects the files, reads their contents, and injects them into the prompt context. Specific line ranges can also be targeted with @file.py:10-30 or @file.py:L25.

Core Tools

CoderAI provides a focused, high-leverage built-in tool surface:

Architecture

CoderAI maintains a strict boundary between the engine (coderai.core) and presentation (coderai.cli):

coderai/
├── main.py                     # Console entry point -> coderai.cli.app.main
├── py.typed                    # PEP 561 typing marker
│
├── cli/                        # Interactive Presentation Layer (Rich UI)
│   ├── app.py                  # CLI argument parser, REPL, permissions prompt
│   ├── ascii_art.py            # Brand banner and header rendering
│   ├── diff_render.py          # Syntax-highlighted diff preview
│   ├── exit_summary.py         # Session metrics & duration summary
│   ├── file_mention.py         # @file path detection and context expansion
│   ├── interactive_menu.py     # Interactive model, session, and skill pickers
│   ├── plan_render.py          # Plan checklist table rendering
│   ├── status_bar.py           # Dynamic status bar (model, tokens, plan status)
│   ├── thinking.py             # Reasoning / thinking block renderer
│   ├── tool_card.py            # Tool execution cards with timing & results
│   └── welcome.py              # Welcome screen & quick-start guide
│
└── core/                       # UI-Agnostic Core Engine
    ├── session.py              # SessionManager (bounded agent loop, JSONL persistence)
    ├── prompt.py               # System prompt builder, tool schemas, skills loader
    ├── permissions.py          # Side-effect permission scopes & policy evaluation
    ├── settings.py             # Settings resolver (project + user + environment)
    ├── state.py                # Snippet manager, file versioning, staleness detection
    ├── openai_client.py        # Client factory & multi-provider auto-routing
    ├── subagent.py             # Subagent orchestrator
    │
    ├── tools/                  # Built-in tool handlers
    │   ├── read.py             # File reader & snippet creator
    │   ├── edit.py             # Scoped string replacer
    │   ├── write.py            # File writer
    │   ├── bash.py             # Shell executor
    │   ├── ask_user_question.py# Interactive user questions
    │   ├── update_plan.py      # Implementation plan checklist
    │   ├── web_search.py       # Web search handler
    │   ├── understand_image.py # Image inspection
    │   └── subagent.py         # Subagent tool interface
    │
    ├── mcp/                    # Model Context Protocol (MCP)
    │   ├── client.py           # Stdio MCP client
    │   └── manager.py          # Dynamic tool discovery & dispatch
    │
    └── common/                 # Core Utilities
        ├── file_history.py     # Git-backed checkpointing, diff, and undo
        ├── message_converter.py# OpenAI message formatting & turn recovery
        ├── model_capabilities.py# Frontier model registry & feature detection
        ├── openai_thinking.py  # Reasoning tokens extractor
        ├── shell_utils.py      # Shell side-effect analyzer
        ├── process_tree.py     # Subprocess tree cleanup
        └── bash_timeout.py     # Command execution timeout wrapper

Security & Permissions

CoderAI follows a defense-in-depth, fail-closed security model. Every tool invocation evaluates side-effect scopes before execution.

Permission Scopes

Configuration

Settings are resolved in order of precedence: CLI arguments > Environment variables > Project config (.coderai/settings.json) > User config (~/.coderai/settings.json).

Configuration Example (settings.json)

{
  "model": "gpt-5.6-luna",
  "temperature": 0.2,
  "thinkingEnabled": true,
  "reasoningEffort": "max",
  "permissions": {
    "defaultMode": "allowAll",
    "allow": ["read-in-cwd", "query-git-log"],
    "ask": ["write-in-cwd", "write-out-cwd", "delete-in-cwd", "mutate-git-log", "network", "mcp"],
    "deny": ["delete-out-cwd"]
  },
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Environment Variables

Development

CoderAI includes a comprehensive offline test and verification suite.

# Format code
make format

# Run linter
make lint

# Run type checks
make typecheck

# Run test suite
make test

# Run offline engine self-check
python scripts/self_check_core.py

# Clean build artifacts
make clean

Acknowledgements

CoderAI builds upon and adapts architectural concepts, protocol designs, and patterns from Deep Code CLI (created by Vegamo), released under the MIT License.

We gratefully acknowledge the Deep Code project and its contributors for pioneering:

• Snippet-Anchored Precision Editing: The robust read (anchored snippet_id) to edit pattern with whitespace tolerance and staleness detection.
• Bounded Agent Loop & Token Compaction: Deterministic turn cycles, multi-turn loop guards, and intelligent context compaction.
• Side-Effect Permission Scopes: The 10-scope fail-closed security architecture (read-in-cwd, mutate-git-log, mcp, etc.).
• Interactive Terminal Workflow: Advanced input buffering, dynamic status bar, and interactive menu patterns.

In compliance with the MIT License terms, original copyright notices and attribution are maintained across adapted core modules.

License

MIT License. See LICENSE for details.