Try Turborg Free → Open Turborg →
← All posts

My AI Coding Agent Works Perfectly on a Demo, Then Choked on My Actual Project. Here's Why.

July 8, 2026 · 5 min read · The xShellz Team

My AI Coding Agent Works Perfectly on a Demo, Then Choked on My Actual Project. Here's Why.

I was excited. I'd just hooked up a local 7B model to an agent loop, gave it a codebase, and told it to rename a class across 12 files and update every import. The demo repo worked like a charm. Then I pointed the same setup at my real project, a Rust CLI with about 40 source files, and watched it fall apart: the agent hung, files got partially written, and one time it left a lock file behind that broke my build until I rebooted.

The model itself wasn't the problem. Inference ran fine on an RTX 4090. What actually killed the workflow was a series of file system bottlenecks that most agent demos conveniently ignore. If you're serious about agentic coding with local models, you need to understand why your laptop's file system is the silent enemy.

Agentic workflows demand an obedient file system

A typical coding agent loop looks simple: the model receives a task, it plans a series of tool calls (read, write, shell command), and it executes them. Under the hood, though, this often translates to dozens of rapid fire file operations in a single turn: grep patterns across files, read multiple candidates, buffer the changes, and then atomically replace chunks of text. If the model decides to refactor a module boundary, it might touch 20 files in under five seconds.

Your local machine was never designed for that kind of abuse. macOS in particular has a famously slow metadata layer. APFS is copy on write friendly, but opening and scanning dozens of small files in quick succession still thrashes the kernel's vnode cache. Windows Defender or real-time virus scanners will happily inspect every temp file the agent creates, adding hundreds of milliseconds per access. Even on Linux, the ext4 journal can become a bottleneck when an agent writes many small chunks while holding file descriptors open.

The result is not just slowness. It's nondeterministic failure. The agent's tool calls time out because fsync took 800 ms instead of 30 ms. Partial writes make the diff engine panic. These failures then poison the model's context. It sees errors it cannot fix, retries, and descends into a spiral of bad repairs that eventually exhaust its context window.

The file-locking landmine

And then there is locking. When your agent spawns a shell command to run a linter or formatter after a refactor, that command often opens the same set of files the agent just wrote. On a local machine, especially one where you might also have an IDE with file watchers running, you get contention.

I hit this hard with cargo fmt. The agent wrote the updated files, then fired off cargo fmt --all. But my editor had a file watcher that briefly locked the now-modified file, causing the formatter to skip it with a silent warning. The agent assumed success, committed the change, and the CI later exploded because one file wasn't formatted. That's a bug that survives 20 agent retries because the model has no visibility into the OS locking state.

There's a deeper issue too: local filesystems give you weak consistency guarantees. Writing a file, closing it, and immediately reading it back doesn't always reflect the final state if the OS write cache hasn't flushed. NVMe drives on modern laptops mask this with low latency, but the moment you push past a few dozen operations per second, you'll see mysterious stalls that look like model unresponsiveness but are actually I/O wait.

Resource contention you can't see

Local LLM inference is already a resource hog. A 7B model quantized to 4-bit uses about 6 GB of VRAM, leaving little headroom for the CUDA context. But your OS, browser, and IDE are also using the GPU. Even if you offload to a separate GPU, the PCIe bus and system memory bandwidth are shared. When the agent loop simultaneously runs inference, hits the disk, and spawns parallel shell processes, your system's memory controller is saturated. You'll see the agent's latency spike, not because the model slowed down, but because the kernel is busy paging.

I've measured this. On an M2 Max MacBook Pro with 64 GB of RAM, running a 13B model with MLX and an agent that refactors 15 files, the system's iowait CPU time went from 2% to 34% during the tool execution phase. The model was waiting on the OS, not the other way around.

The fix: a dedicated, no-compromise Linux environment

If you're going to let an AI agent run unattended for hours, you need a machine where:

  • The file system is fast and predictable, with no antivirus or file watchers you didn't ask for.
  • There's no GUI session or desktop environment contending for I/O.
  • File locks behave as expected under POSIX, with no surprise mandatory locks from third party software.
  • The storage stack is tuned for synchronous I/O and high IOPS, not power saving.

That's hard to achieve on a daily driver laptop. It's trivial on a dedicated cloud Linux instance. Remote development environments have been the answer for compile-heavy workloads for years. Now they solve the agent bottleneck too. A mid-tier VPS with an NVMe volume will easily push 50,000 IOPS with sub-millisecond latency. That's more than enough to keep a model's tool execution loop from ever stalling on I/O.

How xShellz fits into this

We built xShellz to give developers exactly this kind of environment: always-on remote Linux shells with no noisy neighbors, persistent home directories, and full root access when you need it. Our underlying storage is NVMe backed, so grep across a large tree and atomic rewrites of 30 files finish in the blink of an eye. More importantly, our borg agent runs directly on those hosts, co-located with the file system it manipulates. There is no network round trip between the agent and the disk. That's the kind of tight coupling that makes multi-file refactors reliable.

I'm not saying you can't do agentic coding locally. But if you've been banging your head against mysterious timeouts, partial writes, and lock files that survive a reboot, try pointing your agent at a remote Linux box instead. You might find the model was smarter than you thought. It just needed a file system that cooperates.