Goals
Hand Forage a single high-level goal and it works autonomously — across many rounds, self-correcting via real test and lint feedback — until the goal is actually met.
Overview
A goal is the long-horizon counterpart to a normal Code Assistant request. Instead of one bounded edit, you describe an outcome — "a Python app that lets property owners list their yards for overnight stays" — and Forage keeps working toward it across as many rounds as it takes, verifying its own work with real test and lint runs rather than trusting its own opinion.
A goal runs as a persistent background job, not a chat request tied to your browser tab:
- It keeps running if you close the Editor tab or navigate to another view.
- It survives a full Forage server restart — on boot, Forage automatically picks any running goal back up and continues.
- Progress, results, and failures are tracked in the Goals view, not just the chat transcript that started it.
/name command in the Code Assistant chat input. Another built-in skill, /diagnose-fix, runs the same sandbox → edit → syntax-check → test → lint discipline for a single bounded request instead of an open-ended goal.
Starting a goal
Open the Editor view and type /goal followed by a description of what you want built or changed, into the Code Assistant chat input at the bottom of the panel:
/goal Build a REST API for a todo list app with CRUD endpoints, input validation,
and a SQLite database. Include tests for every endpoint.Forage responds immediately with a job ID and starts working in the background — it does not block the chat, and you're free to keep using the Editor for other things while it runs.
A goal stops on its own once the judge reports the work is done, once it's genuinely stuck (see Blocked below), or once its budget is reached — whichever comes first.
How it works
Each round of a goal alternates between two phases, both using the same coding model configured in Settings:
| Phase | What happens |
|---|---|
| Actor | Works in an isolated sandbox — reads and writes real project files, runs commands, and is grounded with relevant knowledge-graph context (related files, symbols, and structure) so it understands the existing codebase instead of guessing. |
| Judge | Reviews the round's changes against the original goal plus the actor's test/lint results, and returns a structured verdict: continue (more work needed), done (goal met), or blocked (stuck and needs attention). |
Every round's changes go through the same sandbox → edit → test → lint discipline used everywhere else in Forage before they count as verified. A round that fails verification never reaches your real project — its sandbox changes are rolled back, and the actor gets another attempt with the concrete failure fed back into its next prompt.
A round that passes verification is merged into your real project immediately, before the judge even reviews it — you don't have to wait for the whole goal to finish to see progress. This also means a goal that later gets blocked or runs out of budget doesn't lose anything: every round that was already verified is already sitting in your real project, not stranded in a sandbox. The sandbox itself keeps living across rounds so the actor can keep building on its own prior work, and is only torn down once the goal is confirmed done (or cancelled).
For a goal with multiple distinct steps, the actor maintains its own working checklist file inside the sandbox, checking off each step as it's completed. On the next round — whether that's a normal continuation or a resume after a Forage server restart — it reads that file first and picks up exactly where it left off instead of re-planning from scratch. The checklist is deleted automatically once the goal is confirmed done; it never ends up in your project.
If the project has a package.json, Forage also runs npm audit once per goal before the actor starts working, and applies npm audit fix for anything it can resolve without a breaking change. Results are recorded in the goal's event timeline.
The Goals view
Click 🎯 Goals in the sidebar to see every goal job for the active workspace. A small status dot on that same sidebar button flashes green when a goal completes and red when one needs attention — so you'll notice even if you're working somewhere else in Forage.
The list shows each goal's title (auto-generated from the description), status, round count, and timestamps. Selecting one opens its detail view:
- A live, ticking round checklist showing progress through the current run
- A full event history timeline — every actor round and judge verdict, in order
- Pause, Resume, and Cancel controls
| Status | Meaning |
|---|---|
| Running | Actively working — can be paused or cancelled. |
| Paused | Stopped by you — resume any time to pick up exactly where it left off. |
| Blocked | The judge couldn't make progress (e.g. a failure it can't self-correct, or the AI model became unreachable), or the goal reached its round/wall-clock budget before being confirmed done — read the judge's feedback in the event timeline, then click Resume. If it stopped because it hit budget (e.g. you left it running overnight past the 24-hour default), Resume automatically grants it a fresh budget from that point rather than just flipping it back to running — no extra setup needed. |
| Completed | The judge confirmed the goal was met. |
| Cancelled | Stopped permanently by you — cannot be resumed. |
Tips
Be specific about the outcome, not the implementation steps — the actor plans its own approach each round. Mentioning a language/framework, key features, and any hard requirements (e.g. "include tests") gives the judge a clear bar to check completion against.
No, but it helps a lot. Configure a testCommand and lintCommand for the workspace (Settings → Workspace) so each round's changes get real, deterministic verification instead of relying only on the judge's read of the diff.
The current round fails cleanly and the goal is marked Blocked rather than left silently stuck or spinning through failed rounds. Reconnect your model server and click Resume to continue.
Yes — start additional goals from the Code Assistant chat the same way; each gets its own row in the Goals list and its own sandbox, so they don't interfere with each other.