Fixing the broken shell execution in Claude Code

I spent four hours last Wednesday fighting a permissions loop that almost made me uninstall Claude Code and go back to a standard IDE plugin. I was trying to automate a migration of a legacy Express.js project to TypeScript, and the CLI kept hitting a wall when trying to run npm install after updating the package.json.

The fix wasn't in the prompt, but in how I handled the tool-use permissions. If you're using Claude Code and it keeps asking for permission to run the same command three times, or fails with a cryptic shell error, you're likely hitting the same wall I did.

Why did the shell keep failing during the migration?

I was running claude in a directory with a mix of root-owned files (remnants of a Docker volume mount). When Claude tried to execute a shell command to verify a file change, it hit this:

Error: EACCES: permission denied, open '/Users/dev/project/node_modules/.bin/tsc'

The annoying part? Claude didn't just tell me it failed. It tried to "fix" it by suggesting chmod commands, which then failed because the CLI session didn't have sudo privileges. I was stuck in a loop where the AI was trying to be helpful, but the environment was locked.

I realized the bottleneck wasn't the AI's logic—it was the session's execution context. I had to kill the process, fix my local folder permissions via sudo chown -R $USER ., and restart the CLI.

The lesson here is that Claude Code is an agent with a shell; it's not just a chat box. If your environment is messy, the agent will spend more tokens trying to fix your OS than fixing your code.

How to actually get a migration started without the loop

If you're looking for a Claude Code tutorial that isn't just "type these commands," start with a targeted scope. Don't just say "convert this to TypeScript." That's how you end up with a broken tsconfig.json and a thousand linting errors.

Here is the exact sequence I used to successfully migrate my controllers after fixing the permission bug:

1. Index the project first. Let it read the files.
2. Create a specific migration plan. Ask it to list every file that needs a .ts extension.
3. Execute in batches.

I found that asking it to do 5 files at a time kept the context window clean. When I tried to do 20 files in one go, it started hallucinating imports from files it hadn't actually converted yet.

| Approach | Result | Token Cost (Est.) | Success Rate |
| :--- | :--- | :--- | :--- |
| "Convert everything" | Massive merge conflicts | High | 40% |
| Batch of 5 files | Clean compiles | Medium | 90% |
| File-by-file | Tedious but perfect | Low | 100% |

Dealing with the "Too Many Tool Calls" bottleneck

Another wall I hit was the tool-call limit. While working on a complex refactor, Claude started looping—reading a file, searching for a string, reading the file again, and then searching for the same string.

It looked like this in the terminal:
Reading file...
Searching for 'UserSchema'...
Reading file...
Searching for 'UserSchema'...

This is a waste of money and time. I stopped the execution and shifted my approach toward AI Coding patterns that emphasize "Plan first, execute second." I told it: "Stop searching. Read the entire models/ directory into your context once, then tell me where the schema is."

Suddenly, the loop stopped. The trick is to realize that the agent sometimes forgets it already read a file if the conversation gets too long. Forcing a "consolidated read" saves you from the repetitive tool-call cycle.

Where to find better patterns than the default docs

The official docs are fine for installation, but they don't tell you how to handle the "AI drift" that happens during a three-hour coding session. This is where I actually found value in the PromptCube community.

Instead of guessing how to structure a request for a complex refactor, I started looking at Prompt Sharing threads. I found a specific pattern for "Architectural Guardrails" that I now paste into my initial session: "Before modifying any file, describe the change in one sentence. If the change affects more than three files, stop and ask for confirmation."

This one line prevents Claude Code from rewriting half your project because it decided to rename a variable globally.

Recommended setup for a smoother experience

If you're just starting, don't just run it in a random folder. Set up a dedicated environment.

• Version Control: Never run Claude Code on a clean branch. Always have a git checkout -b ai-experiment branch. It will delete things. It's a fact.
• MCP Servers: If you need it to interact with your database or Jira, set up the Model Context Protocol (MCP) servers first. Trying to "teach" the AI how to use a tool via chat is inefficient; giving it a formal MCP connection is a game-changer.
• Resource Management: Check out the Resources section of the community to see which MCP servers are actually stable. Some of the community-made ones crash the CLI every ten minutes.

The real power of Claude Code isn't the "coding" part—it's the "agent" part. It can run tests, see the failure, and fix the code. But that only works if you provide a stable, permission-correct environment. If you see EACCES or Permission Denied, stop the AI, fix the OS, and then resume. Don't let the AI try to fix your Linux permissions unless you've given it a very specific, narrow scope to do so.