A CLAUDE.md and AGENTS.md task workflow that survives sessions
By Jake Marsh, who builds Taskhold. Updated 2026-11-16. Facts about other tools checked 2026-10-31. 9 min read.
Agents follow what's in CLAUDE.md (Claude Code) or AGENTS.md (Codex, Cursor and others). A few lines there decide whether a new session starts from zero or picks up where the last one stopped, and whether it reports steps and progress to a live board you can watch. The snippet below is the one the quickstart installs; the agent message patterns explain how to word progress and questions, and Claude Code's built-in task list is compared at the end.
Most agents other than Claude Code read AGENTS.md, so one copy of the block can serve Codex, Cursor, OpenCode and the rest. The two AGENTS.md sections below list which agents read it and add a fuller block with answer buttons, a What changed card and a review queue.
The snippet
## Tasks (Taskhold)
The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
Pass project: "<repo folder name>" on every call (created on first use, no ids needed).
- Session start: taskhold_get_current and taskhold_updates, both with project. Keep the cursor.
- New request: taskhold_begin with title, project, steps and agent: "<client> in <repo>". It files the task, plans the steps and starts the first one. Queued work: taskhold_next with project and agent takes the next To Do task and starts it; after each one, call it again until it says To Do is empty.
- Project notes in a reply (stack, commands, what done means, what to avoid) are the person's rules for every task in that project.
- Each step done: taskhold_complete with start_next: true. Steps drive the progress bar.
- Long step: taskhold_progress on the step (N of M, or a percent) with a short message. Every few minutes at most.
- Need a decision: taskhold_block with one specific question, then taskhold_updates with task_id, since and wait: 50 until the reply arrives.
- Done: taskhold_complete on the task with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create with project (or taskhold_create_from_todo with file and line).It assumes the Taskhold MCP server is connected. The same structure works with any task tool your agent can reach.
Why each line is there
- get_current first: a session that ended mid-task left it in progress, with its steps. Checking first stops the agent from starting something new and abandoning it, and tells it which step is next.
- updates, keeping the cursor: anything you changed or answered while no session was running reaches the agent before it starts.
- taskhold_next for queued work: it takes the next task in To Do (highest priority first, then oldest, or newest if you choose that in Settings) and starts it, so the agent doesn't have to guess and two agents never take the same one.
- Project notes: the stack, commands, definition of done and things to avoid you wrote for the project arrive with every task in it, so the snippet stays short.
- start with a label: marks the task as claimed, so another agent doesn't take it, and puts a name such as "Codex in api" on the live board.
- plan, then start and complete each step: you get a checklist and a bar that fills step by step, and a session that dies leaves a clear point to resume from.
- progress at milestones: "12 of 40 files" with a short message is what makes the bar and the time estimate useful during a long step. Every few minutes at most is enough.
- block with a specific question, then read updates: turns "I'm not sure what you want" into a question on the board that you answer once, and the agent picks the answer up instead of guessing.
- complete with a summary: what changed, in a sentence, attached to the task.
- create / create_from_todo: things the agent notices but shouldn't fix now become tasks instead of comments nobody reads.
Variations
- One repo of several: "Pass project: <repo folder name> on every taskhold call."
- Review gate: "Never complete a task that changes the database schema; block it for review instead."
- Several sessions of one client: "Use a label with the worktree name, such as Claude Code in api-auth."
- Short tasks: "Skip taskhold_plan when the work is one step; start and complete is enough."
Work the list: a loop for queued tasks
The snippet handles one request at a time. To have the agent work through everything in To Do, paste this prompt at the start of a session. It loops taskhold_next, the work, taskhold_complete and taskhold_next again until the list is empty, and blocks with a question instead of guessing. Prompts to plan a goal into tasks, keep waiting for new ones, resume after a crash and stop cleanly are in work your list.
Work through my Taskhold list for project "<project>", one task at a time.
1. Call taskhold_next with project "<project>" and agent: "<your client> in <project>". It takes the next task in To Do and starts it.
2. Read the task, its notes and the project notes in the reply. If it needs more than one step and has none, plan them with taskhold_plan.
3. Do the work. Finish each step with taskhold_complete and start_next: true. On a long step, report progress with taskhold_progress.
4. When the task is done, taskhold_complete it with a summary and an outcome (files, checks, how you verified it).
5. Call taskhold_next again. Stop when it says To Do is empty, and tell me what you finished.
If you need a decision, block that task with one question (taskhold_block) and move on to the next task instead of guessing.
Never spend money, touch credentials or secrets, publish or deploy anything, or delete anything that can't be undone without asking first: block the task with the question instead.
If you have to stop before a task is done, taskhold_release it with a note on where it stands.Which agents read AGENTS.md
AGENTS.md is plain markdown at the repo root with no frontmatter, and each agent finds it a little differently. A summary from each agent's docs, with the full setup on its own page:
| Agent | How it reads AGENTS.md |
|---|---|
| Codex | ~/.codex/AGENTS.md first, then one file per folder from the repo root down to where you started it. Stops adding files at 32 KiB by default. |
| Cursor | AGENTS.md in the project root and in subfolders, alongside rules in .cursor/rules. |
| Windsurf | AGENTS.md at the workspace root and in each folder down to the one it's working in, all as always-on rules. |
| VS Code Copilot | The repo root, the session's working folder and the folders between, alongside .github/copilot-instructions.md. |
| OpenCode | Walks up from the current folder; CLAUDE.md is the fallback when there is no AGENTS.md. |
| Antigravity CLI | AGENTS.md or GEMINI.md in the workspace folder and each parent up to the repo root, always on. Subfolders below the workspace aren't read. |
| Gemini CLI | Only when you list it: "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } in settings.json. |
| Claude Code | Only when the repo has no CLAUDE.md (v2.1.277 and later). With a CLAUDE.md, add a line with @AGENTS.md to it. |
Checked against each agent's docs on 2026-10-31. Cline, Amp, Goose, Junie, Kiro, Warp, Zed and other agents on the integrations page read it too.
In a repo that several kinds of agent work in, keep the Taskhold block in AGENTS.md only and point CLAUDE.md at it with @AGENTS.md, so the two files never disagree. Running several coding agents on one list covers claiming and labels when they work at the same time, and the integrations cover the other agents' files.
A fuller AGENTS.md block: options, outcome and review
Once the basic loop works, three more tool arguments make the board easier to act on. They fit in a few lines under the snippet above:
- A choice you can't make: taskhold_block with one question, 2 to 4 options,
recommended (the index of the one you'd pick) and if_no_answer (what you'll do otherwise).
- Done: taskhold_complete with a summary and an outcome: files changed, checks run
(pass/fail/skip), links (PR, commit, branch) and verify (how you checked it).
- Changes to the schema, auth, billing or anything that deletes data: also pass
needs_review: true on the task. It needs outcome.verify.- options show as buttons under Needs you, so you answer with one tap from your phone. The agent gets your reply as a note, for example: chose "Keep it nullable".
- recommended marks the option the agent would pick, and if_no_answer tells you what happens if you don't get to it.
- outcome shows as a What changed card on the task. Every field is optional, and a step's outcome rolls up to its task.
- needs_review puts the finished task in your Ready for review queue. The task still counts as done, and your approval or request for changes reaches the agent through taskhold_updates.
Answer your coding agents from anywhere.
$12/month or $120/year after the trial. Card up front. Cancel before day 7 and you pay nothing. Every agent you run is included.
Or connect your agent first, no sign-up: add https://taskhold.com/api/mcp as an MCP server. The first time it uses Taskhold, it gives you the trial link.
Questions
- Where does the file go?
- CLAUDE.md in the project root (or ~/.claude/CLAUDE.md for all projects) for Claude Code; AGENTS.md in the project root for Codex and other agents that read it; Cursor also reads rules in .cursor/rules.
- Do I have to write it myself?
- No. Taskhold's setup URL gives the agent this snippet along with the server config.
- Should the block go in CLAUDE.md or AGENTS.md?
- Use AGENTS.md when more than one kind of agent works in the repo, and add @AGENTS.md to CLAUDE.md so Claude Code loads it too. If only Claude Code works there, CLAUDE.md alone is fine. Keep the block in one file so the copies can't drift apart.
- Why does the agent need to be told to report progress?
- Agents use the tools they are told about. Without the plan and progress lines, an agent may only start and complete tasks, and the live board can only show that a task is in progress, not how far along it is.
Sources
- Claude Code docs: CLAUDE.md and AGENTS.md, checked 2026-10-31
- Codex docs: AGENTS.md discovery, checked 2026-10-31
- Cursor docs: rules (.cursor/rules, AGENTS.md), checked 2026-10-31
- Devin docs: Cascade AGENTS.md, checked 2026-10-31
- VS Code docs: custom instructions (copilot-instructions.md, AGENTS.md), checked 2026-10-31
- OpenCode docs: rules (AGENTS.md, instructions), checked 2026-10-31
- Antigravity docs: rules (AGENTS.md, GEMINI.md), checked 2026-10-31
- Gemini CLI docs: GEMINI.md (context.fileName), checked 2026-10-31
Related
- Claude Code task list over MCP: see progress live
- Codex CLI task list over MCP: watch tasks live
- How to see what Claude Code is doing, live
- How to hand tasks to your coding agent
- Run several coding agents in parallel on one list
- Claude Agent SDK progress updates for long runs
- Turn TODO comments into tasks as your agent works
Related guides from other Great Work products
Updated 2026-11-16. Something wrong or out of date? Email hello@greatwork.company.