How to see what your coding agent is doing right now

What the tools show on their own

The missing piece: progress the agent reports

Session views know whether a session is working or waiting. They can't tell you "step 3 of 5, 12 of 40 files migrated", because that lives in the agent's plan, not in the session. The agent has to write it down somewhere you can read, at the moments it knows something new: when it plans, between steps, inside a long step, and when it gets stuck.

So you need two things: a line in the agent's instructions, and a place for it to write. The two options below differ in where the progress lands and who can see it.

What should an agent report?

Four things are enough, at the moments the agent knows them:

1. A plan as ordered steps, before it starts. Three to seven steps is a useful size: enough to show movement, few enough to read at a glance.
2. Progress as it goes: "step 3 of 5" or N of M items, plus one short line about what it is doing now. Agents are far better at counting finished steps than at guessing a percentage.
3. Blocked, with one specific question, when it needs a decision, access or information from you.
4. Done, with a summary of what changed and how it checked the result.

Everything else (diffs, test output, reasoning) stays in the session and the pull request. The message patterns in the docs show how to write each report so a person can act on it from a phone.

Free option: a progress file in the repo

Ask the agent to keep a PROGRESS.md: the plan as a checklist, the current step, and a line per milestone. Add the rule to CLAUDE.md or AGENTS.md so every session does it:

## Progress
Before multi-step work, write the plan to PROGRESS.md as a checklist.
Tick each step when done and add one line: what changed, what's next.
If you're blocked, write the question at the top under BLOCKED.

Even without a file, three lines in CLAUDE.md or your rules give you most of the habit inside a single session:

Before starting a task, write your plan as 3 to 7 numbered steps.
After each step, say "Step N of M done: <one line>".
If you need a decision from me, stop and ask one specific question.

Where it falls short: you read it by opening the repo, there is no notification when the agent writes BLOCKED, parallel sessions in one repo edit the same file, and nothing tells you the agent went quiet an hour ago.

Taskhold: one live board for every agent

Taskhold is a task list your agents reach over MCP. The workflow snippet asks the agent to plan each task into steps with taskhold_plan, start and complete each step, and call taskhold_progress at milestones with percent or N of M and a short message. The live board shows it as it happens:

• A card per task an agent is working on: which agent, how long it has run, an estimate of time left once there is enough to go on, and the message from its last progress report.
• A progress bar split into one segment per step, so you see which step is running and which one is blocked.
• Blocked tasks at the top under Needs you, with the agent's question and a box to reply, or reply and unblock.
• A status dot: Live if the agent reported in the last two minutes, Quiet after that, and No word, with how long ago, after fifteen minutes. A stalled agent stands out without you reading its terminal.
• Optional desktop notifications when an agent gets blocked or finishes, and a count in the tab title while you're in another tab.

The time estimate is simple on purpose: elapsed time divided by progress so far, shown once the task is at least 5% done and has run for 30 seconds. Steps that take very different times make it rough; the step list tells you more than the number.

## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).

Want the same bar inside Claude Code or a terminal? The Taskhold CLI sets up the Claude Code status line with one command (taskhold-mcp statusline --install) and runs the board in a terminal (taskhold-mcp watch). A short script does the status line too: see the status line recipe or the status line generator.

How does the agent get your reply?

The agent asks Taskhold what changed since it last looked, with taskhold_updates. The call takes a cursor and returns only what you changed: replies, new tasks, priority changes. Agents call it at the start of a session and between steps, so you can steer one mid-task without stopping it. Answering a blocked agent walks through the full loop, including notifications.

How do you know an agent stopped?

Liveness tells you, not the bar. Each card shows Live if the agent reported in the last two minutes, Quiet after that, and No word, with how long ago, after fifteen minutes. A card at 90% with No word usually means the session ended and the task needs someone to pick it up again. The bar shows what the agent last said; liveness shows whether it is still saying anything.

How the live board is built

Every change an agent or a person makes (create, status, progress, note, edit) writes a row to an events table, and the row id is the cursor for everything: the board, taskhold_updates and the REST API. The board streams new rows over Server-Sent Events, with an in-process wake for instant updates, a 3 second poll as a backstop and a 15 second ping so proxies keep the connection open.

One gotcha if you build SSE on Next.js: its compression buffers the stream unless the response sends Cache-Control: no-transform, and nginx needs X-Accel-Buffering: no. The events reference documents the stream and the polling fallback.

Checking from your phone

The live board is a web page, so a phone browser shows the same cards, steps and blocked questions, with the reply box. For Claude Code alone, the Claude app with Remote Control lets you drive the session itself; Taskhold is the view across Claude Code, Codex, Cursor and anything else you've connected, without a session open.