Proxima
Open-source AI coding agent for the terminal, model-agnostic and permission-controlled
Overview
Proxima is an open-source, terminal-native AI coding agent written in Dart that lets developers understand, navigate, modify and maintain software projects in natural language. Built around an autonomous agent loop, it gives language models controlled access to development tools: inspecting codebases, locating symbols and dependencies, editing files, running shell commands and tests, and working with Git, all within explicit permission boundaries. It is model-agnostic, supporting Anthropic and OpenAI models alongside locally hosted models through Ollama and compatible endpoints, and its layered architecture keeps AI reasoning separate from tool execution, security enforcement, context management and terminal interaction.
Context
AI-assisted development is moving from code completion toward autonomous agents that work directly inside software projects, which takes far more than connecting a language model to a terminal.
Problem
Language models cannot inspect or change a local environment on their own, and unrestricted file and shell access is risky. Large codebases, limited context windows, differing providers and multi-step tasks add reliability challenges.
Approach
Designed and built a modular AI coding agent in Dart around a structured reasoning and tool-execution loop, with a unified interface for multiple LLM providers, a registry of development tools, a risk-aware permission gateway, token-aware context management and persistent sessions.
Outcome
An open-source agent that carries out multi-step development tasks in the terminal (codebase analysis, file changes, tests and Git operations) across cloud and local models, with configurable permissions and an extensible foundation for agentic tooling.
Challenges
Orchestrating Autonomous Tool Execution
Turning a model's proposed steps into reliable actions means interpreting tool requests, validating arguments, executing operations and feeding results back, without repetitive loops, malformed calls or steps that make no progress.
Securing Filesystem and Shell Access
A useful agent must edit files and run commands, but destructive operations need explicit user authorization, and that security has to be enforced by the runtime rather than by instructions to the model.
Managing Limited Context Windows
Repositories hold far more than a model can process at once. Keeping relevant code, history, tool results and token budgets under control during long sessions affects cost, limits and reasoning quality.
Supporting Different Model Providers
Cloud and local models differ in APIs, context limits, tool calling, streaming and error handling, and the agent's core logic could not be duplicated per provider.
Reliability Across Multi-Step Tasks
Reading files, finding references, editing code, running tests and fixing errors depend on each other. A failure at any step can leave the agent in an inconsistent state.
Solutions
Autonomous Agent Execution Engine
A structured reasoning and execution loop in which the model inspects its environment, selects tools, executes them and evaluates the results until the task is done or a limit is reached. Tool requests are validated against schemas, with safeguards against repeated and unproductive calls.
Impact: Multi-step engineering workflows from natural language, with execution governed by the application rather than the model.
Model-Agnostic LLM Integration
A unified provider abstraction for Anthropic Claude, OpenAI and local Ollama models, plus configurable OpenAI-compatible endpoints, with models switchable inside a session.
Impact: Less dependence on any one AI vendor, and the option to run without a cloud AI dependency at all.
Risk-Based Permission Gateway
Every tool request passes a central gateway that classifies it as Safe (runs automatically), Confirm (needs approval), High Risk (explicit confirmation) or Blocked (always rejected), with configurable modes, command restrictions, audit logging, credential masking and previews of proposed actions.
Impact: Enforceable boundaries between AI-generated instructions and the developer's machine.
Codebase Navigation and Development Tools
A tool registry for reading and editing files, traversing directories, pattern search, symbol discovery, reference and import analysis, shell execution, testing and Git, each with an input schema and a risk classification.
Impact: From conversational assistance to practical repository analysis, modification and workflow automation.
Token-Aware Context Management
Context budgeting, codebase indexing, file chunking, relevance-based selection and conversation compaction keep the important information in view during long sessions.
Impact: Coherent multi-step work within finite model context windows.
Persistent Sessions, Audit Trails and Undo
Resumable sessions that track files accessed and changed, execution history and token usage, an append-only permission audit log, automatic backups and an undo command.
Impact: Continuity, traceability and recoverability during AI-assisted development.
Specialist Subagent Delegation
The main agent can hand bounded subtasks to specialist agents for code analysis, refactoring and testing, with limits that prevent runaway task expansion.
Impact: Structured task decomposition while keeping execution control central.
Extensible Plugin Architecture
Plugins add tools without changing the core, through JSON descriptors and a structured input/output protocol, with discovery, installation, removal, integrity checks and project or global scope.
Impact: An extensible tool ecosystem for new capabilities and integrations.
Cross-Platform CLI and Automated Releases
An interactive terminal interface with streaming responses, keyboard navigation, command completion and model selection, plus GitHub Actions workflows that publish standalone executables for macOS, Linux and Windows.
Impact: A portable tool that runs without installing the Dart SDK, interactively or as a one-shot task runner.