Autonomous Agent Guide

Proxima Agent is a local Python assistant that operates your local development workspace, analyzes structures, applies edits, runs tests, and automates browser interactions.

1. Core Agent Capabilities

The agent is package-isolated inside a dedicated virtual environment (python-env) and performs four primary runtime tasks:

  • Codebase Ingestion: Builds hierarchical symbol maps of project classes, modules, and functions. It indexes definitions locally so the system knows what context to load when debugging.
  • CDP Browser Control: Directly controls local Google Chrome instances using Chrome DevTools Protocol over WebSockets (port 9222). This enables browser automation without importing bulky dependencies like Selenium or Playwright.
  • Dynamic Skill Generation: Generates quick helper scripts on the fly, validates their parameters, and registers them inside its local procedural databases 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.

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.