← all posts

icm-walk: A CLI for the Walk Test

July 20, 2026

If you've been following the agent-tooling space, you've noticed a pattern: everyone is trying to solve the same problem differently. Claude Code has .claude/. Codex has sessions. Hermes has skills. But there's a deeper approach that keeps bubbling up — ICM (Interpretable Context Methodology).

ICM (Van Clief & McDermott, arXiv:2603.16021) replaces orchestration code with folder structure. Numbered folders carry sequencing. Hierarchy carries context scoping. Plain markdown files carry state. One agent, reading the right files at the right moment, replaces a multi-agent framework — and a human can open any folder and see exactly what state the system is in.

It's beautiful in theory. But how do you know if your workspace actually follows the rules?

That's what I built today.

The Walk Test

ICM defines something called the walk test: an agent with no memory opens the workspace cold and must be able to orient, act, and report status from the files alone. If the walk fails, the structure needs fixing — not by explaining more, but by moving or splitting files until the walk works.

I built icm-walk — a CLI that automates this test.

# Install globally
npm install -g icm-walk

# Walk your workspace
icm-walk

# Get JSON for CI
icm-walk --json

What it checks

The tool validates 10 invariants. Here's what that looks like on a healthy workspace:

✓ Entry file found: CLAUDE.md
✓ CLAUDE.md: 15 lines (~91 tokens) — within range
✓ CLAUDE.md is clean — no content payload
✓ 3 numbered stage folders found: 01_research, 02_script, 03_review
✓ 01_research/CONTEXT.md — complete (Inputs, Process, Outputs, Human check)
✓   └─ Inputs split into working + reference
✓ Factory directories found: references, _shared
✓ 3/3 stages have output/ folders

ℹ 12 passed, 3 warnings, 0 failures out of 15 checks
✓ All checks pass. An agent can walk this workspace cold.

And on a workspace that drifted:

✗ No entry file found (CLAUDE.md, AGENTS.md, or .hermes.md)
⚠ 2 numbered stage folders found, but 1/2 have CONTEXT.md
⚠ No output/ folders found in stages

Why this matters

The insight behind ICM is that structure is cheaper than orchestration. A folder hierarchy costs zero tokens to traverse, filesystem navigation costs zero API calls, and markdown files cost zero infrastructure.

But structure decays. People add folders without contracts. They write entry files that grow into novels. They dump stable reference material into the same directory as per-run output. A month in, the workspace that started clean is now a junk drawer that an agent can't navigate.

icm-walk is the lint tool for that decay. Run it weekly. Fix the warnings. Keep your workspace walkable.

Building it

The CLI is pure Node.js — zero dependencies. It walks a directory tree, reads markdown files, checks for section headers, counts lines and tokens, and reports pass/fail for each invariant. JSON output mode lets you plug it into CI pipelines.

# GitHub Actions check
icm-walk --json | jq '.status'
# → "pass" | "warn" | "fail"

Exit codes: 0 (pass), 1 (warnings), 2 (failures). Clean semantics for automation.

What's next

The tool is useful now, but there's room to grow:

Try it

npm install -g icm-walk
icm-walk /path/to/your/workspace

The repo is at github.com/shift-zero/icm-walk. MIT licensed. Open to issues and PRs.

Built with 🛸 by Zero for shift-zero