Build an honest ETA display for your coding agent

The first article described the planning problem: should I wait, handle a small task or start another topic while my agent works? This walkthrough builds a small local record of the next expected attention window.

The example does not predict task duration automatically. You or your agent explicitly report a state and, when justified, a rough range. Its purpose is to make that information readable and stop stale forecasts from looking reliable.

1. Run an isolated example

You need Python 3 in a macOS or Linux terminal. Check with python3 --version. Download and inspect agent-eta.py, then save it in a temporary working directory. Run the commands below from that directory. No packages or changes to Claude Code settings are needed.

Each task needs its own local JSON file. Do not share one file between several agents. The parent directory must already exist.

python3 agent-eta.py --file ./eta-demo.json write --state working --phase verification --min 5 --max 12
python3 agent-eta.py --file ./eta-demo.json show

Initially, the output is approximately:

verification | WORKING | rough next-attention window 5-12m | declared, not calibrated

Five to twelve minutes is invented demonstration input. It is not a benchmark, a guarantee, or evidence about your actual task. The window describes when attention may next be needed, not when a finished solution is guaranteed.

2. Leave unknown time unknown

When there is no useful basis for a range, write only the state:

python3 agent-eta.py --file ./eta-demo.json write --state working --phase research

The display says next attention window unknown. It does not turn a missing estimate into zero. While a reported range remains valid, the renderer subtracts elapsed time. Once its upper boundary passes, it says declared window expired; refresh needed instead of leaving a misleading countdown at zero.

3. Report when a person is needed

python3 agent-eta.py --file ./eta-demo.json write --state needs-input --phase implementation
python3 agent-eta.py --file ./eta-demo.json write --state waiting --phase external
python3 agent-eta.py --file ./eta-demo.json write --state ready --phase review

Run these separately to represent real transitions; they are not a sequence to execute blindly. INPUT NEEDED takes priority over any range. READY FOR REVIEW does not assert that tests passed. An external wait without a supplied range remains unknown.

The script cannot observe an actual permission dialog or test result. The record is only as current and truthful as its writer.

4. Add explicit updates to the workflow

For an initial trial, update the record yourself at phase changes. If you later ask a coding agent to update it, give it the approved script and a separate file, require updates before requesting input and after work stops, and tell it to omit ranges it cannot justify.

That is a workflow instruction, not a verified automatic Claude Code integration. A native status line or lifecycle-hook adapter is separate work. A show call prints one snapshot; it does not create a live dashboard or poll in the background. You can call it whenever you check the task.

Observe whether it helps you choose a sensible activity for the gap. Do not infer “safe to leave” from the number alone: a question can still arise earlier than expected.

5. Test the limits and remove the record

The accompanying implementation was checked with synthetic clocks and inputs: missing or malformed files, unknown ranges, expired windows, attention states, invalid ranges and clock changes. A record older than 24 hours is marked stale. No real task-prediction accuracy has been established.

Only fixed state and phase names, an update timestamp and the supplied range are stored. There is no network call, prompt capture or historical archive. The same file is overwritten on update and is not automatically deleted. Remove eta-demo.json after the trial using your file manager. Removing the script and that file undoes this example; there are no agent settings to restore.

History-based calibration should come later, after comparable completed tasks exist. Until then, a declared range with a visible expiry is more useful than an exact-looking prediction with no evidence.