Try free

Last updated 13 October 2026

Convert a Claude plan into a checklist

The challenge of tracking complex plans in the terminal

You ask Claude Code to perform a large refactor or implement a new feature. The agent analyzes your repository and provides a comprehensive twelve-step plan in the terminal. You review the steps and give the agent permission to proceed. As the agent begins to work, it uses the Bash tool to run tests and the Edit tool to modify files. Every change generates a diff or a log that scrolls past your view. By the time the agent reaches the fourth or fifth step, the original plan has vanished from your screen.

Relying on the scrollback buffer is a fragile way to manage a project. If the agent encounters a build error or a failing test, it will focus on fixing that specific problem. This detour can lead to a long exchange of commands and summaries that completely bury the initial roadmap. You might find yourself wondering if a specific part of step three was actually finished or if the agent skipped ahead. Without a persistent record, you lose the ability to verify progress at a glance and must spend time scrolling up to find the original context.

Use planning mode to capture structured steps

You can gain better control over the execution process by changing the permission mode. Press Shift+Tab inside a session to cycle through the available modes until you reach the plan mode. In this state, the agent focuses on describing its intended actions instead of executing them immediately. This is the ideal moment to request a structured breakdown of the work. You can instruct the agent to list every file it needs to read and every modification it plans to make before any tools are actually invoked.

Planning mode prevents the agent from starting a task before you have a clear understanding of the full scope. It allows you to refine the strategy and catch potential issues early. For example, if you notice the agent missed a specific configuration file in its plan, you can correct it before the first Edit tool call occurs. This upfront planning phase serves as the raw material for your persistent checklist. Once the agent provides a satisfactory list of steps in the terminal, you are ready to move that information into a more stable format.

Create a persistent checklist file in your repository

Do not leave your plan in the volatile memory of the terminal session. Instead, tell the agent to use the Write tool to create a new file named TASKS.md in your repository root. Instruct the agent to format this file using standard Markdown task list syntax. Every step from the plan should be a checkbox item. This file becomes your source of truth for the duration of the feature development. You can keep this file open in your IDE alongside the terminal to maintain a constant visual reference of the project status.

This approach creates a physical asset that survives any terminal disruption. If your terminal crashes or you need to restart your computer, the plan remains safely on your disk. You no longer need to worry about the history buffer size or the searchability of the terminal scrollback. The TASKS.md file provides a clear and concise view of what has been decided. It acts as a bridge between your high-level goals and the low-level tool executions that the agent performs.

Embed the plan into project instructions for context

The CLAUDE.md file is the primary way to provide persistent instructions to the agent across different sessions. Claude Code reads this file at the start of every session and uses it to understand project standards. You should add a specific instruction to your root CLAUDE.md file that directs the agent to look for TASKS.md. Explicitly state that the agent must check this checklist before starting any work and update it as it progresses. This ensures that the agent stays aligned with your plan even after you use the /clear command.

Integrating the checklist into CLAUDE.md transforms it from a simple note into a functional part of the agent's workflow. When you start a new session using the claude command with the -c flag, the agent immediately knows where it left off. It will read the instructions in CLAUDE.md, find the TASKS.md file, and see which items remain unchecked. This setup eliminates the need to re-explain the plan every time you resume work. It provides the agent with a long-term memory that spans multiple sessions and restarts.

Automate status updates during the execution phase

Manually updating a checklist is a chore that you can delegate to the agent. Instruct the agent that every time it completes a step using the Bash or Edit tools, it must immediately use the Edit tool to mark that task as complete in TASKS.md. You can also use the TodoWrite tool to add new sub-tasks or reminders as they arise during the coding process. This creates a real-time feedback loop where the file always reflects the actual progress of the work. You can watch the checkboxes fill up as the agent moves through the project.

By making the update process part of the agent's instructions, you ensure that the documentation never lags behind the code. If the agent hits a roadblock and needs to change the plan, it should update the TASKS.md file to reflect the new strategy. This practice keeps you informed without requiring you to constantly prompt the agent for status updates. The agent becomes responsible for its own progress tracking, which allows you to focus on reviewing the code and providing high-level guidance.

Monitor multiple plans simultaneously with a tiled interface

When you manage several complex refactors across different projects, a single terminal window often feels insufficient. This is a scenario where adhdTerminal provides a distinct advantage by allowing you to run many Claude Code sessions side by side. Each session is displayed as a tile on a wall, which you can name and color-code to match your different project tasks. You can have one tile dedicated to a backend API update and another to a frontend component migration, each with its own checklist visible in its respective workspace.

The tiled interface helps you maintain mental focus by giving you a bird-eye view of all ongoing work. You can see at a glance if a tile is working, waiting for your input, or idle. This visual feedback is essential when you are balancing multiple plans. Instead of switching between terminal tabs and trying to remember the state of each project, you can simply look at your wall of tiles. The adhdTerminal app ensures that your environment is organized and that every plan has its own dedicated space to execute.

Preserve plan details during context summarization

As a session grows longer, the context window fills up with conversation history and file content. You may need to use the /compact command to summarize the session and free up space for more tokens. While /compact is excellent for maintaining performance, a summary can sometimes lose the granular details of a long-term plan. By keeping your primary checklist in the TASKS.md file, you protect that information from being compressed or omitted. The agent can always refer back to the raw Markdown file for the exact details of the remaining steps.

This separation of the plan from the conversation history makes your sessions more efficient. You can /clear the session to start with a fresh context window whenever things get cluttered, knowing that the agent will simply read the checklist again. This keeps the agent's focus sharp and reduces the risk of hallucinations caused by an overloaded context window. A clean session with a clear file-based plan is much more reliable than a long, messy session that relies on memory alone.

Track progress remotely via mobile mirror

Sometimes a task takes a long time to run, such as a full test suite or a complex build process. You might want to step away from your desk but still keep an eye on the checklist progress. The adhdTerminal mobile app mirrors your workspace over an end-to-end encrypted link, allowing you to see the status of your tiles from your iPhone. You can check if the agent has marked the current task as complete or if it is waiting for your permission to proceed with the next step in the plan.

The ability to interact with your sessions remotely means you do not have to be tethered to your workstation for the duration of a long plan. If the agent completes a step and needs to know which task to tackle next, you can send a quick prompt from the mobile app. This keeps the momentum of your project moving forward even when you are not physically at your computer. The combination of a persistent Markdown checklist and a mobile-monitored workspace gives you total visibility into your development pipeline at all times.

Questions people ask

Will the agent automatically know how to use the checklist file?

The agent will only use the file if you explicitly instruct it to do so. You should add a rule to your CLAUDE.md file stating that the agent must read TASKS.md at the start of work and update it after every tool use. This ensures the behavior is consistent every time you start the claude command.

Can I use /clear without losing the progress on my plan?

Yes, because the checklist is stored in a physical file on your disk rather than just in the session memory. After you run /clear, the agent will lose the conversation history, but it can immediately regain its context by reading the TASKS.md file again. This is the most reliable way to maintain a long-running plan.

What should I do if the agent skips a step in the checklist?

If the agent skips a task, you can use the /permissions command to switch to plan mode or a more restrictive mode to stop its execution. Point out the skipped item and ask the agent to complete it before moving on. Maintaining a strict rule in your CLAUDE.md file about following the checklist order helps prevent this behavior.

Read next

More on claude code basics·All posts