1. Why Single-Shot Code Generation Fails

In a standard chat interface, code generation is open-loop: you describe a task, the model writes code, and you are left to run it and report back. In real codebases that fails for predictable reasons:

  • Missing context and invented APIs: without the surrounding files, models guess function signatures or import helpers that do not exist.
  • Mismatches that only show at run time: code that reads correctly still fails a test because a return type or an interface is slightly different.
  • No feedback: without stack traces, compiler messages and test exit codes, the model cannot tell that it was wrong, let alone how.

A self-healing agent closes the loop. It runs what it wrote, reads the failure, and tries again with that evidence in hand, and it keeps a record of what worked so the next run does not start from zero.

2. The Repair Loop in Practice

The agent (proxima_agent/agent.py) works in turns. In each turn the model writes a piece of Python, a gate checks it, a worker process runs it, and the output goes back to the model. A task ends when the model reports completion or after max_tool_iterations turns (50 by default). For code changes, that loop looks like this:

1. Understand (repository index: find the symbol, its callers and its tests)
↓
2. Edit (small patch, not a whole-file rewrite)
↓ safety gate, then run in a worker process
3. Verify (syntax check, linter, the project's test command)
↓ failed? classify the error and look up earlier fixes
4. Recover (retry with a known fix, or go back to step 2 with the error text)
↓ passed
5. Prove it (cheapest convincing evidence, then report)
Figure 3: The agent's repair loop, simplified

The final step is not a formality. Before the agent reports back, a verification prompt asks it to name 1 to 3 observable proofs and to try the cheapest first: a changed URL, an element that appeared, a file that exists, a file that contains the expected text. Only if cheap evidence is not enough does it spend steps on opening another page or app to confirm.

There is also a self-contained repair primitive, autonomous_repair_loop(file, edit, test_command, max_iterations=3). It measures a baseline (does the file 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. It refuses an instruction without those markers instead of overwriting the whole file, and it preserves the file's original line endings.

3. Reading Only What Matters: Symbols and Slices

Pasting a five-thousand-line file into a prompt wastes context and dilutes attention. Proxima avoids that in two places, both based on code structure rather than text search.

In the agent, a repository index (.proxima/index.db in the project) records files, symbols, imports, references and tests. Python files are parsed with the standard ast module and JavaScript files with Node. From it the agent can ask where a symbol is defined, who calls it, which files and tests a change would touch, and can pack a size-limited context around a set of seed files.

In the MCP server, src/utils/smart-slicer.js and symbol-extractor.js serve the analyze_file tool. They build a symbol map of a file and return only the symbols relevant to a question, which keeps prompts to cloud models small.

Python // asking the index instead of grepping (agent code)
from proxima_agent.tools.coding import repo_intel as ri

ri.find_definition("TokenVerifier.verify")      # where is it defined?
ri.find_references("TokenVerifier.verify")      # who uses it?
ri.get_impacted_files("auth/verifier.py")       # what could break if I change this file?
ri.get_impacted_tests("auth/verifier.py")       # which tests should I run afterwards?
ri.rename_symbol("TokenVerifier", "JwtVerifier", dry_run=True)   # preview a rename first

4. What the Agent Remembers

A self-healing agent should not rediscover the same fix every session. Proxima keeps four SQLite databases, plus two small JSON files, all on your machine:

Store Location What it holds
vault.db ~/.proxima-agent/ Conversation sessions and messages, with parent and child links for sub-agent forks. Pruned automatically.
insights.db ~/.proxima-agent/ Preferences, workspace facts and environment details learned across sessions.
memory.db ~/.proxima-agent/ Short "lessons" keyed by context (a website, a tool): the goal, what worked, what failed, and a hit count. Capped at 300 entries.
skills.db ~/.proxima/ Reusable procedures with triggers, guidance and verification steps, plus a use count and success rate.
learned_fixes.json ~/.proxima-agent/ Recoveries that fixed a class of tool failure before (for example "reconnect, then retry"), with a success rate.
strategies.json ~/.proxima-agent/ Task strategies and how they performed.

Note what is not stored: the databases hold lessons and recoveries, not a verbatim archive of every failing stack trace and patch. The recovery of a failing step is recorded by failure class, which keeps the store small and makes a match likely.

Python // how a failing step is healed (simplified from tools/self_heal.py)
def execute(task, tool, idempotent=False):
    try:
        return task()                                  # first attempt
    except Exception as e:
        failure_class = classify_failure(str(e))       # timeout, connection_failed, rate_limited ...
    known_fix = learned_fixes.lookup(failure_class, tool)
    if not idempotent and failure_class not in SAFE_TO_RETRY:
        return Failed("skipped auto-retry: action may not be safe to repeat")
    result = retry_engine.execute(task, tool=tool, idempotent=idempotent)  # policy per class
    if result.succeeded and not known_fix:
        learned_fixes.record_success(failure_class, tool, recovery_action="auto-retry")
    elif known_fix:
        learned_fixes.update_outcome(failure_class, tool, success=result.succeeded)
    return result

5. Skills: Promotion and Demotion by Evidence

When a multi-step procedure works, the agent can save it as a skill. New skills are not trusted automatically. Each one starts as a candidate, and every use updates an exponential moving average of its success (weight 0.3 on the latest outcome):

Python // proxima_agent/prompt/skills.py (simplified)
EMA_ALPHA = 0.3
MIN_USES_FOR_PROVEN = 3
MIN_RATE_FOR_PROVEN = 0.80
DEMOTION_TO_CANDIDATE = 0.50      # a proven skill whose rate falls below this drops back to candidate
DEMOTION_TO_DEPRECATED = 0.20     # a candidate whose rate falls below this is deprecated

new_rate = EMA_ALPHA * (1.0 if success else 0.0) + (1.0 - EMA_ALPHA) * old_rate

if status == "candidate" and uses + 1 >= MIN_USES_FOR_PROVEN and new_rate >= MIN_RATE_FOR_PROVEN:
    status = "proven"

Only a few skills are injected into a prompt (at most three, within roughly 200 tokens), and unproven ones are used as limited trials. Relevance scoring combines the skill's capabilities, workflow, trigger words and context. Deprecated skills are purged after 180 days. A Beta-Bernoulli prior (mean 0.5, strength 2) gives new skills a fair first trial rather than writing them off after one failure.

6. Safety Boundaries and Permissions

An agent that can run code can also delete things. Two independent mechanisms guard against that, described in more detail in the Agent Guide:

  • A pattern gate (execute.py, gate.py) asks for approval before known destructive operations such as recursive deletes, git push --force, git reset --hard, database DROP, registry edits or writes into system folders. If no console is available to ask, it blocks.
  • A permission mode (permissions.py) decides what else needs your approval.
Permission ModeBehaviorRisk policy
Full Auto Runs code without asking, apart from the pattern gate above. None beyond the pattern gate.
Smart (default) Scores the code with keyword weights and pauses for approval when the total reaches 3. Examples: delete or rm -rf weigh 3, installing packages weighs 2, downloads weigh 1.
Suggest The model is told to offer 2 to 3 numbered options in a [SUGGEST] block before significant actions, and you pick one or type your own. Relies on the model following the instruction, so it is guidance rather than a hard block.

These gates reduce risk; they do not remove it. Run the agent on a git-tracked project so any change can be reviewed and reverted.

7. Failure Analysis and Loop Halting

SymptomRoot causeDiagnosisFix
The task stops at the iteration limit The agent used all max_tool_iterations turns (50 by default) without finishing. Read the end of the transcript and the agent logs in ~/.proxima-agent/logs/ for repeated, similar attempts. Narrow the task, give it the failing test command, or raise the limit in ~/.proxima-agent/config.json.
"Provider generation failed" or "model not available" The model call failed in a way that repeating cannot fix. Since 5.5.0 this is treated as terminal. Run proxima-agent models --refresh to see what your accounts offer. Choose another model or log in again. See the troubleshooting guide.
A repair edit is rejected The instruction lacked the <<<old<<< / ===new=== markers, or the old text no longer matches the file. Read the returned error field. The file is left untouched. Re-read the file and resend a patch that matches the current text.
database disk image is malformed A database file was damaged, for example by a power loss during a write. Close Proxima, then run sqlite3 ~/.proxima-agent/memory.db "PRAGMA integrity_check;". Move the damaged file aside. Proxima creates a fresh, empty database on the next start, and you lose only the memory that file held.

8. Architectural Takeaways

What makes a coding agent reliable is less the model than the scaffolding around it: a code index so it reads the right lines, small verifiable edits, a run-and-check step after every change, classified errors with sensible retry policies, evidence before it claims success, and memory that only trusts a lesson after it has worked more than once. Proxima implements each of these as separate, inspectable pieces.