Apex-Agent: Resilient & Context-Aware Coding CLI

Apex-Agent is a sophisticated Command Line Interface (CLI) framework designed to enhance developer productivity by providing deep context awareness, secure tool execution, and multi-provider LLM resilience.

🚀 Key Features (MVP)

🧠 Intelligence & Context

• Advanced Context Engine: Automatically manages relevant project context, including pinned files and repository structure.
• Symbol-Aware Search: Precisely locate class and function definitions using AST parsing (search_symbol).
• Semantic Mapping: Built-in repository mapper to provide the LLM with a structural overview of the codebase.

🛠️ Resilient Architecture

• Multi-Provider Support: Seamlessly switch between Groq (high-speed) and Ollama (local/privacy).
• Human-in-the-Loop Safety: Mandatory planning and approval workflow. Every change is previewed with a colorized Diff UI.
• Circuit Breaker & Fallback: Automatic failover logic with latency tracking for maximum uptime.

🧰 Comprehensive Toolset

• File Ops: read_file (with selective truncation), write_file, replace_in_file, open_file_range.
• Analysis: find_references, list_files, search, get_repo_map.
• Execution: run_command (with security classification), run_tests (pytest integration).

🛠️ Setup & Installation

Prerequisites

• Python 3.12+
• Ollama (for local execution)
• Groq API Key (optional, for cloud execution)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/apex-agent.git
   cd apex-agent
   

2. Install globally (using uv or pip):

   # Using uv (recommended)
   uv tool install .
   
   # Or using pip
   pip install .
   

3. Initialize Global Configuration: Run the following from anywhere:

   apex init
   

   This creates a configuration file at ~/.apex-agent/.env. Open it to add your API keys.

🖥️ Usage

You can now run the agent from any repository directory by simply typing:

apex chat start

Commands

• apex init: Initialize global settings.
• apex chat start: Start an interactive session in the current directory.
• /trace: (Inside chat) View raw LLM interaction data.

📜 License

Distributed under the MIT License. See LICENSE for more information.