When a local coding agent fails, do not start by changing the model, expanding context, and swapping the tool harness at the same time. The same broken edit can come from three different layers: the local model/runtime is too weak or over-quantized, the agent is reading the wrong context, or the harness cannot apply, run, and verify the fix.
| Symptom | Suspect first | Proof test | First fix |
|---|---|---|---|
| It fails a tiny edit before tool use matters | Model/runtime or quantization | Run the same tiny task with a higher-precision local setting or a hosted control, with no extra files loaded | Change the quantization/runtime or use a stronger model for that task |
| It loses the relevant file, rule, or earlier decision | Context/retrieval | Start a clean session with only the target files and the governing instruction | Shrink the context and load exact evidence instead of more repo text |
| It explains the right fix but bad edits, commands, or tests derail the run | Harness/tool feedback | Compare the model's intended patch with the tool log, command output, and test result | Repair edit application, permissions, command wrappers, schemas, or test hooks |
| It only works after you changed several settings | No diagnosis yet | Reset to the same repo, same task, clean session, fixed files, and one changed variable | Repeat the control test before tuning again |
Use a hosted control only as a baseline: if the same minimal task succeeds there but fails locally, the local stack still needs diagnosis; if both fail, the task or instructions are probably underspecified. Stop local tuning for this task when the local route cannot meet your quality, speed, or tool-reliability bar after a controlled comparison.
Fast Triage Matrix
The first mistake is treating a local coding agent as one thing. It is a model, a runtime, a context selection system, and a harness wrapped around file edits, shell commands, tests, permissions, retries, and review. A failure in any one layer can look like "the agent is dumb" from the outside.
Use this short matrix before you touch settings:
| Layer | What it owns | Failure pattern | Do not conclude yet |
|---|---|---|---|
| Model/runtime | Model size, quantization, KV cache behavior, CPU/GPU placement, serving defaults | Weak reasoning on tiny tasks, broken structured output, slow or unstable inference, OOM when context grows | That every local model is bad |
| Context/retrieval | Loaded files, rules, prior turns, summaries, tool definitions, and logs | Edits the wrong file, forgets a constraint, misses a nearby symbol, overreads the repo | That a larger context window will fix it |
| Harness/tool feedback | Edit application, command runner, permissions, schemas, tests, sensors, retry loop | Correct explanation but failed patch, bad command, ignored test error, permission loop | That the model itself could not solve the task |
The winning move is not a universal setting. The winning move is a small controlled comparison that isolates one suspect layer.
Run the One-Variable Control
A local coding-agent diagnosis is only useful if the comparison is fair. Keep the same repository, same task, same instruction, same file set, and a clean session. Change one layer at a time.
Start with the smallest real task that reproduces the failure: one failing test, one bad edit, one command that the agent mishandles, or one file it keeps misreading. Record the model, quantization, runtime, context files, harness, command output, and final result. Then change exactly one thing.
| Control change | What it proves if the result improves | What it does not prove |
|---|---|---|
| Higher precision, larger local model, or hosted baseline | Model/runtime was a likely bottleneck | That the harness and context are healthy |
| Clean session with only target files | Context selection or history was a likely bottleneck | That a smaller model is enough for the full repo |
| Same model in another harness | Tool loop, edit application, tests, or permissions were likely involved | That the alternate harness is better for every task |
| Same prompt with a manual patch/test path | The model's idea may be sound while execution failed | That humans should rescue every future run |
This control rule matters more than the exact tool name. The adjacent route guide for local versus cloud coding agents is useful after you know which route is failing. Find the failed layer first; route selection comes after the evidence.
Suspect Quantization or Runtime When Tiny Tasks Fail
Suspect the model/runtime layer when the agent fails before context or tools can explain the error. Examples: it cannot keep a two-step edit straight, emits malformed tool JSON on a tiny task, repeats simple syntax errors, or becomes too slow or unstable when the context grows.
Quantization is a real suspect, but it is not the default verdict. Hugging Face's quantization guide describes the basic tradeoff: lower precision can reduce memory and compute cost, but it can also introduce precision loss. NVIDIA's model quantization overview separates weight, activation, and KV-cache quantization; that distinction matters because a coding session can be limited by both model weights and growing sequence memory.
Do not jump from "Q4 failed" to "local is impossible." First run the same tiny task with a less aggressive quantization, a larger coding-tuned model if your hardware supports it, or a hosted control. Keep the context minimal so you are not testing retrieval at the same time. If the higher-precision or hosted baseline succeeds while the local low-precision route fails, the model/runtime layer becomes the first fix target.
Good runtime notes include model name, quantization, context length setting, runtime, device placement, memory pressure, prefill speed, decode speed, and whether the exact same command/test passed. Without those notes, "quantization broke it" is only a guess.
Suspect Context When the Agent Loses the Relevant Evidence
Suspect context when the model is capable in isolation but cannot use the right repo facts. The agent edits a sibling file, forgets an earlier decision, ignores a local convention, or keeps reading more files without becoming more accurate.
Context engineering is not "dump the whole repository." Martin Fowler's context engineering for coding agents frames context as curated information, tools, rules, and feedback that help the model act. The Lost in the Middle paper is also a useful warning: even long-context models can perform worse when relevant information is buried in the middle of long input.
Run a clean-session test. Load only the target file, the failing test, the nearest interface or schema, and the governing instruction. Tell the agent what not to inspect. If the same task improves, your full run probably had context pollution, retrieval miss, stale history, or too many tool/rule definitions.
The first fix is usually smaller context, not larger context. Build a concise file map. Pin the exact rule. Use symbols, tests, and command output as evidence. Compact long sessions before they turn into a mixed log of old guesses. If the agent needs a huge context window for a small patch, the diagnosis is still incomplete.
Suspect the Harness When the Model Knows the Fix but the Run Fails
Suspect the harness when the answer is conceptually right but execution falls apart. The model names the right file, describes the right patch, and maybe even writes the correct diff, but the edit tool fails, the command runner uses the wrong directory, permissions block the check, the test output is not fed back, or the retry loop repeats the same mistake.
Harness engineering is the system around the model. Fowler and Thoughtworks describe harness engineering as guidance, sensors, deterministic checks, inferential reviews, and feedback loops. Their sensors for coding agents piece is a good reminder that type checks, linters, dependency rules, SAST, tests, and review signals can become the agent's eyes and brakes. OpenAI's Codex best-practices guidance similarly emphasizes tests, checks, review, and repository guidance for reliable coding-agent work.
Use a harness comparison before blaming the local model. Run the same model and same prompt in another harness if possible. Or ask the model for the intended patch without applying it, then apply and test manually. If the idea is good but the harness cannot perform the edit-test loop, fix the harness before you change the model.
The practical fixes are boring: clearer tool schemas, safer edit application, stable working directory, explicit permission policy, deterministic verification commands, better AGENTS or rules files, and a retry loop that reads compiler/test output instead of guessing.
Build the Failure Log Packet
A useful support issue, team note, or model comparison needs a compact evidence packet. It should let another engineer reproduce the failure without replaying the whole session.
Use this template:
| Field | Record |
|---|---|
| Task | The smallest repo task that reproduces the failure |
| Model/runtime | Model, quantization, runtime, device placement, context-length setting |
| Context | Files loaded, rules loaded, prior turns kept, summaries or retrieval used |
| Harness | Tool wrapper, edit method, command runner, permission mode, test command |
| Symptom | Exact failure, not the interpretation |
| Tool log | Patch application, command output, test result, permission or schema error |
| Control comparison | What stayed fixed, what changed, and whether the result changed |
| First fix tried | One change only, with pass/fail outcome |
| Stop decision | Continue tuning, switch harness, use hosted control, or stop local for this task |
Keep the difference between evidence and explanation clear. "The Q4 model failed a tiny no-context edit that passed with a higher-precision local model" is evidence. "All quantized local coding agents are useless" is not.
Tune, Switch, or Stop
After one or two controlled comparisons, choose a route. Do not keep tuning because the setup feels close.
Tune the model/runtime when the failure appears before context or harness effects and improves with a stronger local baseline. Try less aggressive quantization, a model better suited to coding, saved runtime settings, or a smaller task boundary.
Shrink context when the agent succeeds with hand-selected files but fails in a broad session. Add a file map, remove stale conversation, load exact tests, and prefer evidence over repo dumping.
Repair the harness when the model knows the fix but tools, commands, tests, permissions, or retries break the run. The fix belongs in schemas, edit application, command wrappers, AGENTS guidance, sensors, or review gates.
Use a hosted control when the local route cannot meet the quality or speed bar but the task still matters. Hosted controls are diagnostic baselines and delivery routes, not proof that local coding agents are pointless. If the question becomes Claude Code versus Codex rather than local failure diagnosis, use the sibling Claude Code vs Codex route guide. If the question is usage meters and context accounting in Codex, use the Codex token usage guide. If API-key spend is the issue, use the Codex CLI token cost estimator.
Stop local tuning for this task when the local stack still fails after a fair baseline, when review cost rises above the saved inference cost, when context management becomes the work, or when the harness cannot produce trustworthy test feedback. A local route that consumes the engineer is not a working coding agent.
FAQ
Is quantization the most common reason a local coding agent fails?
Not by itself. Quantization can reduce precision and make a smaller local route possible, but context selection and harness feedback can create the same outward failure. Test a tiny task with minimal context and a higher-precision or hosted baseline before blaming quantization.
How do I know the context is the problem?
Run the same task in a clean session with only the target files, nearest tests, and governing rules. If the agent improves, the broad session likely had noisy context, stale history, retrieval miss, or too many tool definitions. The first fix is a smaller evidence set, not a larger dump.
What counts as a harness failure?
A harness failure happens when the model's intended fix is plausible but the system around it cannot execute the loop. Failed patch application, wrong working directory, permission loops, malformed tool calls, ignored test output, and retries that do not learn from errors all belong here.
Should I switch to Claude Code, Codex, or a hosted agent when local fails?
Use a hosted control as a comparison first. If the hosted route succeeds on the same minimal task and local still fails after one-layer diagnosis, use the hosted route for that task. If both fail, improve the task description, files, tests, or acceptance criteria before changing tools again.
What should I send when asking for help?
Send the smallest failure log: model/runtime, quantization, context files, harness, prompt, tool log, command output, test result, and one control comparison. Leave out secrets and private code that is not required to reproduce the failure.