Autonomous /goal Mode

Most of the time you drive BharatCode turn by turn: you send a prompt, it responds, you read the result and send the next prompt. /goal hands that loop to the agent. You describe the end state you want, and the agent iterates toward it without waiting for you to prompt each step — it keeps going until it judges the goal complete or it hits a built-in limit that stops it from running forever.

/goal is a slash command you run inside the TUI. It has four operations: set the goal, run the loop, stop a run in progress, and clear the goal entirely.

The /goal lifecycle

A goal moves through a simple lifecycle — you set it, run it, and either let it finish, stop it mid-run, or clear it to start over.

• /goal <text> — set the goal. The text after the command becomes the objective for the session. Setting a goal does not start work; it records what you want so you can review or refine it first.
• /goal run — run the loop. The agent begins iterating toward the goal and keeps going on its own until the goal is met or the iteration cap is reached.
• /goal stop — halt a run that is in progress. The loop ends after the current step; the goal itself stays set, so you can adjust course and run again.
• /goal clear — reset. The goal is removed and the session returns to ordinary turn-by-turn use.

Setting a goal

Set a goal by typing /goal followed by a plain description of the end state you want. Treat it like a task you would hand a capable teammate: say what “done” looks like, and name any constraints that matter.

/goal Make `go test ./...` pass. Several tests in the auth package are failing after the session-token refactor. Fix the implementation, not the tests.

Nothing runs yet. The goal is now attached to the session and you can edit it (just run /goal again with new text) or kick it off when you are ready.

Running the loop

/goal run starts the autonomous loop. Each iteration follows the same rhythm:

1. Run — the agent takes the next concrete action toward the goal, using the same built-in tools it uses in normal turns: reading and editing files, running commands with bash, searching the codebase, and so on.
2. Observe — it reads the result of that action: command output, test results, diagnostics, file contents. This is the feedback that tells it whether it is closer to the goal.
3. Continue — it decides whether the goal is now satisfied. If so, the loop ends. If not, it plans the next action and starts another iteration.

The loop ends on its own in one of two ways: the agent judges the goal met, or it reaches the iteration cap. Either way it stops and hands control back to you with a summary of what it did.

/goal run

The iteration cap

Autonomy without a limit is a runaway. To keep a run bounded, every /goal run is governed by an iteration cap — a fixed maximum number of run-observe-continue cycles. When the loop reaches that cap it stops, even if the goal is not yet complete. This is the safety rail that guarantees a goal run terminates rather than looping indefinitely.

Hitting the cap is a normal outcome, not an error. If the agent runs out of iterations before finishing, it reports where it got to so you can decide what to do next: read its progress, refine the goal to be more specific, and run again — the work it already did (edited files, passing tests) stays in place — or take over manually for the last stretch.

Watching progress in the TUI

A goal run is not a black box. While the loop is running, the TUI shows the goal you set, that a run is in progress, and the iterations as they happen — each action the agent takes and the result it observes. You can watch it read files, make edits, and run commands in real time, and see the moment it decides the goal is met or that it has hit the cap.

goal  Make `go test ./...` pass (auth package).running… iteration 3   iter 1  read auth/session_test.go, auth/session.go  iter 2  edit auth/session.go — refresh token TTL          bash: go test ./auth/  →  2 failing  iter 3  edit auth/session.go — clock-skew window          bash: go test ./auth/  →  running press /goal stop to halt · esc to interrupt the current step

Because the run is visible step by step, you are never locked out: if it starts heading the wrong way you can interrupt and /goal stop without waiting for it to exhaust the cap.

Stopping and clearing

/goal stop halts a run that is in progress. The loop ends after the current step rather than tearing work off mid-edit, and the goal stays set — so you can tweak your instruction and /goal run again from where things stand.

/goal stop

/goal clear removes the goal completely and returns the session to ordinary turn-by-turn use. Reach for it when the goal is finished, or when you want to start fresh with a different objective rather than editing the current one.

/goal clear

Goals and approval modes

An autonomous loop works best when it is not stopping to ask permission on every step. How a goal run behaves therefore depends on your current approval mode:

• In read-only mode the agent can investigate freely but cannot make changes, so a goal that requires edits or commands will keep bumping into the permission wall.
• In auto mode it can proceed through the actions covered by that mode without prompting you, which lets the loop actually flow.
• In full mode it can take any action without per-step approval — the most hands-off setting for an unattended run.

Writing good goals

The single biggest factor in how well a goal run goes is the goal you write. The agent can only iterate toward an objective it can understand and recognize when it has reached. A few habits make a large difference.

Define “done” concretely

Give the loop a finish line it can check. A goal that names a verifiable condition — a command that should pass, a behavior that should exist — is one the agent can confirm for itself each iteration. Vague goals never clearly resolve, so they tend to drift until they hit the cap.

/goal Improve the orders API.

/goal Add pagination to the GET /api/orders endpoint: accept ?page and ?page_size query params (page_size capped at 100), return an X-Total-Count header, and cover it with a table test in orders_handler_test.go. Done when go test ./api/... passes and go vet ./... is clean.

Point at a check the agent can run

Whenever you can, tie “done” to something the agent can verify with a tool — go test ./..., go vet ./..., a build command, or your project's test command. A self-checkable condition turns the observe step into real feedback and keeps the loop honest about whether it is actually done.

Scope it so it fits the cap

Because each run is bounded by the iteration cap, a goal that needs a hundred steps is unlikely to finish in one run. Prefer a sharply scoped goal — one bug, one endpoint, one refactor — over a sprawling one. If a large task is naturally several pieces, run them as a sequence of focused goals rather than one open-ended objective.

State constraints and boundaries

Tell the loop what not to do as clearly as what to do: “fix the implementation, not the tests,” “don't touch the public API,” “stay inside the api/ package.” Constraints keep an autonomous agent from taking shortcuts that technically satisfy the goal but aren't what you meant. Durable, project-wide boundaries belong in your AGENTS.md instead, so every goal inherits them automatically.