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:
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.
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.
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):
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, databaseDROP, 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 Mode | Behavior | Risk 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
| Symptom | Root cause | Diagnosis | Fix |
|---|---|---|---|
| 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.