Session goals
Goals let you give an AFK session an explicit objective that the agent should keep working toward across turns. While a goal is active, AFK tracks progress, keeps the objective in context, and can automatically continue the session until the goal is completed, blocked, cleared, or reaches its configured limits.
When to use a goal
Use a goal when the work is bigger than a single prompt and you want AFK to keep making progress without repeatedly nudging it. Good examples are "fix the checkout test suite", "add docs for the new webhook API", or "investigate this production error and report the likely root cause".
For short one-off questions, normal chat prompts are usually enough. For high-risk or ambiguous architecture changes, ask the agent to use plan mode before it edits files.
Start a goal
In a session, start a goal from the browser UI when the goal controls are available, or send a /goal command in chat:
/goal Update the docs website with the new session goal workflowAFK records the goal objective on the session, forwards the objective to the running agent, and shows the current goal state to connected browser clients. The visible chat history keeps the /goal command, while the agent receives the objective as the task text.
What AFK tracks
Goal state is persisted with the session, so it can be restored after a reconnect or resume. AFK tracks:
- the objective and current status
- token usage since the goal started
- elapsed time and turn count
- an optional token budget
- an optional maximum number of continuation turns
Continuation behavior
After an agent turn finishes, an active goal can trigger a silent continuation turn. The continuation reminds the agent to keep working toward the original objective, not narrow or redefine it, and to mark the goal complete only after verifying the result against actual state.
Continuations are intentionally invisible as normal user messages. They are control-plane prompts that keep the agent moving, while the browser shows the goal status and normal transcript activity.
AFK displays the active goal in the session UI. You can use it to review progress, change available limits, or clear the goal when you no longer want automatic continuation.
Completion and blocked states
Agents have two built-in goal tools:
| Tool | Use |
|---|---|
get_goal | Reads the active goal, including objective, status, tokens used, elapsed seconds, turn count, token budget, and continuation limit. Returns {"status":"none"} when no goal is active. |
update_goal | Sets the active goal status to complete or blocked. Agents should use complete only after the objective is fully achieved and verified, and blocked only when the same blocker has repeated for at least three consecutive turns and user input is required. |
Limits and clearing
Goal limits help bound unattended work. A token budget can stop continuation once the session has consumed the configured goal budget, and a maximum continuation-turn setting can cap how many automatic follow-up turns AFK sends.
Clearing a goal removes the active goal from the session, broadcasts an empty goal state to browsers, and tells the agent that goal tracking has ended. Clearing does not delete the transcript or undo work already performed.
Best practices
- Write the goal as an outcome, not a vague activity.
- Include the success condition: what should be true when the goal is complete?
- Set limits for exploratory or potentially expensive work.
- Use approvals and plan mode for risky edits even when a goal is active.
- If the agent reports a blocker, answer the missing question or clear the goal before changing direction.