Gestalt Agents Orchestrator Methodology

_{We invite you to stop assembling the pieces and start perceiving the whole.}

This methodology is based on Emacs org-mode and concepts by Ludwig Wittgenstein

📖 More info on dyne.org/gestalt

Org-mode plan and development

This method optimizes on token usage and quality of code by leveraging org-mode as planning format and context-mode as token saving memory system. It adopts a light multi-agent setup to keep the workflow and avoid stall. The prepared agents default to:

root (depth 0, org-plan-reviewer, Sol or Terra, read-only)
└── executor (depth 1, org-plan-executor, Terra, only code writer)

The root also performs the director, supervisor, and routine reviewer duties. It directly launches one fresh executor for each L1, supervises its evidence gates, and reviews its uncommitted result. Rejected work returns to the same executor; accepted work is committed once before that executor closes. This keeps the root active with only one subagent below it. Evidence flows upward as concise summaries; raw test and inspection logs stay outside conversational context. The root gives brief user-facing updates such as L1 2/5 — Validate release metadata: in review.

After all L1s are REVIEWED and their executors have closed, the root launches one fresh subagent inheriting the root model and reasoning effort for a terminal whole-branch review. That agent fixes any P0/P1 findings as the sole writer before final acceptance.

Supervision is completion-driven. An executor owns its entire L1 but returns a concise evidence report whenever an L2 reaches DONE. In checkpoint-capable Mobile sessions, the root validates and publishes that L2 as a compact final answer; the next automatic turn resumes the same executor. Each answer lists the new behavior, changed files, focused verification, pending L1 commit, and next action. Accepted L1 answers roll up their L2s and name the resulting commit. Without L2 checkpoint support, the root uses the legacy same-turn continuation. Neither role yields merely for progress, time, or token usage. The root stops only when every plan L1 is REVIEWED and final gates pass, or when a genuine external blocker requires user input or changed external state.

Every new or resumed relay session signals supervision before it recovers milestone or executor state, including when the plan is already WIP. Mobile uses a fresh status directory for a resumed relay session; repeated signaling inside one directory retains the existing document so a later root turn cannot override explicit manual Off. Starting supervision has an observable postcondition: the retained plan either has healthy Mobile control evidence, or the root emits one bounded compatibility warning and continues in the same turn. On an incomplete plan it must choose a real disposition—work, same-executor follow-up, review/correction, an accepted checkpoint followed immediately by its boundary final, an accepted one-shot wait lease, structured attention, or explicit manual Off. A status message alone never ends supervision. Executors and their displayed roster entries use exact names such as l2 (or canonical l2 for a replacement physical slot such as l2_g2); titles and generated nicknames are never appended.

A wait lease is a valid yield disposition only after Mobile returns accepted:true. If the tool is unavailable or returns accepted:false, the root keeps supervising in the same turn so an idle executor cannot be stranded without an automatic continuation.

Context-mode transports evidence; it does not spawn agents.

Optional mobile attention protocol

Supervised roles may consume the mobile-managed, schema-v1 gestalt_org_plan_attention dynamic tool for a genuine external blocker. It is optional: the Org Plan workflow remains fully usable without mobile or the tool. The versioned reason vocabulary and fail-closed compatibility rule live in the attention protocol.

🎮 Quick setup

Requirements

Gestalt setup requires Node.js 22.5 or newer and npm. It uses Bun for dependency installation when a working Bun executable is available. Building context-mode also requires network access, python3, make, and a C/C++ compiler.

Fresh Codex install

Gestalt uses an isolated Codex home at ~/.codex-gestalt. Add the marketplace to that profile and locate its checkout:

export CODEX_HOME="$HOME/.codex-gestalt" && mkdir -p "$CODEX_HOME"
codex plugin marketplace add dyne/gestalt-agents
"$CODEX_HOME/.tmp/marketplaces/dyne-gestalt-agents/gestalt-setup.sh"

You may change 'add' to 'upgrade' in the middle of the second line.

If you use codex-profile then add alias gestalt='codex-profile cli gestalt' else invoke CODEX_HOME="$HOME/.codex-gestalt" codex.

Developer's installl

You may also run gestalt-setup.sh from a development checkout. If Codex has a different marketplace snapshot configured, the script continues from that snapshot automatically and preserves its arguments.

The script defaults CODEX_HOME to ~/.codex-gestalt, installs both plugins, and prepares context-mode under ~/.gestalt. Setup generates org-plan-reviewer and org-plan-executor, then removes the obsolete ~/.codex-gestalt/agents/org-plan-supervisor.toml. It also reconciles the context-mode MCP and lifecycle-hook entries in config.toml and hooks.json. The reconciler preserves unrelated settings and is byte-idempotent. It disables the plugin-manifest contribution while retaining the installed package, because current Codex does not pass its session workspace to plugin MCP children; the native launcher supplies the Codex process workspace and avoids duplicate MCP and hook registrations. Current Codex already defaults the V1 agent depth to one and enables stable lifecycle hooks. The former features.plugin_hooks flag has been removed, so Gestalt only enables the stable features.hooks gate required by its generated hook configuration. On an older installation, remove an agents.max_depth = 2 override.

Setup also verifies the app-server's real skills/list response contains every enabled $gestalt:<skill-name> distributed by the installed release. Setup fails rather than reporting success when the session catalog disagrees with the plugin. The bundled Org Plan helper is copied to the stable $CODEX_HOME/bin/org-plan path on every setup or upgrade, with its Node implementation installed as a matching private bundle under $CODEX_HOME/lib/gestalt-org-plan; launchers should add $CODEX_HOME/bin to PATH.

The bundled gestalt-org-plan MCP server explicitly approves its local plan and lifecycle tools, matching the trusted context-mode server. Codex's approval_policy = "never" forbids approval prompts; it does not approve a write-capable MCP tool automatically. Without the server's approval setting, read-only plan queries work while startup signals and lifecycle updates fail. Explicit user per-tool approval overrides still take precedence. The server also forwards Mobile's session-specific status directory (or its legacy status file), so typed lifecycle calls publish to the same relay session as CLI helper calls.

Setup now checks the effective MCP permission configuration before reporting success. Launchers can repeat the read-only check outside the agent sandbox with the intended session policy; see the bundled Org-plan skill's startup diagnostics. The diagnostic starts no turn and changes no permission or plan state. Automated approval tests use a local Responses fixture to exercise Codex's model-triggered MCP gate without credentials or paid model calls, including explicit per-tool overrides and status publication. Typed supervision-start signals also retain the existing same-session startup marker, matching the CLI and preserving a deliberate Autopilot Off.

Pass --extra-skills to opt into the marketplace's curated third-party skill set. This uses npx skills in project scope and keeps its canonical skill payloads and lock metadata under ${GESTALT_HOME:-$HOME/.gestalt}, then links each non-conflicting entry into CODEX_HOME/skills. The option requires network access and is intentionally disabled during normal setup. Use --extra-skills-only to install or refresh only that curated set without repeating runtime preparation or plugin installation.

Start or restart Codex with that home, verify the effective installation, and run ctx-doctor in a new session:

export CODEX_HOME="$HOME/.codex-gestalt"
export PATH="$HOME/.gestalt/bin:$CODEX_HOME/bin:$PATH"
codex plugin list --marketplace dyne-gestalt-agents --json
codex

Runtime preparation details

Run ./gestalt-setup.sh again after a marketplace upgrade. Use ./gestalt-setup.sh --prepare-only to install the external runtime without installing plugins or changing the isolated Codex home, and --force to replace an invalid prepared runtime. A single runtime lives under ${GESTALT_HOME:-$HOME/.gestalt}/runtime/context-mode/. Its manifest checks the package version, operating system, CPU architecture, and Node ABI. Setup builds and verifies a temporary replacement before switching, then removes the previous copy, including the old version-directory layout. A failed build keeps the previous runtime. Restart sessions after updating.

Setup also installs context-mode and org-plan in ${GESTALT_HOME:-$HOME/.gestalt}/bin/. Add that directory to your shell's PATH, or invoke the commands by their full paths. These are small managed launchers; the Org-plan launcher preserves the helper's relative module lookup. Future commands can use the same explicit registry in scripts/install-managed-commands.mjs. User-owned files in that directory are never overwritten.

Set CODEX_HOME explicitly only to test or install an additional isolated Gestalt profile. Use ./gestalt-setup.sh --force to rebuild and replace that runtime.

Marketplace installation does not execute setup automatically. On an existing installation, upgrade the marketplace and rerun its setup script:

export CODEX_HOME="$HOME/.codex-gestalt"
codex plugin marketplace upgrade dyne-gestalt-agents
"$CODEX_HOME/.tmp/marketplaces/dyne-gestalt-agents/gestalt-setup.sh"

Do not add duplicate MCP or hook configuration; rerun setup to repair old or partial registrations. If startup still fails after forced preparation, confirm that another context-mode marketplace variant is not also enabled. CONTEXT_MODE_NOT_PREPARED identifies a missing, incompatible, or damaged external runtime; rerun setup with --force and restart Codex. MCP and hook startup are side-effect free: only setup installs, builds, or repairs the external runtime.

🧪 Testing (only for developers of this repo)

Run the same complete validation used by CI before publishing changes:

bash tests/ci.sh

The validation covers repository and Gestalt contracts, plugin and skill ingestion, context-mode integrity and Codex-focused tests, skill discovery, nested MCP startup, shell linting, release versioning, and release-workflow contracts. It also installs both plugins through the current Codex CLI in an isolated home. GitHub runs it on Linux and macOS with Node.js 22.12.0. The release job starts only after both operating-system jobs pass.

Releases use conventional commits with ietf-tools/semver-action@v1. The stable release line starts at v2.0.0; historical v0.x tags are excluded from future version calculations. Each release assigns the same version to the Gestalt plugin and the adapted context-mode plugin/runtime. feat advances the minor version, supported fix-oriented commit types advance the patch version, and breaking changes advance the major version.

Each GitHub release includes one gestalt-agents-vX.Y.Z.zip. The bundle contains the repository marketplace metadata, the Gestalt plugin and its full skill set, the context-mode plugin and runtime sources, gestalt-setup.sh, and the user documentation. This keeps the complete installation together while retaining per-skill activation and Org Plan's explicit milestone skill loading. SHA256SUMS covers the release archive.

📃 Plan

Each L1 starts unreviewed. After implementation and test gates make it DONE, the root audits only requested DONE + UNREVIEWED milestones. Accepted L1s remain reviewed as the plan grows, so later refinements review only new or materially changed L1s. Final acceptance still requires a current full-suite pass and clean intended scope.

Each L1 also declares a non-empty :SKILLS: property containing exact $skill references selected from the planner's complete optional-skill catalog. Never list a $gestalt:* skill: Gestalt workflow skills are always loaded for every role; conditional capabilities such as gestalt:xerj require verified runtime tools and are not milestone dependencies. A fresh executor loads exactly the declared optional task-specific list before inspecting or implementing the L1 and stops without edits when a required optional skill is unavailable.

💼 License

Copyright (C) 2025-2026 Dyne.org foundation

Designed and written by Denis "Jaromil" Roio.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Conditional local retrieval

The canonical gestalt:xerj skill is packaged with Gestalt. Managed runtime launchers expose it only alongside verified xerj MCP tools, and force it into the effective session skills when ready. Installation and package discovery do not establish runtime readiness. A missing service or unindexed repository falls back to rg and direct file reads. Indexing requires an explicit request for the identified repository; startup never autoindexes a workspace. Existing Gestalt workflow skills retain their fixed inclusion.

The conditional gestalt:serena skill uses the verified managed connection for symbol navigation, references, diagnostics and structured edits in the active workspace. CLI and Mobile select it only when its MCP connection is verified, hooks are enabled and the session profile permits it. The connection always uses --context codex --mode editing; native filesystem policy, per-tool approvals and collaboration plan-mode instructions still govern edits. A connected catalog does not prove language readiness: require a successful symbol overview and fall back to native tools for unsupported languages or startup failures. Serena and XERJ readiness are independent; use XERJ for broad cross-project references and context-mode to analyze large outputs. Startup does not install or index Serena implicitly.