Autonomous Agent Guide
Proxima Agent is an optional Python runtime that carries out tasks on your computer. It sends its model calls through the Proxima gateway, so it can run on your free web sessions or on your own API keys. From web research and browser automation to editing code, running tests and repairing failures, it turns an instruction into actions and remembers useful lessons between sessions. This guide describes version 5.5.0.
1. Core Agent Capabilities
The agent runs in its own managed Python environment (Python 3.10 or newer; the installer bundles the wheels it needs, so nothing is downloaded from PyPI at runtime):
- Execution loop: the agent writes Python and runs it in a worker process. That code can read and write files, run shell commands, call the network and drive the desktop, so one execution tool covers a wide range of work.
- Coding tools: file read, write and patch helpers with whitespace-tolerant edits, recursive grep, find-and-replace (dry run by default), syntax checks and linters, and git helpers (status, diff, commit, branch, stash, blame).
- Repository intelligence: an index of symbols, imports and references for Python and JavaScript projects (see section 5).
- CDP browser control: drives local Google Chrome over the Chrome DevTools Protocol on port
9222, without Selenium or WebDriver, to open pages, type, click, read the console and take screenshots. - Computer use: window management, screen OCR (Tesseract, or the native Vision API on macOS) and desktop automation on Windows, macOS and Linux.
- Skills: reusable procedures the agent derives from tasks that worked, stored with success statistics (see section 7).
- Sub-agents and peers: a task can be delegated to lightweight sub-agents or other AI peers when multi-agent mode is on.
--permission auto|smart|suggest):
-
Full Auto: runs everything without asking.
-
Smart (default in the interactive prompt): runs normally and pauses for your approval when an action looks risky (section 3).
-
Suggest: the agent stops before significant actions and offers you numbered options, including typing your own instruction.
2. Running the Agent
Start it from the Agent tab of the desktop app, or from a terminal with the
proxima-agent command:
| Command | What it does |
|---|---|
proxima-agent run "<prompt>" | Runs one goal-driven task. Options: --model, --thinking default|low|medium|high, --permission auto|suggest|smart. |
proxima-agent models | Lists the models discovered across your active providers and BYOK settings. --refresh forces a fresh check. |
proxima-agent web | Starts the web console (default 127.0.0.1:8500; --host and --port change it). |
proxima-agent test | Runs built-in diagnostic self-checks. |
The web console
The console streams output over a WebSocket while a task runs, keeps a list of conversations (with pinning, folders and titles), accepts file uploads, lets you store BYOK keys for the agent, and shows a model picker populated from the gateway's live model list. When you choose a reasoning model it offers the thinking-depth selector. Requests from any non-loopback origin are rejected.
Finding the gateway
The agent looks for the gateway port in this order: the environment variables
PROXIMA_GATEWAY_PORT, PROXIMA_REST_PORT or PROXIMA_PORT; then
rest-port.json in Proxima's user data folder; then 3210. PROXIMA_API_KEY
supplies a key if you enabled one, and PROXIMA_WORKSPACE (default ~/Proxima)
sets the agent's workspace folder.
Limits worth knowing
| Setting | Default |
|---|---|
| Tool iterations per task | 50 |
| Time limit for one code execution | 300 seconds |
| Captured output per execution / per tool result | 15,000 / 10,000 characters |
| API retries per model call | 4 |
| Context compaction threshold / hard threshold | 30 / 50 |
These live in ~/.proxima-agent/config.json and can be edited there.
3. Safety Gates
Every piece of code the model writes passes a gate before it runs. The gate applies its checks in a fixed order:
The dangerous-pattern list covers file and folder deletion (.unlink,
shutil.rmtree, rm -r, Remove-Item), moves, disk formatting and
partitioning, shutdown and restart, registry edits, permission changes, package uninstalls,
destructive git commands (push --force, reset --hard, clean -f,
branch deletion), database DROP, TRUNCATE and DELETE FROM,
firewall changes, killing processes, system environment changes, writes into system folders, and SSH
or GPG key operations. You can add your own patterns under blocked_patterns in the
config file.
Risk scoring in Smart mode
Each risky token adds a weight to the code's score, and the agent asks for approval when the
total reaches 3. Examples: deleting or removing files, rm -rf, os.system,
eval(, shell=True, payments and purchases weigh 3; installing packages,
subprocess.run, sending data, registry access and shutdown weigh 2; downloads, logins and
navigation weigh 1. Several small risks can add up to a prompt.
Suggest mode
In Suggest mode the model is instructed to emit a [SUGGEST] block with a
one-line context and two or three options before moves, deletes, installs, messages, purchases or
anything that could lose data. You pick a number, type your own instruction, or skip and let the
agent decide. Trivial actions such as reading and listing proceed without a prompt.
4. Self-Healing and Error Recovery
Recovery works on two levels: the way the agent reacts to a failing model call, and the way it reacts to a failing step in the work itself.
Failing model calls
Each error from the model API is classified before anything is retried:
| Kind | Retried? | What the agent does |
|---|---|---|
| Transient server or network error, empty reply | Yes | Retries with exponential backoff and jitter (by default 2 s base, up to 60 s). |
| Rate limit (HTTP 429) | Yes | Backs off, then retries. |
| Context too large (HTTP 413) | Yes | Trims history, then retries. |
| Authentication failure (401, 403) | No | Stops and tells you to check the login or key. |
| Invalid request or unknown model (400, 404, 422) | No | Stops, since repeating the same request cannot succeed. |
| Provider generation failed ("model not available", parse or stream failures) | No | Stops and suggests trying another model or checking the login. Terminal failures are no longer retried as of 5.5.0. |
Failing steps
When a tool call fails, the self-healing engine classifies the failure (timeout, lost connection, element not found, rate limited, stale reference, and so on) and looks it up in a store of recoveries that have worked before. Each class has a retry policy with its own limits, for example three retries with a reconnect step for a lost browser connection, and up to three retries with 5 to 60 second backoff for rate limits. A step that is not marked as safe to repeat is not retried automatically unless its failure class is known to be safe to retry. When a retry succeeds, the recovery is recorded with its success rate so the next run applies it first.
The code repair loop
For code changes the agent works in small, checked steps: edit, run the tests or linter, read the
error output, and adjust, until the checks pass or the iteration limit (max_tool_iterations)
is reached. The repository tool autonomous_repair_loop packages one version of this. It
scores the file before changing it (does it parse, how many tests pass, how many lint errors), applies
a patch written as <<<old<<< ... ===new=== ... >>>end>>> blocks, re-scores the
result, and keeps the best version it has seen, for at most three iterations per call. It refuses an
instruction without those markers rather than overwrite the whole file, and it keeps the file's
original line endings. A longer walk-through is in the engineering journal.
5. Repository Intelligence
Instead of grepping blindly, the agent builds an index of your project in
.proxima/index.db inside the project folder. The index records files, symbols
(classes, functions, methods), imports, references, call relations, dependencies, modules and tests.
Python files are parsed with the ast module and JavaScript
files with Node. The agent can then:
- report project type and entry points (
analyze_project) and index health (repo_status,repo_health); - find definitions, references, callers and implementations of a symbol;
- list the files and tests a change would affect (
get_impacted_files,get_impacted_tests); - rename a symbol across the project, as a dry run unless told otherwise (
rename_symbol); - produce hierarchical file and directory summaries, and pack the most relevant files into a size-limited context (
compress_context).
This is what lets it work on repositories far larger than a model's context window.
6. Browser Automation
The agent's browser driver speaks the Chrome DevTools Protocol directly over WebSockets, in a single Python module of about two thousand lines, with no Selenium or WebDriver dependency. It can open tabs, navigate, type, click elements by their visible text, read console output and take screenshots. Agent code that tries to simulate keyboard input for a browser task is blocked by the gate described above and redirected to this driver. Chrome must be installed; the desktop app's diagnostics panel reports whether it was found. For a deeper walk-through see the Chrome CDP guide.
7. Local Memory Stores
Everything the agent remembers stays on your machine. The main stores are four SQLite databases, plus a few small JSON files:
vault.db (Conversations)
Sessions and messages, with parent and child links so sub-agents can work on a fork without
polluting the main thread. Old data is pruned automatically. Location: ~/.proxima-agent/.
insights.db (User Context)
Preferences, workspace facts and environment details extracted from conversations, so you do
not have to repeat them. Location: ~/.proxima-agent/.
memory.db (Lessons)
Short lessons per context (for example per website or tool): what worked, what failed, and
how often it was useful. Capped at 300 entries. Location: ~/.proxima-agent/.
skills.db (Procedural Skills)
Reusable procedures with triggers, guidance, verification steps, a use count and a success
rate. New skills start as candidates and are promoted or retired based on results. Location:
~/.proxima/skills.db.
Alongside these, learned_fixes.json holds the recoveries from section 4 and
strategies.json records task strategies and their performance. To reset the agent's
memory, close Proxima and delete the files you want to forget. They are recreated empty on the next
run.
8. Sub-agents and Peers
With multi-agent mode enabled in the configuration (multi_agent, off by
default), the agent can delegate work to lightweight sub-agents that run their own tool loop, or delegate
to peer AIs, synchronously or in the background. The conversation vault records the
parent and child sessions. At the MCP level, the crew, run_workflow and
run_loop tools offer role-based and iterative pipelines without the Python agent; see
the tool catalog.