# A CLAUDE.md and AGENTS.md task workflow that survives sessions

> A short CLAUDE.md or AGENTS.md snippet that makes an agent resume work in progress, claim the next task, ask with options and finish with a summary.

Source: https://taskhold.com/guides/claude-md-task-workflow
Last updated: 2026-11-16

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](https://taskhold.com/docs/quickstart) installs; the [agent message patterns](https://taskhold.com/docs/agent-messages) explain how to word progress and questions, and [Claude Code's built-in task list](https://taskhold.com/vs/claude-code-tasks) 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

```markdown
## 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](https://taskhold.com/docs/work-your-list).

```text
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](https://taskhold.com/for/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](https://taskhold.com/for/cursor) | AGENTS.md in the project root and in subfolders, alongside rules in .cursor/rules. |
| [Windsurf](https://taskhold.com/for/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](https://taskhold.com/for/vs-code) | The repo root, the session's working folder and the folders between, alongside .github/copilot-instructions.md. |
| [OpenCode](https://taskhold.com/for/opencode) | Walks up from the current folder; CLAUDE.md is the fallback when there is no AGENTS.md. |
| [Antigravity CLI](https://taskhold.com/for/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](https://taskhold.com/for/gemini-cli) | Only when you list it: "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } in settings.json. |
| [Claude Code](https://taskhold.com/for/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](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list) covers claiming and labels when they work at the same time, and the [integrations](https://taskhold.com/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:

```markdown
- 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.
```

Add to AGENTS.md (or CLAUDE.md) under the workflow block. Keep the agent label per agent, for example "Codex in api".

- 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.

## FAQ

### 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](https://code.claude.com/docs/en/memory), checked 2026-10-31
- [Codex docs: AGENTS.md discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md), checked 2026-10-31
- [Cursor docs: rules (.cursor/rules, AGENTS.md)](https://cursor.com/docs/context/rules), checked 2026-10-31
- [Devin docs: Cascade AGENTS.md](https://docs.devin.ai/desktop/cascade/agents-md), checked 2026-10-31
- [VS Code docs: custom instructions (copilot-instructions.md, AGENTS.md)](https://code.visualstudio.com/docs/copilot/customization/custom-instructions), checked 2026-10-31
- [OpenCode docs: rules (AGENTS.md, instructions)](https://opencode.ai/docs/rules/), checked 2026-10-31
- [Antigravity docs: rules (AGENTS.md, GEMINI.md)](https://antigravity.google/docs/rules), checked 2026-10-31
- [Gemini CLI docs: GEMINI.md (context.fileName)](https://geminicli.com/docs/cli/gemini-md), checked 2026-10-31

## Related

- [Claude Code task list over MCP: see progress live](https://taskhold.com/for/claude-code.md)
- [Codex CLI task list over MCP: watch tasks live](https://taskhold.com/for/codex.md)
- [How to see what Claude Code is doing, live](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [Run several coding agents in parallel on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Claude Agent SDK progress updates for long runs](https://taskhold.com/guides/claude-agent-sdk-progress.md)
- [Turn TODO comments into tasks as your agent works](https://taskhold.com/guides/turn-code-todos-into-tasks.md)

## Related guides from other Great Work products

- [Make Claude Code check production errors first](https://runheed.com/guides/claude-md-check-production-errors?ref=taskhold-related) (Runheed)
- [Have Claude Code fix and resolve production errors](https://runheed.com/guides/claude-code-fix-production-errors?ref=taskhold-related) (Runheed)

## About Taskhold

Taskhold is a hosted task list shared by a person and their AI coding agents over MCP. Agents break tasks into steps and report progress, and the person watches a live board. $12/month or $120/year per person, 7-day trial with a card, no free plan. Made by Great Work LLC.

To try it, add the MCP server https://taskhold.com/api/mcp to your agent. It connects with no sign-up, and the first time the agent uses Taskhold it gives you a link to start the trial.

- Pricing: https://taskhold.com/pricing.md
- Agent index: https://taskhold.com/llms.txt
