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 modes: the agent runs in one of three modes, chosen at start-up or per run (--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.
http://127.0.0.1:8500 — Proxima Agent Web Console
Proxima Agent web console showing a task in progress

2. Running the Agent

Start it from the Agent tab of the desktop app, or from a terminal with the proxima-agent command:

CommandWhat it does
proxima-agent run "<prompt>"Runs one goal-driven task. Options: --model, --thinking default|low|medium|high, --permission auto|suggest|smart.
proxima-agent modelsLists the models discovered across your active providers and BYOK settings. --refresh forces a fresh check.
proxima-agent webStarts the web console (default 127.0.0.1:8500; --host and --port change it).
proxima-agent testRuns 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

SettingDefault
Tool iterations per task50
Time limit for one code execution300 seconds
Captured output per execution / per tool result15,000 / 10,000 characters
API retries per model call4
Context compaction threshold / hard threshold30 / 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:

1. Web-misuse check Raw keyboard simulation aimed at a browser task is blocked, and the agent is told to use its Chrome (CDP) driver instead. 2. Dangerous patterns Code that matches a known destructive operation needs explicit approval. 3. Permission mode Smart mode scores the code for risk and asks when the score is high enough.

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.

When nobody is at the keyboard: if a dangerous operation needs approval and there is no console to ask, the gate blocks it instead of letting it through. Full Auto mode skips the risk prompt, but the dangerous-pattern approval still applies.

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:

KindRetried?What the agent does
Transient server or network error, empty replyYesRetries with exponential backoff and jitter (by default 2 s base, up to 60 s).
Rate limit (HTTP 429)YesBacks off, then retries.
Context too large (HTTP 413)YesTrims history, then retries.
Authentication failure (401, 403)NoStops and tells you to check the login or key.
Invalid request or unknown model (400, 404, 422)NoStops, since repeating the same request cannot succeed.
Provider generation failed ("model not available", parse or stream failures)NoStops 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.

1. Ingest workspace files and build the symbol index 2. Run the test suite and capture stdout/stderr 3. Classify the error and look up earlier fixes for the same failure 4. Apply a patch 5. Re-run the tests; stop on success or after the iteration limit

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.