Skip to main content

moai goal Goal Loop

UPDATED 2026-08-08 2 min read EDIT ON GITHUB ↗

moai goal arms/queries/clears a condition-declared agentic goal loop for the current session. The MoAI goal engine keeps the session working across turns until the declared condition is met or the turn ceiling is reached.

This is the programmatic MoAI counterpart of the native /goal (a user-only TUI command), letting the orchestrator register and arm a goal without a human typing the /goal line.

Subcommands

CommandDescription
moai goal arm "<condition>"Register + arm a goal on the active session (moai goal "<condition>" is also an arm alias)
moai goal statusPrint the goal status of the active session
moai goal clearClear the goal of the active session

Common flags

FlagDescription
--session <id>Override the session id (default: resolved via moai session current)
--jsonMachine-readable JSON output
--all(status only) List goals across all sessions, not just the active one

Arm flags

FlagDescription
--max-turns <N>Turn ceiling. 0 = infinite (auto-compact-driven); default 30 when omitted (full backward compat). 0 requires --max-duration or --cost-cap (arm-time fail-closed).
--max-duration <sec>Wall-clock bound (seconds since arm time). The primary run-time bound for an infinite goal.
--cost-cap <value>Cost cap recorded in Ceiling. Enforcement is a documented follow-up (no invocation/token accounting today); an infinite goal is still bounded by --max-duration and the stagnation guard.

State and evaluation

Goal state is stored in .moai/state/goal/<session-id>.json (one file per session). The Stop hook moai hook stop-goal evaluates the goal at the end of every turn.

Condition parsing:

  • An executable shell command (optionally suffixed with exits <N>) becomes a mechanical condition.
  • A claim referencing the conversation transcript becomes a model condition that the orchestrator evaluates.

Examples

bash 
# Keep working until the test suite passes
moai goal arm "go test ./... exits 0"

# Check the current goal status
moai goal status

# Clear the goal
moai goal clear