Autonomous Agent Guide

Proxima Agent is an autonomous action engine designed to execute tasks on your host computer. From web research, browser automation, and data processing to full-stack software development, shell execution, and self-healing error repair, it turns your instructions into completed real-world actions with persistent cross-session memory.

1. Core Agent Capabilities

The agent is package-isolated inside a dedicated virtual environment (python-env) and performs general autonomous tasks across your system:

  • Universal Task & Shell Execution: Runs terminal commands, writes Python and bash scripts, manages files, and executes multi-step automation workflows.
  • CDP Browser Control: Directly controls local Google Chrome instances using Chrome DevTools Protocol over WebSockets (port 9222) to browse the web, extract data, fill forms, and test web apps.
  • Self-Healing Engineering: Reads, edits, and refactors files, runs test suites, and automatically heals syntax or runtime failures until all checks pass.
  • Dynamic Skill Generation: Generates custom Python runner scripts on the fly, validates their parameters, and registers them inside its local procedural database (skills.db) to expand its toolkit.
Gated Execution Safety: To protect your local system, the agent supports three permission levels:
- Full Auto: Executes writes and system commands instantly.
- Smart (Default): Reads files automatically but prompts for permission if a system command risk score exceeds safety limits.
- Suggest: Displays proposed file changes as unified git diffs and command lines, waiting for manual user approvals.
http://127.0.0.1:8500 — Proxima Agent Web Hub
Proxima Agent Interface

2. Self-Healing Compilation Loops

When assigned code repair tasks, the agent operates in an active correction loop. It performs code writes, calls test scripts, captures stdout/stderr streams, and corrects code when failures occur:

1. Ingest workspace files & build symbol map 2. Run test suites to capture stdout/stderr traces 3. Parse exceptions against the local experiences DB 4. Synthesize code corrections & apply patches 5. Re-run test suites to verify compile compliance

If a compilation or execution error is thrown, the compiler parser compares the stack trace against previously stored successful fixes. It adapts the code and repeats the cycle until all tests pass.

3. Local SQLite Memory Engines

To support persistence across sessions, the Python agent maintains four isolated SQLite databases inside your home directory (~/.proxima-agent/*.db):

vault.db (Conversations)

Stores message histories, parent-child thread lineages, and conversation forks so sub-agents can collaborate on alternative solutions without polluting the main thread.

insights.db (User Context)

Extracts and catalogs key developer patterns, operating environments, stack preferences, and facts to prevent repetitive prompt instructions.

memory.db (Exceptions & Fixes)

Caches syntax compilation errors and the matching file diffs that successfully fixed them, allowing the self-healing routine to reuse working corrections.

skills.db (Procedural Scripts)

Caches custom runner scripts created during tasks. The agent grades skills via a success priority model, keeping working utilities and deprecating failing ones.