Progress

The progress tool lets a subagent send an intermediate status update to its parent orchestrator without stopping the session — the counterpart to complete (ends the session) and clarify (pauses it). The update arrives as a ⏳ system message via the parent’s LOOP_CONTINUE hook.

The tool is opt-in and enabled automatically for subagents; enable it explicitly with -t +progress.

Progress tool — subagents use this to send intermediate updates to the parent.

Registers the progress block type so subagents can report status mid-task without stopping their session. The parent orchestrator receives these updates via the LOOP_CONTINUE hook as ⏳ system messages, enabling the “fire-and-forget- then-get-alerted-when-update/done” pattern alongside complete and clarify.

Unlike complete (ends session) and clarify (pauses session), progress continues execution after delivering the update.

Delivery modes:

• Thread-mode subagents: uses the in-process _progress_queue; the parent’s LOOP_CONTINUE hook picks it up on the next iteration.

• Subprocess-mode subagents: writes JSON lines to GPTME_PROGRESS_FILE (set by the parent before spawning); the parent’s monitor thread polls that file and delivers updates via the same hook path.

Only enabled in autonomous/subagent sessions (disabled_by_default=True).

gptme.tools.progress.execute_progress(code: str | None, args: list[str] | None, kwargs: dict[str, str] | None) → Generator[Message, None, None]

Send an intermediate progress update to the parent orchestrator.

In thread mode: reads the current agent_id from thread-local storage (set by _create_subagent_thread) and pushes the update to the shared _progress_queue. The parent’s LOOP_CONTINUE hook delivers it as a ⏳ system message.

In subprocess mode: writes the update to the file pointed to by GPTME_PROGRESS_FILE (set by the parent). The parent’s monitor thread polls that file and delivers the update via the same hook path.