Persistent Goals: The /goal Command in Depth

The Problem with Finishing

Ask a language model to do a complex task. It works through it, produces output, and then tells you it's done. How do you know it's actually done? Before v0.18, the answer was: you don't, not without checking. The agent would stop when it felt like the task was complete — when its own assessment of completeness triggered the end of the agentic loop. That assessment is not verified. It is an assertion.

The /goal command is Hermes' answer to this. A goal is a persistent objective that Hermes pursues across multiple conversation turns until a separate judge model — not the agent itself — confirms that the goal has been met. The agent does not get to decide it's done. The judge does.

How the Judge Loop Works

When you set a goal with /goal <text>, Hermes activates a judge loop that runs after every turn in the session. The judge is a lightweight auxiliary model — separate from your main model — that receives the conversation history and evaluates whether the goal has been satisfied.

The judge applies three completion criteria. A goal is marked complete when:

• The assistant's response explicitly confirms the goal is complete (not just implies it)
• The final deliverable has been clearly produced — the file exists, the test passes, the output is present
• The goal is unachievable or blocked — the agent cannot proceed without external input

If none of these criteria are met, auto-continuation fires: Hermes sends another turn to the agent, instructing it to continue working toward the goal. This repeats until the judge confirms completion, until you manually pause or clear the goal, or until the turn budget (default: 20 continuation attempts) is exhausted and the loop auto-pauses.

The critical distinction: the main agent model is the worker; the judge model is the evaluator. These are two different models with two different jobs, running independently of each other.

Setting and Monitoring Goals

The basic /goal command accepts plain language:

/goal implement the data validation layer described in REQUIREMENTS.md, all tests must pass

Once set, you can check on the goal without interrupting the agent loop:

• /goal status — displays the current goal text, the turn count, whether the loop is active or paused, and the judge's most recent evaluation
• /goal pause — halts auto-continuation without clearing the goal; useful if you need to inspect progress or inject additional context before the loop continues
• /goal resume — restarts the loop with the turn counter reset to zero (you get a fresh 20-turn budget from the resume point)
• /goal clear — removes the goal entirely; the session continues normally without a judge loop

Goals survive session boundaries. If you close the terminal and open a new Hermes session, the active goal persists via SessionDB.state_meta. The judge loop picks up where it left off.

Using /goal draft

Vague goals produce vague judge evaluations. If your goal is improve the codebase, the judge has no reliable way to determine completion — every turn looks like partial progress. The /goal draft subcommand is designed for this problem: you provide a plain-language description of what you want, and Hermes generates a structured completion contract from it.

/goal draft refactor the auth module to use the new token model

Hermes responds with a structured contract containing five fields. You review it, edit if needed, and then confirm to set the goal with the contract attached. With the contract in place, the judge evaluates against concrete, testable criteria rather than vague intent. Lesson 5 covers completion contracts in full detail — for now, know that /goal draft is the recommended entry point for non-trivial goals.

Background Process Parking

Some tasks involve waiting for long-running processes: a CI pipeline, a build, a deploy, a background job. The judge loop does not need to burn through its turn budget while waiting for an external process. When the agent determines that progress depends on one of these, it can explicitly park the loop in one of three wait states:

• wait_on_session — pauses until a specific session ID produces output (useful when delegating to a subagent)
• wait_on_pid — pauses until a specific process ID exits (useful for background shell processes)
• wait_for_seconds — pauses for a fixed duration before checking again

While parked, the goal remains active but the judge does not run and the turn counter does not advance. When the wait condition resolves, the loop resumes automatically.

The Turn Budget

The default turn budget is 20 continuation attempts after the initial turn. This is configurable in config.yaml. When the budget is exhausted, the loop auto-pauses with a notification — it does not clear the goal. You can inspect progress, decide whether to resume (which resets the budget), or clear the goal and take over manually.

A common mistake is setting a goal that is far too large for 20 turns and wondering why it keeps pausing. Large tasks benefit from decomposition: set a goal for a well-scoped subtask, let it complete, then set the next goal. The /subgoal command, covered in Lesson 5, offers a complementary approach for mid-loop criteria addition.