> ## Documentation Index > Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt > Use this file to discover all available pages before exploring further. # Goal Management > Define long-running objectives with budget control, acceptance criteria, and autonomous execution. # Goal Management Goals transform Myrm from a chat assistant into an autonomous worker. Define an objective, set constraints, and let the agent work independently across multiple turns. ## Creating a Goal ### From the GUI 1. Toggle **Goal Mode** in the message input area (bottom-right toggle button) 2. The configuration panel expands with sections: * **Budget** — Set any combination of `max_tokens`, `max_usd`, `max_time_seconds`, and `max_turns` * **Acceptance Criteria** — Define shell commands and semantic checks the agent must pass * **Constraints** — Rules the agent must follow during execution * **Protected Paths** — Glob patterns for files the agent must not modify (e.g., `*.env`, `migrations/**`) * **Advanced** — `loop_on_pause`, `convergence_window`, **Pause after each step** (per-todo checkpoint) 3. Type your objective in the message box and send — the agent begins planning and executing ### From Chat Simply describe a complex task in natural language. The agent will detect it requires sustained effort and offer to create a goal. ## Goal Lifecycle ``` QUEUED → ACTIVE → PAUSED / WAIT / BUDGET_LIMITED / NEEDS_HUMAN_REVIEW → COMPLETE / CANCELLED ↑ ↓ PENDING_APPROVAL ←───────── (resume) ``` | State | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `QUEUED` | Waiting for the current active goal to finish | | `ACTIVE` | Agent is actively working toward the objective | | `PENDING_APPROVAL` | Waiting for user to approve the execution plan | | `PAUSED` | Temporarily halted by user or convergence detection | | `WAIT` | Agent is blocked and needs user input or an external event (e.g., background job, user credentials), or the goal is determined unachievable without user guidance | | `BUDGET_LIMITED` | Budget exhausted — requires user to add budget and resume | | `NEEDS_HUMAN_REVIEW` | Verification failed — requires human review and feedback | | `COMPLETE` | Objective met and verified | | `CANCELLED` | Explicitly cancelled by user | ## Budget Control Every goal has 4 budget dimensions: | Dimension | Description | Example | | ------------------ | ----------------------------- | ------------- | | `max_tokens` | Maximum total tokens consumed | 500,000 | | `max_usd` | Maximum dollar spend | \$5.00 | | `max_time_seconds` | Maximum wall-clock time | 3600 (1 hour) | | `max_turns` | Maximum agent turns | 30 | Budget exhaustion pauses the goal with a structured summary of progress. You can **resume** the goal with additional budget at any time. ## Acceptance Criteria Define what "done" looks like: ``` All tests pass, code coverage > 80%, no new linting errors ``` The agent uses **dual-engine verification**: 1. **Shell verification** — Runs test commands (e.g., `pytest`, `npm test`) and checks results 2. **Semantic verification** — LLM-based assessment against your acceptance criteria Both engines must agree for the goal to be marked complete. ### Advanced: Logical Consistency Verification For long document tasks, semantic verification ensures the entire output is logically consistent: ``` Verify all sections are logically coherent: data and claims introduced earlier are addressed in later sections with no contradictions or omissions ``` After the agent finishes writing, the LLM reads the full output and judges logical consistency. If it fails, the agent automatically fixes the issues (up to 3 retries, then pauses for human review). ## Constraints Hard rules the agent must follow: ``` Do not modify the database schema Do not introduce new dependencies Keep all changes backward compatible ``` Constraints are injected into the agent's prompt every turn as a "CONSTRAINTS (MUST NOT VIOLATE)" block, and the semantic judge evaluates compliance during completion verification. ## 14-Layer Dead-Loop Shield At the end of every turn, a 14-layer guard chain determines whether the agent should continue — preventing runaway execution, cost overruns, token waste, goal drift, and sandbox probing: | # | Guard Layer | What it does | | -- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | **User cancellation** | Immediate stop via `CancellationToken` | | 2 | **4D budget limits** | Tokens / USD / wall-clock time / turns — any dimension exhausted triggers pause | | 3 | **Steering token** | Pauses when a new user message is pending, ensuring user input takes priority | | 4 | **Tool completion check** | Detects if tools already reported the goal as done | | 5 | **Sandbox boundary HITL** | 3× consecutive `PERMISSION_DENIED` → graceful PAUSE (not hard crash) + red alert in GoalStatusCard for human review | | 6 | **Goal drift detection** | Every 5 turns, LITE\_MODEL scores trajectory drift 0–10. Score ≥3 → nudge message injected; ≥7 → PAUSE for human review. Fail-open on LLM error | | 7 | **Per-todo checkpoint** | Opt-in mode: auto-PAUSE after each todo completion, waits for user confirmation before continuing. Ideal for high-risk multi-step tasks (deployments, migrations, data pipelines) | | 8 | **Semantic judge (LLM)** | Evaluates whether the objective is met based on conversation context | | 9 | **Constraint compliance** | Checks acceptance criteria and protected-file rules | | 10 | **Zero-progress pause** | No tool calls in a turn → auto-pause to prevent "talks but does nothing" | | 11 | **Judge parse circuit-breaker** | 3 consecutive unparseable judge outputs → pause (saves tokens on bad models) | | 12 | **Verification fuse** | 3 consecutive verification failures → pause (prevents verify-retry loops) | | 13 | **Convergence detection** | K turns without progress → auto-complete (`convergence_window`) | | 14 | **Graceful wrap-up** | On budget exhaustion, injects a wrap-up prompt for a final summary turn — no mid-sentence cutoffs | Additionally, **progressive budget degradation** (WARNING → FINALIZATION) with dynamic remaining USD injection and **4-layer context-window overflow protection** operate at the middleware level to catch edge cases before they reach the guard chain. ### Judge Feedback Loop When the semantic judge determines the goal is **not yet complete**, it provides a specific reason (e.g., "only 3 of 5 charts produced"). This reason is automatically injected into the next turn's prompt so the agent knows exactly what gap to address — eliminating redundant re-analysis and reducing unnecessary turns. ### Per-Todo Checkpoint Enable **"Pause after each step"** in Advanced settings to activate per-todo checkpoint mode. When enabled, the agent automatically pauses after completing each todo item and waits for your confirmation before continuing. **How it works:** 1. Agent reports a todo item as completed via `todo_write` 2. Guard chain detects the new completion and pauses the goal 3. GoalStatusCard shows which step(s) just finished with a **Continue** button 4. You review the results, then click **Continue** to proceed to the next step **Best for:** * **Production deployments** — Confirm each migration step before proceeding * **Data pipelines** — Verify data integrity at each stage * **Complex refactors** — Review code changes step by step * **Learning** — Understand what the agent does at each stage This is opt-in and defaults to off. When disabled, the agent runs uninterrupted as usual. ## Priority Queue When you create multiple goals, they're automatically queued: * The first goal runs immediately * Subsequent goals enter `QUEUED` state * When the active goal finishes, the next queued goal auto-starts * Drag-and-drop reordering in the GUI Set `auto_approve: true` to skip the approval step for queued goals, enabling fully unattended execution of goal chains. ## Adaptive Convergence & Loop-on-Pause Goals can automatically detect when the agent has finished its work and handle continuous execution without human intervention. ### Convergence Detection When the agent goes `convergence_window` consecutive turns without making any tool calls, the goal is automatically marked as converged (completed). This prevents the agent from idling and wasting tokens when it has nothing left to do. | Parameter | Description | Default | | -------------------- | -------------------------------------------- | ---------- | | `convergence_window` | Turns of no progress before auto-convergence | (disabled) | ### Loop-on-Pause When enabled, a goal that pauses due to convergence will automatically restart with a fresh context, up to a configurable maximum number of restarts. This is ideal for long-running monitoring or iterative refinement tasks. | Parameter | Description | Default | | ------------------- | --------------------------------------------- | ------- | | `loop_on_pause` | Automatically restart after convergence pause | `false` | | `max_loop_restarts` | Maximum number of automatic restarts | 0 | ### Resume Safety When you manually resume a paused goal, all runtime counters (`no_progress_streak`, `loop_restarts`, `consecutive_judge_parse_failures`) are automatically reset to zero. This ensures the agent gets a fresh opportunity without triggering immediate re-convergence or false auto-pauses. ### Judge Failure Circuit Breaker If the semantic judge model returns unparseable output (not valid JSON) **3 consecutive times**, the goal is automatically paused to prevent burning tokens on a misconfigured judge. This protects against: * Using a weak model that can't follow the JSON reply contract * Temporary model degradation producing garbage output * Token budget waste from infinite retry loops When the goal pauses due to parse failures, the reason field clearly states what happened and suggests switching to a more capable judge model. Resuming the goal resets the failure counter, so you can try again after fixing the configuration. API/network errors do **not** count toward this threshold — only content-level parse failures trigger the circuit breaker. ### Server Restart Recovery If the server restarts (upgrade, crash, or container reschedule) while a goal is active, the orphaned goal is automatically detected and paused with a clear reason: * On startup, the server scans for goals still marked ACTIVE with no execution engine driving them * Each orphaned goal transitions to **PAUSED** with the reason "Server restarted — resume when ready" * A system notification alerts you that goals were paused * Open the affected chat to see the paused status and one-click Resume when ready This prevents silent token waste (no automatic resume without your consent) while ensuring you never lose track of interrupted work. ### Frontend Status The Goal Status Card displays differentiated states: * **Converged** — Goal completed via convergence detection * **Restarting (#N)** — Goal is restarting via loop-on-pause (showing restart count) ## Global Goal Tracking Monitor all active goals from any page without switching contexts: * **NavBar Badge** — A real-time badge shows the number of active goals. Updates instantly via Server-Sent Events when a goal completes or dequeues. * **Background Tasks Popover** — Click the badge to see all active goals across all sessions: objective, status, tokens consumed, and elapsed time. * **Quick Actions** — Pause, resume, or cancel any goal directly from the popover. A toast confirms the action. * **Navigate** — "Go to session" button jumps directly to the goal's chat for full detail. * **OS Notifications** — When a goal finishes (completes, fails, or gets paused), you receive a system notification even if the browser tab is in the background. This works across **all deployment modes** — local WebUI, Tauri desktop app, and cloud-hosted sandboxes. ## Dynamic Subgoals During execution, you can add new objectives without interrupting the agent: 1. Open the active goal's detail panel 2. Add a subgoal (e.g., "Also add unit tests for the new module") 3. The subgoal is injected into the agent's context with highest priority Subgoals are included in the semantic judge's completion criteria. ## IM Slash Commands Manage goals entirely from any IM channel (Slack, Feishu, Telegram, WhatsApp, etc.): | Command | Description | | ------------------------- | -------------------------------------------------- | | `/goal set ` | Create a new goal | | `/goal status` | View active goal status, constraints, and subgoals | | `/goal pause` | Pause the active goal | | `/goal resume` | Resume a paused goal | | `/goal clear` | Cancel and clear the active goal | | `/goal budget ` | Add budget to the active goal | | `/goal constraint ` | Add a hard constraint the agent must not violate | | `/goal constraint` | View all current constraints | | `/goal constraint clear` | Remove all constraints | | `/subgoal add ` | Add a dynamic subgoal | | `/subgoal list` | List all subgoals | | `/subgoal remove ` | Remove a subgoal by index | | `/subgoal clear` | Clear all subgoals | Constraints added via IM are injected into the agent's prompt as "CONSTRAINTS (MUST NOT VIOLATE)" and enforced by the semantic judge during completion verification — identical behavior to GUI-defined constraints. ## Objective Hot-Edit Change the goal's direction mid-execution: 1. Open the active goal's detail panel 2. Edit the objective text 3. The change is injected as a steering message — the agent adjusts course without losing progress ## Execution Summary After completion, every goal produces a `GoalExecutionSummary` with: * Files modified (with diff links) * Token usage breakdown * Cost breakdown by model * Time elapsed * Turn count * Completion reason This summary is available in the GUI and via API. ## Deliverable Bundle When a goal completes and has produced **2 or more artifacts** (documents, spreadsheets, presentations, etc.), Myrm automatically aggregates them into a **Deliverable Bundle** card: * **Auto-Collection** — All artifacts generated during the goal's session are collected without any manual action * **One-Click ZIP Download** — Download the entire bundle as a single ZIP archive * **Per-File Preview** — Click any individual deliverable to open it in the Artifact Portal with format-aware rendering * **Filename Deduplication** — If multiple artifacts share the same name, unique identifiers are appended automatically ### Use Case: Full-Chain Office Delivery Use the pre-built **"Office Full-Chain Delivery"** agent template to generate complete document suites in one conversation: 1. Select the "Office Full-Chain Delivery" agent from the agent selector 2. Describe your deliverables (e.g., "Prepare quarterly report: Excel data + PPT presentation + Word summary") 3. The agent executes with Goal mode, maintaining data consistency across all documents 4. On completion, the Deliverable Bundle card appears with all files ready for download ### API Access Deliverables are also available via REST API: * `GET /api/goals/{goal_id}/status` — Returns `deliverables` array with artifact IDs and filenames * `POST /api/files/download-bundle` — Downloads multiple artifacts as a ZIP archive ## Example Workflow ``` User: "Migrate the API from Express to Fastify" Goal created: Objective: Migrate Express → Fastify Criteria: All existing tests pass, no API contract changes Constraints: Don't modify the database layer Budget: max_turns=50, max_usd=$10 Agent: Turn 1-3: Plans migration, identifies 12 affected files Turn 4-15: Rewrites route handlers Turn 16-20: Updates middleware Turn 21-25: Fixes failing tests Turn 26: All tests pass, semantic judge confirms completion Goal COMPLETED — 26 turns, $3.47 spent ``` ## Project Milestones (Cross-Session Goals) While Goals operate within a single session, **Project Milestones** span across sessions. They let you define strategic objectives for an entire project, and the agent automatically stays aware of them in every conversation. ### How It Works 1. **Create milestones** in the sidebar panel (within a Project) 2. **Agent auto-injects** — `ProjectRoadmapMiddleware` injects a compact roadmap context (\~100 tokens) into every conversation in that project 3. **Track progress** — Milestones link to Kanban boards for automatic progress calculation ### Creating Milestones In the sidebar, navigate to your project and find the **Milestones** section: * Click the `+` button to add a new milestone * Each milestone has a **title**, optional **description**, and **acceptance criteria** * Mark milestones as completed when objectives are met ### Automatic Context Injection When you chat within a project that has milestones, the agent receives context like: ``` Project: Q3 Product Upgrade — Complete core feature iteration Current Focus: Finish milestone system and ship to production Active Milestones: - [active] MVP Release (criteria: All core APIs pass integration tests) - [active] Beta Launch Completed: Technical Research ``` This happens automatically — no commands needed. ### Goals vs Milestones | Aspect | Goal | Milestone | | --------- | ------------------------------- | -------------------------------------- | | Scope | Single session | Cross-session (project-level) | | Lifecycle | QUEUED → ACTIVE → COMPLETE | active → completed → archived | | Execution | Agent executes autonomously | Strategic direction, manual completion | | Budget | Yes (tokens, cost, turns, time) | No budget — purely organizational | | Use case | "Migrate API to Fastify" | "Q3: Ship v2.0 to production" |