AI Coding Agents Need an Adult at the Shell

The reassuring news from a new study of AI coding tools is that they are not failing in some exotic, unknowable machine way. They are failing like software: at the seams, in the terminal, around configuration, and at the precise moment one component confidently hands a small flaming object to another component. The less reassuring news is that the software in question has access to your repository, shell, credentials, and an earnest belief that it has understood the assignment.

Researchers manually analyzed 3,864 closed bug reports from the public GitHub repositories for Claude Code, Codex CLI, and Gemini CLI, collected through December 12, 2025. Functional bugs accounted for 67% of the sample. The biggest concentrations were Tool/API Orchestration at 37.6% and Command Execution & Monitoring at 25%. The most common user-visible symptoms were API and server communication failures (18.3%), terminal experience problems (14.0%), and command-execution failures (12.7%). In other words, the agent often does not lose the plot while writing a loop. It loses the plot while attempting to locate the stage, plug in the microphone, and run the test command.

This is a systems problem, not a model personality test

That distinction matters for how you use these tools. When an agent produces questionable code, the familiar response is review, tests, and perhaps a brief period of staring at the diff with the expression of someone who has just found a semicolon in a place semicolons do not go. The study suggests you also need to inspect the workflow around the code: what it was allowed to call, which environment it actually used, whether the command succeeded, and whether its result is still relevant after the agent edited three more files.

The paper attributes 21.4% of the studied bugs to API and integration errors and another 15.9% to configuration and setup issues. Intrinsic AI logic and behavior accounted for 10.0%. This is not evidence that models are reliable little angels. It is evidence that a coding agent is a distributed-systems project wearing a chat interface, which is how we got here in the first place.

Put the agent somewhere it can make a mess politely

For exploratory or multi-file work, give the agent a disposable worktree rather than your one emotionally important checkout. Git supports linked worktrees, each with its own working directory, HEAD, and index. That means an agent can churn through a refactor on a branch without decorating your main worktree with half-applied edits and a new appreciation for the word “undo.”

git worktree add -b agent/fix-timeout ../api-agent-fix HEAD
cd ../api-agent-fix

Then begin in a mode that asks for a plan before it starts operating. Gemini CLI offers a read-only Plan mode through gemini --approval-mode=plan; its documentation also notes that the mode is still under development, so treat it as a useful brake, not an architectural proof. Ask for a file-level plan, the tests it intends to run, and the expected behavioral change. If the plan is vague, the implementation will be vague but with more files modified.

For tools that offer permission allowlists, begin by granting read-oriented commands rather than teaching the agent that every shell prompt is an invitation to autobiography. Claude Code, for example, documents --allowedTools for commands that can run without repeated permission prompts. A narrow first pass can permit repository inspection while holding back edits and arbitrary shell execution.

claude --allowedTools "Bash(git log:*)" "Bash(git diff:*)" "Read"

This is not about making the agent useless. It is about making the first five minutes cheap. Let it map the change, identify the relevant tests, and surface environmental assumptions before it gets to rewrite your package scripts because it encountered a missing dependency and felt creative.

Sandboxing is useful, but your repository is still real

If you are running unfamiliar code, working in a repository with sketchy fixtures, or simply do not feel like explaining a new global toolchain to future you, use a sandbox. Gemini CLI supports --sandbox and a tools.sandbox setting; its Docker-based sandbox mounts the current workspace so the agent can work there while being isolated from the rest of the host. That last clause is important. A sandbox protects the host more than it protects the branch. It is a seat belt, not a time machine.

gemini --sandbox -p "Inspect the failing test, propose the smallest fix, and do not modify files yet."

Spend 30 seconds reading every requested sandbox expansion, network permission, or command approval. That is not ceremonial skepticism. The study’s failure clusters are exactly where permissions, paths, APIs, shells, and tool schemas meet. The approval dialog is often the one place the system has stopped being an agent and started being legible.

Make the acceptance check independent of the agent

Do not accept “tests pass” as a status update. Accept a command you can run yourself. Before implementation, tell the agent the acceptance command. After implementation, run it outside the agent’s narration, then inspect the diff. git diff --check is a tiny additional guard: it exits nonzero for conflict markers or configured whitespace errors. It will not detect a broken feature, naturally. It is merely one more way to learn that the machine can produce a patch and a small mess simultaneously.

git diff --check
npm test

Replace npm test with the same targeted test or CI command your team trusts. If the change requires migrations, generated files, a service dependency, or a particular Node, Python, Java, or container version, write that down in the prompt. The study’s configuration findings are a fairly persuasive argument against relying on the agent to infer your local universe from a .env.example last updated during the previous CEO.

Do not turn this study into a leaderboard

The study is useful precisely because it is narrower than the discourse around coding agents. It examined closed, user-reported bugs in three tools; it did not reproduce every bug, measure failure rates per task, or establish that one tool is universally safer than another. Issue trackers also overrepresent failures that interrupt work and underrepresent mediocre output that a developer silently repairs. So the practical conclusion is not “never use an agent.” It is: select an agent for the work, but build your workflow assuming its integrations and execution path are ordinary software, with ordinary defects and unusually good marketing.

The agent can still save time on the boring middle: tracing code paths, drafting a focused patch, writing a first test, or explaining a crusty build failure. Just keep ownership of the boundaries. That is where the study says the bugs live, and where experienced developers have always known the rent is due.