What is the agent loop map?

A transition map showing what tool family follows what tool family during real coding sessions.

What did the map show?

The dominant core was search, edit, and shell. 81.7% of transitions stayed inside that triad.

What should operators do with this?

Improve the quality of search output, edits, and shell/test feedback before chasing more elaborate prompting.

The Agent Loop Map: Claude Code Is Mostly Search, Edit, Shell, Repeat

The public imagination of coding agents is still too chat-shaped.

The data says something else.

Claude Code is an execution loop. In my refreshed corpus, the dominant loop was:

search -> inspect -> edit -> run shell/test -> inspect result -> repeat

The corpus basis:

4,234 parsed session IDs
247,592 tool events
244,000+ tool-family transitions
Timestamp range: November 25, 2025 to May 6, 2026

The Finding

At the tool-family transition level:

Pattern	Transitions	Share
Same-family transitions	162,814	66.6%
Search/edit/shell core	199,557	81.7%
Shell/edit back-and-forth	28,359	11.6%

Top transitions:

Transition	Count	Share
shell -> shell	91,381	37.40%
file_edit -> file_edit	46,526	19.04%
file_edit -> shell	14,995	6.14%
shell -> file_edit	13,364	5.47%
file_search -> file_search	10,015	4.10%
file_search -> file_edit	9,233	3.78%
file_edit -> file_search	7,513	3.08%

The center of gravity is not exotic.

It is shell, files, search, and feedback.

Why This Is Non-Obvious

Agentic coding advice often overweights prompts, personas, and high-level planning rituals.

Those matter, but the loop map points somewhere more concrete:

Can the agent find the right code fast?
Are command outputs short enough to interpret?
Do tests fail with useful messages?
Are file edits narrow and reviewable?
Does the agent get structured reality back after every action?

The model is not operating in a vacuum. It is trapped inside the feedback loop you give it.

The So What

If 81.7% of the action lives inside search/edit/shell, then the biggest leverage is not a clever prompt.

It is improving those surfaces.

Practical moves:

Prefer rg over broad grep-style scans.
Ask for targeted file inspection before edits.
Keep command output narrow: one test file, one failure class, one diff.
Make test failures descriptive.
Make scripts deterministic and idempotent.
Put common checks behind short commands the agent can reuse.
Avoid dumping giant logs unless the agent asks for a specific slice.

This is loop-shaping.

The Operator Protocol

For Claude Code, use this working contract:

Before editing, locate the relevant implementation and call sites.
After editing, run the narrowest meaningful verification.
If verification fails, diagnose the failure class before retrying.

The "narrowest meaningful verification" line is what closes the verification-debt loop: the receipt the agent produces is the same artifact that turns "done" into a defensible terminal state.

That protocol maps directly onto the loop:

locate -> inspect -> edit -> narrow verification -> report receipts

It sounds plain because it is plain. Most of the gains come from removing noise from the execution loop.

The Counterintuitive Part

Adding more tools can make the agent worse if those tools add noise to the loop. And noise is where stuckness gets expensive: the same noise that confuses the loop also drives sessions into long error tails.

A bloated MCP server, a verbose test runner, or a noisy project script can cost more than it helps. The agent already spends most of its life in a small action core. Make that core better before you expand the surface area.

The top 0.01% agentic coder is not the person with the most plugins loaded.

It is the person whose agent gets the cleanest possible reality after every action.

The public query factory is here: MPIsaac-Per/claude-code-ops-audit.