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
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:
director (depth 0, org-plan-reviewer, Sol or Terra, read-only)
└── executor (depth 1, org-plan-executor, Terra, only code writer)
The root director also performs the supervisor and 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 gpt-5.6-sol subagent 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 and continues across L2 boundaries. After every report, the root inspects executor state and immediately resumes the same executor when its L1 is partial and it stopped or became idle. It reviews only DONE + UNREVIEWED L1s and advances accepted work. 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.
Context-mode transports evidence; it does not spawn agents.
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.
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.
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.
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; launchers should add
$CODEX_HOME/bin to PATH.
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="$CODEX_HOME/bin:$PATH"
codex plugin list --marketplace dyne-gestalt-agents --json
codexRun ./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. Runtime versions are isolated by operating system,
CPU architecture, and Node ABI under
${GESTALT_HOME:-$HOME/.gestalt}/runtime/context-mode/. Set CODEX_HOME
explicitly only to test or install an additional isolated Gestalt profile.
Use ./gestalt-setup.sh --force to rebuild and atomically 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.
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 L1 starts unreviewed. After implementation and test gates make it DONE, the director/reviewer 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
available-skill catalog. Do not list $gestalt:context-mode; it
is an implicit baseline for every role. A fresh executor loads that
baseline plus exactly the declared task-specific list before
inspecting or implementing the L1 and stops without edits when either
is unavailable.
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/.