Track a goal across project sessions
Set, pause, and complete a persistent objective scoped to your Git repository.
A goal tells the agent what you are trying to achieve beyond the current conversation. Unlike memory, which records knowledge, a goal is an objective included in new sessions while it is active.
Set your first goal
Start afk in the project
Run afk from the repository whose objective you want to track. Repository identity determines which goal is read and changed.
Set and inspect the objective
/goal Ship the authentication refactor before the sprint ends
/goal status/goal set is equivalent to /goal followed by the objective. Text is limited to 500 characters. Setting a goal replaces the existing goal for this project, including a paused or completed one.
Begin a new session
Goal changes are saved immediately, but the active-goal prompt is built at session construction. Start a new session for the agent to receive the updated objective.
Project scope
Inside Git, goals are scoped to the repository's common root. Subdirectories and linked worktrees of the same repository share one goal. A separate clone has a different path-derived key, even if it has the same remote URL.
Outside Git, or when Git cannot resolve the repository, AFK falls back to the legacy global current goal. It does not create an independent goal for every arbitrary directory.
Changing a goal from a linked worktree changes the objective used by future sessions in the main checkout and its other linked worktrees. Already running sessions retain the goal prompt they started with.
Only one goal is stored per scope. Use a goal for a sustained refactor, a research question, or an ongoing maintenance objective. It does not replace individual task plans, and it does not schedule work by itself.
Manage the lifecycle
| Command | Result |
|---|---|
/goal or /goal status | Show the text, status, creation time, and update time |
/goal set <text> | Replace the scoped goal with an active objective |
/goal pause | Change an active goal to paused |
/goal resume | Change a paused goal to active |
/goal done or /goal complete | Complete an active goal |
/goal clear | Delete the scoped goal |
Paused and completed goals are not injected into new sessions. Resume a paused goal before completing it. A completed goal cannot be resumed; set a new goal if work continues. Commands that do not fit the current status leave it unchanged and report that no transition occurred.
Clearing has no undo. Completing keeps the objective and its timestamps available for inspection.
Example: interrupt and resume a refactor
/goal set Ship the authentication refactor with no public API changes
/goal pauseStart a new session for the unrelated urgent task. When ready to return:
/goal resumeBegin a new session for the refactor, then mark it complete when the objective is satisfied:
/goal doneWhat the agent receives
An active objective is included as an active-goal block after memory context and before the environment section. It contains the objective and its creation timestamp. XML-like tags are stripped from the text before injection.
The prompt snapshot is not refreshed just because you pause, complete, or replace a goal from another session. Tell a running agent directly if its current objective has changed.
Persistence across surfaces
Goals are JSON documents in ~/.afk/state/kv/kv.db, under the goals namespace. Git repository keys have the form proj.<slug>-<hash>; the non-Git fallback key is current. Stored fields include text, status, createdAt, updatedAt, and optional createdBy session attribution.
The REPL, afk chat, Telegram, and daemon sessions can receive the same goal when they use the same state directory and repository scope. Merely sharing a state directory is not enough if the surfaces run in different repositories. Manage goals with /goal in the REPL.
AFK_STATE_DIR relocates the database to its kv/kv.db child. See structured state for the underlying store.