Loop strategies

A mode decides how one user turn unfolds: how many provider calls, in what order, with what gating. It is a registry entry like any other block, so switching is a command rather than a fork.

Four ship. All of them are built on one shared runReactLoop core with a TurnCheckpoint gate between iterations, so they differ in policy and termination rather than in machinery.

Mode	Package	What it does
default	@moxxy/mode-default	Claude Code-style ReAct: call the provider, run the tools it asked for, feed results back, repeat until it emits a final message.
goal	@moxxy/mode-goal	Autonomous. Tools auto-approved, keeps working until it calls goal_complete, then hands back to your previous mode.
research	@moxxy/mode-deep-research	Plans queries, fans out to subagents in parallel, synthesises a cited report.
collaborative	@moxxy/mode-collaborative	A team of separate agent processes — an architect plus implementers — working one task in parallel.

moxxy plugins use mode goal      # persist it as the default

/mode                            # switch inside a session

default

The one you want for almost everything well-scoped: edit this file, run this query, find that bug. Tool calls pass the permission engine and you answer for them.

goal

Armed for one objective. It auto-approves tools and keeps working unattended, which is why every surface shows a persistent GOAL badge while it is active: you must never lose track of the fact that the agent is driving itself.

Two properties worth knowing:

• It is transient. Goal mode is armed per objective, disarms when the goal concludes, and is never persisted as the boot default. Running /goal once must not make every future session autonomous.
• It reverts. On goal_complete, or on a stall, control returns to whichever mode you were in before, rather than leaving you in an autonomous loop you have to remember to leave.

There are no step guardrails and no iteration cap. A stuck run is nudged rather than halted, on the reasoning that an autonomous run which stops silently at an arbitrary limit is worse than one that says it is struggling.

WARNING

goal auto-approves tool calls. Use it where the blast radius is understood, and consider enabling isolation alongside it.

research

Three phases: plan a set of queries, run subagents over them in parallel, then synthesise the findings into a report with citations. Follow-up queries are parsed out of the synthesis, so one round can feed the next.

Reach for it when the question is "what is the state of X", not "change Y".

collaborative

Entered through /collab rather than picked from /mode, because it is a separate flow rather than a variation on a turn. A coordinator spawns real agent processes: one architect and several peers, each running its own internal role mode.

collab-architect and collab-peer exist in the registry but are marked special — they are what the spawned processes run, not something you select.

Writing your own

import { defineMode, definePlugin } from '@moxxy/sdk';

export const reviewMode = defineMode({
  name: 'review',
  description: 'Read-only: gather context, never write.',
  badge: { label: 'REVIEW', tone: 'attention' },
  async *run(ctx) {
    // Drive the loop and yield events. `runReactLoop` is available when you
    // only want to change policy rather than rebuild the machinery.
  },
});

export default definePlugin({
  name: '@acme/mode-review',
  version: '1.0.0',
  modes: [reviewMode],
});

Useful ModeDef fields:

Field	Effect
badge	A persistent pill on every surface. Use it for any mode that acts without asking.
transient	Armed per objective, never persisted as the default, reverts when it concludes.
special	Not offered in /mode; entered by its own command.

See authoring a plugin for packaging and discovery.

Next

• The swap axis
• Permissions — what a mode's tool calls still pass through
• Subagents — the fan-out that research and collaborative build on