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

Toggle Goal Mode in the message input area (bottom-right toggle button)
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)
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:

Shell verification — Runs test commands (e.g., pytest, npm test) and checks results
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:

Agent reports a todo item as completed via todo_write
Guard chain detects the new completion and pauses the goal
GoalStatusCard shows which step(s) just finished with a Continue button
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:

Open the active goal’s detail panel
Add a subgoal (e.g., “Also add unit tests for the new module”)
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 <objective>`	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 <amount>`	Add budget to the active goal
`/goal constraint <text>`	Add a hard constraint the agent must not violate
`/goal constraint`	View all current constraints
`/goal constraint clear`	Remove all constraints
`/subgoal add <text>`	Add a dynamic subgoal
`/subgoal list`	List all subgoals
`/subgoal remove <index>`	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:

Open the active goal’s detail panel
Edit the objective text
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:

Select the “Office Full-Chain Delivery” agent from the agent selector
Describe your deliverables (e.g., “Prepare quarterly report: Excel data + PPT presentation + Word summary”)
The agent executes with Goal mode, maintaining data consistency across all documents
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

Create milestones in the sidebar panel (within a Project)
Agent auto-injects — ProjectRoadmapMiddleware injects a compact roadmap context (~100 tokens) into every conversation in that project
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”

Getting Started

Core Concepts

Guides

Self-Hosting

Goal Management

Goal Management

Creating a Goal

From the GUI

From Chat

Goal Lifecycle

Budget Control

Acceptance Criteria

Advanced: Logical Consistency Verification

Constraints

14-Layer Dead-Loop Shield

Judge Feedback Loop

Per-Todo Checkpoint

Priority Queue

Adaptive Convergence & Loop-on-Pause

Convergence Detection

Loop-on-Pause

Resume Safety

Judge Failure Circuit Breaker

Server Restart Recovery

Frontend Status

Global Goal Tracking

Dynamic Subgoals

IM Slash Commands

Objective Hot-Edit

Execution Summary

Deliverable Bundle

Use Case: Full-Chain Office Delivery

API Access

Example Workflow

Project Milestones (Cross-Session Goals)

How It Works

Creating Milestones

Automatic Context Injection

Goals vs Milestones

​Goal Management

​Creating a Goal

​From the GUI

​From Chat

​Goal Lifecycle

​Budget Control

​Acceptance Criteria

​Advanced: Logical Consistency Verification

​Constraints

​14-Layer Dead-Loop Shield

​Judge Feedback Loop

​Per-Todo Checkpoint

​Priority Queue

​Adaptive Convergence & Loop-on-Pause

​Convergence Detection

​Loop-on-Pause

​Resume Safety

​Judge Failure Circuit Breaker

​Server Restart Recovery

​Frontend Status

​Global Goal Tracking

​Dynamic Subgoals

​IM Slash Commands

​Objective Hot-Edit

​Execution Summary

​Deliverable Bundle

​Use Case: Full-Chain Office Delivery

​API Access

​Example Workflow

​Project Milestones (Cross-Session Goals)

​How It Works

​Creating Milestones

​Automatic Context Injection

​Goals vs Milestones

Goal Management

Creating a Goal

From the GUI

From Chat

Goal Lifecycle

Budget Control

Acceptance Criteria

Advanced: Logical Consistency Verification

Constraints

14-Layer Dead-Loop Shield

Judge Feedback Loop

Per-Todo Checkpoint

Priority Queue

Adaptive Convergence & Loop-on-Pause

Convergence Detection

Loop-on-Pause

Resume Safety

Judge Failure Circuit Breaker

Server Restart Recovery

Frontend Status

Global Goal Tracking

Dynamic Subgoals

IM Slash Commands

Objective Hot-Edit

Execution Summary

Deliverable Bundle

Use Case: Full-Chain Office Delivery

API Access

Example Workflow

Project Milestones (Cross-Session Goals)

How It Works

Creating Milestones

Automatic Context Injection

Goals vs Milestones