Most Claude Code users default to markdown files and terminal prompts for giving the agent context. A technique gaining traction among practitioners flips that assumption: HTML files, not markdown, work better as persistent scratchpads for complex, multi-step coding sessions.
The pattern is simple. Instead of writing a PLANNING.md or stuffing requirements into a terminal prompt, you create an HTML file at the project root before starting a session. Claude Code reads it, works from it, and updates it as tasks complete. Open it in a browser and you have a live view of what the agent is doing and where things stand.
Why HTML Works Here
The core advantage is richness. HTML can communicate structure, task priority, and completion state in ways that flat text cannot. Checklists render visually, sections separate cleanly, and Claude can write back to the file without creating the formatting mess that tends to accumulate in long markdown documents. More practically, HTML files act as a stable anchor across a session. Claude Code's in-context memory - the running conversation - gets compressed as sessions grow long, which causes drift in complex projects. A file on disk doesn't get compressed. Keeping the task list, constraints, and open questions in an HTML file gives the agent something reliable to reference regardless of where it is in a session.
This matters most in projects that span dozens of files or require multiple coordinated changes. A single-file bug fix doesn't need the overhead. A refactor touching fifteen modules does.
The Practical Setup
- Create a
scratchpad.htmlorcontext.htmlat the project root - Include your goals, constraints, file map, and a task checklist
- Tell Claude at session start to read it and update it as work progresses
- Check the browser tab to track state without scrolling back through terminal output
This isn't an Anthropic-designed feature - it's a workflow developers arrived at by experimenting with how Claude Code handles files. The broader takeaway is that Claude Code's file system access is more useful as a communication layer than most users treat it. The terminal conversation is one interface. The file system is another, and for long sessions it's often the more reliable one.