Goal

Download

Focus Mode

Font Size

Last updated: 2026-09-30 18:41:47

AI-Translated

Overview
The /goal command sets a completion condition that CodeBuddy continuously works toward without requiring step-by-step prompting from you. At the end of each turn, a small-fast model evaluator determines whether the condition is met. If not, CodeBuddy automatically starts the next turn instead of returning control to you. Once the condition is satisfied, the goal is automatically cleared.
Version Requirements:
The /goal command requires that @tencent-ai/codebuddy-code already includes the goal feature (the GoalService module of agent-cli).
Use /goal to track substantive work that has a verifiable end state:
Migrate a module to the new API until all call sites compile and pass tests.
Implement a design document until all acceptance criteria are met.
Split a large file into focused modules until each module stays within its size budget.
Process the list of issues with a specific label until the queue is empty.
Comparison with Other Autonomous Workflows
All three methods below allow a conversation to continue running across multiple prompts. Choose based on "who triggers the next turn":
Method
When the Next Round Starts
When to Stop
/goal
Starts immediately after the previous round ends.
The evaluator confirms that the condition is met.
/loop
Triggered by time interval
You stop it manually or the model determines that the work is complete.
Stop hook
Starts immediately after the previous round ends.
Your script or prompt determines it autonomously.
Both /goal and Stop hook are triggered after each turn. /goal is a session-level shortcut: you enter a condition, and it takes effect only within the current session. Stop hook is written in settings and applies to all sessions within its scope, and it can run either deterministic scripts or model-evaluated prompts.
Note:
All the methods above keep the "current session" running continuously. If you need scheduled work that is independent of the current session (such as running tests at night or triaging issues in the morning), see Scheduled Tasks.
Using /goal
Each session can have only one active goal at a time. The same command plays three roles depending on its parameters: "set / view / clear."
Setting a Goal
Simply enter the condition you want to meet after /goal. If an active goal already exists, the new one replaces the old one (the old goal's hook is automatically unregistered).
/goal all tests in test/auth pass and the lint step is clean
After setup is complete, CodeBuddy immediately starts a turn and passes the "condition itself" as an instruction to the main agent, so you do not need to send an additional prompt. At the same time, a ⊚ /goal active (Xs) indicator appears at the bottom right of the input box, refreshing the elapsed time every second so you always know that goal mode is active.
After each turn, the evaluator returns a brief reason explaining "why the condition is not yet/has been met." This reason is injected into the conversation history as an internal message with isMeta=true, allowing the model to see the evaluator's perspective in the next turn and precisely address what is still missing. This is key to the model's ability to "know which steps remain."
Session-level behavior: the goal keeps running until the condition is met or you run /goal clear. Run /goal (without parameters) to view statistics such as turns / tokens.
Writing an Effective condition
The evaluator only judges conditions based on what CodeBuddy has already expressed in the conversation. It does not run commands or read files on its own. Therefore, conditions should be written in a form that "CodeBuddy's own output can prove." "All tests in test/auth pass" works because CodeBuddy runs the tests itself, and the results appear in the transcript for the evaluator to read.
A condition that can robustly support multi-turn work typically includes:
A measurable terminal state: test results, build exit codes, file counts, empty queues...
A provable method: for example, \\`npm test\\` exits 0 or \\`git status\\` is clean
Inviolable constraints: things that must not be changed along the way, such as "no other test file is modified"
The maximum length of a condition is 4000 characters.
To set a fallback limit for a goal, you can add a turn/time clause to the condition, such as or stop after 20 turns. CodeBuddy checks the current progress against this clause in each turn, and the evaluator can also read it from the conversation.
Viewing the Status
Run /goal without parameters:
/goal
In the TUI, the goal recap panel opens. In Web UI / ACP clients, the same panel opens via ACP broadcast. In headless / SDK environments without a UI, it degrades to plain text output.
The panel includes:
Conditions
Elapsed time
Number of evaluated turns
token consumption (incremental during the goal)
The reason most recently provided by the evaluator
If there is no active goal but a goal was previously achieved in this session, the panel shows the condition, duration, number of turns, and number of tokens from that time.
Clearing the Goal in Advance
/goal clear
The following tokens are all treated as synonyms for clear: stop, off, reset, none, and cancel. They are recognized as a clear command only when a single token matches exactly. /goal stop using deprecated API is still processed as "set a new condition" and is not swallowed.
Running /clear to restart the session also removes the active goal (hook unregistration + meta cleanup).
Carrying a goal When Resuming a Session
When a session is resumed with --resume / --continue, any unfinished goal is restored (both condition and scope are recovered).
Current limitations: When a goal is resumed, the original goal's createdAt, turnCount, and token starting points are retained, and the timers and counters are not reset. If you want to restart the timing, run /goal clear first and then run /goal <condition> again. Goals that have already been achieved or cleared are not restored (the meta has been deleted).
Running in Non-Interactive Mode
/goal is available in both non-interactive mode (headless) and Remote Control. Setting a goal in -p mode makes the evaluator run in a loop until completion:
codebuddy -p "/goal CHANGELOG.md has an entry for every PR merged this week"
To terminate early when the condition is met, press Ctrl+C.
How the Evaluation Mechanism Works
/goal is a wrapper around the session-level prompt-based Stop hook. Each time the CodeBuddy main agent completes a turn, the current condition + current conversation are sent together to a configured small-model evaluator. The evaluator returns a tri-state result of "yes / no / unreachable" along with a brief reason:
Yes (ok: true): Clear the goal, record an "achieved" event, and the UI displays the ✔ Goal achieved status bar.
No (ok: false): Inject the reason into the history as a user message with isMeta=true (so the main model can see what to supplement next), and let CodeBuddy continue working. Also write a goal-progress UI status bar: ◯ Goal not yet met... continuing.
Unreachable (ok: false, impossible: true): Used by the evaluator to determine that "this goal is impossible to complete in the current session" (the conditions are contradictory, required capabilities/resources are unavailable, or the model has exhausted all reasonable attempts). Clear the goal immediately, and the UI displays ✕ Goal could not be achieved to avoid getting stuck in a loop.
The evaluator uses the small model bound to the lite slot in the product configuration (mapped to gpt-5.1-codex-mini / gemini-2.5-flash / DeepSeek deepseek-v4-flash on different model providers). Evaluation only reads the existing transcript and does not call tools, so using a small model is both fast and cost-effective.
Billing:
The tokens consumed by the evaluator are billed to the small model account and are usually negligible compared to the main turn.
Evaluation Window Constraints
To avoid the situation where a goal is achieved immediately after being set, because a previously achieved goal in the same session leaves a success response in the transcript, we inject the current goal's createdAt (ISO 8601) into the evaluator's user prompt and explicitly instruct:
Evaluate ONLY the conversation that happened AFTER this timestamp. Earlier messages MUST NOT be used as evidence.
If no qualifying activity has occurred since the goal was set, the evaluator must return {"ok": false, "reason": "Goal was just set; no work has been done yet against the new condition."}.
Sanitizing history for the evaluator
Before feeding the history to the evaluator, we filter out the following extended item types (which are project-defined and not recognized by the SDK):
goal-result / goal-progress (the goal's own UI status items)
summary / topic / ai-title / custom-title
file-history-snapshot
These items are neither user input nor assistant responses, have no evaluation value for the evaluator, and trigger the SDK's Unknown item type warning.
Implementation Notes and Known Limitations
The following table summarizes the key behaviors and known limitations of the current implementation for easier troubleshooting:
Action
Status
Remarks
Set / Replace / kick-off
✔
Starts a round immediately after it is set. If an active goal already exists, it is automatically replaced.
/goal clear alias
✔
Supports five single-token synonyms: stop / off / reset / none / cancel.
/clear synchronously clears the active goal.
✔
When restarting a session, also unregister the goal hook and clear the meta.
condition limit
✔
4000 characters
Feedback of reason into history.
✔
Injection format: Stop hook feedback: [<condition>]: <reason>
Three-state semantics (ok / not-yet / impossible)
✔
When unreachable, clear the goal immediately to avoid invalid loops.
evaluator uses the small model.
✔
Use the model bound to the lite slot (mapped separately by provider).
/goal without parameters → status view
✔
TUI / Web UI panel + headless text fallback
Continuous running indicator ⊚ /goal active (Xs)
✔
Constantly displays the running duration at the lower right of the input box, refreshing at 1 Hz.
Reset turn / timer / token when --resume is used.
✖ 
Currently keeps the original createdAt / turnCount. To restart timing, run /goal clear first.
See Also
/loop creates a recurring task: triggers repeatedly at a time interval, rather than waiting until a condition is met.
Hook Getting Started / Hook Reference: Understand the underlying mechanism of prompt-based Stop hooks. When you need more complex evaluation logic, you can write one yourself.
Non-interactive (headless) mode: Run /goal with -p in CI / scripts.
Remote Control: Trigger a goal in the Web UI / WeChat channel.
Slash Commands Overview: An index of all built-in slash commands.
﻿

Help and Support

Was this page helpful?

You can also Contact sales or Submit a Ticket for help.

Help us improve! Rate your documentation experience in 5 mins.

Feedback

tencent cloud

Tencent WorkBuddy Enterprise

Goal

Overview

Comparison with Other Autonomous Workflows

Using `/goal`

Setting a Goal

Writing an Effective condition

Viewing the Status

Clearing the Goal in Advance

Carrying a goal When Resuming a Session

Running in Non-Interactive Mode

How the Evaluation Mechanism Works

Evaluation Window Constraints

Sanitizing history for the evaluator

Implementation Notes and Known Limitations

See Also

Help and Support

Method	When the Next Round Starts	When to Stop
`/goal`	Starts immediately after the previous round ends.	The evaluator confirms that the condition is met.
`/loop`	Triggered by time interval	You stop it manually or the model determines that the work is complete.
Stop hook	Starts immediately after the previous round ends.	Your script or prompt determines it autonomously.

Action	Status	Remarks
Set / Replace / kick-off	✔	Starts a round immediately after it is set. If an active goal already exists, it is automatically replaced.
`/goal clear` alias	✔	Supports five single-token synonyms: stop / off / reset / none / cancel.
`/clear` synchronously clears the active goal.	✔	When restarting a session, also unregister the goal hook and clear the meta.
condition limit	✔	4000 characters
Feedback of reason into history.	✔	Injection format: `Stop hook feedback: [<condition>]: <reason>`
Three-state semantics (ok / not-yet / impossible)	✔	When unreachable, clear the goal immediately to avoid invalid loops.
evaluator uses the small model.	✔	Use the model bound to the `lite` slot (mapped separately by provider).
`/goal` without parameters → status view	✔	TUI / Web UI panel + headless text fallback
Continuous running indicator `⊚ /goal active (Xs)`	✔	Constantly displays the running duration at the lower right of the input box, refreshing at 1 Hz.
Reset turn / timer / token when `--resume` is used.	✖	Currently keeps the original createdAt / turnCount. To restart timing, run `/goal clear` first.