GitHub - tienne/gestalt: From ambiguity to AI execution ⚡

Gestalt — AI Development Harness
When requirements are vague, AI becomes the interviewer.

📊 Benchmark: Resolution 0.8 specs reduce rework rate by 27% vs. 0.5 specs — verified by LLM-as-judge on 20-item golden set

The hardest part of building software isn't writing code — it's knowing what to build. Gestalt is an MCP server that runs inside Claude Code and acts as a structured interviewer: it applies five Gestalt psychology principles to raise requirement resolution from vague intent to a measurable score of ≥ 0.8, then crystallizes that into a validated Spec that drives the rest of your pipeline. No API key required.

/interview "user authentication system"   # AI interviews you until resolution ≥ 0.8
/spec                                      # crystallize into a validated Spec
/execute                                   # plan → execute → evaluate → evolve

Requires Node.js >= 20.0.0. Use nvm install 22 && nvm use 22 if needed.

Built with Gestalt, for Gestalt

This repository is developed using the gestalt-develop skill — the same pipeline you get when you install Gestalt. Every significant feature in v0.26.0 was implemented through the Interview → Spec → Execute → Evolve loop:

Memory → Interview feedback loop (prior specs auto-injected into new sessions)
execute-passthrough.ts 1,296-line God File decomposed into 8 focused modules
Code review context-collector migrated from regex to blastRadius() graph analysis
ESLint flat config + CI 3-gate pipeline (typecheck → lint → format:check)

This self-referential proof is the strongest argument for Gestalt: an AI harness that improves itself through its own pipeline. When Gestalt interviews you about a Gestalt feature, it applies the same five principles to its own architecture.

Quick Start

Install the plugin once, then use it in any Claude Code session.

From a terminal (outside a session):

claude plugin install gestalt@gestalt

Inside a Claude Code session:

/plugin marketplace add tienne/gestalt
/plugin install gestalt@gestalt

Then run the pipeline:

/interview "user authentication system"
/spec
/execute

Full MCP Reference — all tools, parameters, and examples

Installation

Option 1: Claude Code Plugin (Recommended)

Bundles the MCP server, slash-command skills, Gestalt agents, and project context — pre-configured in a single install.

From a terminal:

claude plugin install gestalt@gestalt

Inside a Claude Code session:

/plugin marketplace add tienne/gestalt
/plugin install gestalt@gestalt

What you get:

Item	Details
MCP Tools	`ges_interview`, `ges_generate_spec`, `ges_execute`, `ges_create_agent`, `ges_agent`, `ges_status`, `ges_code_graph`, `ges_graph_visualize`, `ges_benchmark`, `ges_generate_kb`, `ges_search`, `ges_sync`
Slash Commands	19 workflow skills — `/interview`, `/spec`, `/execute`, `/review`, `/pr`, `/brief`, `/jira-create`, `/slack-send`, and more
Agents	21 role agents + 4 review agents
CLAUDE.md	Project context and MCP usage guide auto-injected

Option 2: Claude Code Desktop

Install once, then point the config at the installed binary:

npm install -g @tienne/gestalt

{
  "mcpServers": {
    "gestalt": {
      "command": "gestalt",
      "args": ["serve"]
    }
  }
}

MCP tools are available immediately after restart. Slash commands require the plugin or manual skills setup.

npx -y @tienne/gestalt works too, but read Startup timeouts first — the desktop app is the setup most likely to hit them.

Option 3: Claude Code CLI

npm install -g @tienne/gestalt
claude mcp add gestalt -- gestalt serve

Or add directly to ~/.claude/settings.json:

{
  "mcpServers": {
    "gestalt": {
      "command": "gestalt",
      "args": ["serve"]
    }
  }
}

Startup timeouts

If the server connects sometimes and reports Connection closed other times, the cause is almost always npx, not Gestalt. Three things are worth knowing.

npx reaches the registry on every start. Pinning an exact version does not change that. Measured against npm: 1.9s on a warm cache, 20s on a cold one, and a 70s hang before failing when the registry is unreachable. Claude Code gives a stdio server 30s to answer initialize, so the cold and offline cases both surface as a closed connection. Installing the package globally and calling gestalt serve skips all of it.

GUI-launched sessions have a different PATH. Anything started outside a terminal — the desktop app, a launcher, launchd — inherits a PATH with no version manager on it, so npx is not found and the server dies instantly. Give command an absolute path, or set env.PATH on the server entry.

startup_timeout_sec does nothing in Claude Code. That key belongs to Codex. Claude Code reads the MCP_TIMEOUT environment variable (milliseconds) instead, so it goes in settings.json, where it lands in the Claude Code process:

{
  "env": { "MCP_TIMEOUT": "180000" }
}

The plugin install (Option 1) already handles the first two through scripts/mcp-serve.sh: it finds Node under nvm, fnm, Volta, or Homebrew, prefers a globally installed gestalt, and otherwise resolves the pinned version from the npm cache, falling back to the network only when the cache misses.

Option 4: OpenAI Codex Plugin

Bundles the MCP server and all 19 workflow skills, the same way the Claude Code plugin does.

codex plugin marketplace add tienne/gestalt
codex plugin add gestalt@gestalt

What you get:

Item	Details
MCP Tools	All 12 `ges_*` tools
Skills	19 workflow skills, including `gestalt:review` and `gestalt:pr`
Agents	21 role agents + 4 review agents (bundled for skills to read)

Skills load on the next Codex session. Slash commands and the Claude Code Task panel are still Claude Code only — in Codex you invoke a skill by describing the task, and Codex reads the matching SKILL.md.

Option 5: OpenAI Codex CLI (MCP only)

If you want the MCP tools without the bundled skills:

codex mcp add gestalt -- npx -y @tienne/gestalt serve

Then add "client": "codex" to your project's gestalt.json so the active session context is written to AGENTS.md (which Codex reads automatically):

{
  "$schema": "./node_modules/@tienne/gestalt/schemas/gestalt.schema.json",
  "client": "codex"
}

Or set GESTALT_CLIENT=codex as an environment variable.

Codex uses host passthrough mode: Gestalt returns prompts and structured context, and Codex performs the reasoning, file edits, and command execution. When client is "codex", this remains true even if ANTHROPIC_API_KEY exists in your shell.

All 12 MCP tools (ges_interview, ges_generate_spec, ges_execute, etc.) are available immediately. This option ships no skills — the pipeline runs entirely through MCP tool calls. Use Option 4 if you want gestalt:review and the other workflow skills. During execution, active context is written to a managed section in AGENTS.md; continue following the current MCP response (executeContext, taskContext, etc.) in the active Codex turn.

Option 6: Grok Build Plugin

Bundles the MCP server and workflow skills for Grok Build TUI/CLI. Install from the Grok marketplace (.grok-plugin/marketplace.json). Do not use the Claude marketplace here — that one copies the repo root.

grok plugin marketplace add tienne/gestalt
grok plugin install gestalt --trust

Then add "client": "grok" to your project's gestalt.json so the active session context is written to .grok/rules/gestalt-active.md (which Grok always scans):

{
  "$schema": "./node_modules/@tienne/gestalt/schemas/gestalt.schema.json",
  "client": "grok"
}

Or set GESTALT_CLIENT=grok as an environment variable.

Grok uses host passthrough mode: Gestalt returns prompts and structured context, and Grok performs the reasoning, file edits, and command execution. When client is "grok", this remains true even if ANTHROPIC_API_KEY exists in your shell.

Option 7: Grok Build CLI (MCP only)

If you want the MCP tools without the bundled skills:

grok mcp add gestalt -- npx -y @tienne/gestalt serve

Then add "client": "grok" as in Option 6. This option ships no skills — the pipeline runs entirely through MCP tool calls. Use Option 6 if you want the workflow skills. During execution, active context is written to .grok/rules/gestalt-active.md.

Option 8: Google Gemini CLI

gemini mcp add gestalt -- npx -y @tienne/gestalt serve

Or add directly to ~/.gemini/settings.json:

{
  "mcpServers": {
    "gestalt": {
      "command": "npx",
      "args": ["-y", "@tienne/gestalt", "serve"]
    }
  }
}

Then add "client": "codex" to your project's gestalt.json — Gemini CLI reads AGENTS.md for persistent context, same as Codex:

{
  "$schema": "./node_modules/@tienne/gestalt/schemas/gestalt.schema.json",
  "client": "codex"
}

Use the /mcp command inside a Gemini CLI session to verify the server is connected.

Interview + Spec: The Core Differentiator

Claude Code and Cursor are excellent at executing tasks. Where they struggle is when the task itself is unclear. Gestalt fills that gap: before any code is written, it conducts a structured interview that surfaces assumptions, resolves contradictions, and captures acceptance criteria — producing a Spec precise enough to drive a dependency-aware execution plan.

1. Interview

Start with any topic. A rough sentence is enough.

/interview "I want to build a checkout flow with Stripe"

Gestalt conducts a multi-round interview. Each round targets the weakest resolution dimension using a weighted impact score (1 - clarity) × weight, so the interview always attacks the most critical gap first.

The five principles guide the process:

Principle	Role
Closure	What's missing? Surfaces implicit requirements you haven't said yet
Proximity	Which features belong together? Groups by domain
Similarity	Are there repeating patterns across requirements?
Figure-Ground	What's the core MVP vs. what's optional?
Continuity	Any contradictions? Detected and penalized until resolved

The resolution score rises across four dimensions:

Dimension	Principle	Greenfield weight	Brownfield weight
goalClarity	Closure	0.40	0.30
constraintClarity	Proximity	0.25	0.20
successCriteria	Similarity	0.20	0.15
priorityClarity	Figure-Ground	0.15	0.15
contextClarity	Continuity	—	0.20

The interview continues until overall ≥ 0.8:

Round 1 → resolution: 0.28  (lots of unknowns)
Round 4 → resolution: 0.55  (getting clearer)
Round 8 → resolution: 0.81  ready for Spec

Contradictions are penalized directly: unresolved contradictions subtract up to 0.15 from the overall score, making it structurally impossible to reach 0.8 without resolving them first.

Context Compression

When rounds exceed 5, Gestalt signals that compression is available. Use the compress action to summarize earlier rounds and keep the context window lean:

1. respond returns needsCompression: true + compressionContext
2. ges_interview({ action: "compress", sessionId }) → compressionContext
3. Caller generates summary → submits it → stored in session

The compressed summary is automatically injected into all subsequent rounds.

2. Spec Generation

From a completed interview:

/spec

From text (no interview required):

ges_generate_spec({ text: "Build a checkout flow with Stripe" })

With a built-in template:

Template ID	Description
`rest-api`	REST API with auth, CRUD, and OpenAPI
`react-dashboard`	React dashboard with charts, filters, and responsive layout
`cli-tool`	CLI with subcommands, config file, and distribution

ges_generate_spec({ text: "API with JWT authentication", template: "rest-api" })

The generated Spec includes:

goal                → Clear, precise project objective
constraints         → Technical and business constraints
acceptanceCriteria  → Measurable, verifiable success conditions
ontologySchema      → Entity-relationship model
gestaltAnalysis     → Key findings per Gestalt principle

Memory: The Feedback Loop

Every spec and execution result is automatically recorded in .gestalt/memory.json at your repo root.

{
  "specHistory": [
    { "specId": "...", "goal": "Build a user auth system", "sourceType": "text" }
  ],
  "executionHistory": [],
  "architectureDecisions": []
}

The interview gets shorter over time. When prior specs and execution history exist, Gestalt automatically injects that context into the gestaltContext.systemPrompt at the start of each new interview session. Prior goals, architecture decisions, and constraints become shared knowledge — the AI already knows what you've built and why.

Commit it. .gestalt/memory.json is plain JSON. Teammates inherit all prior decisions on git pull.

User profile. Personal preferences are stored in ~/.gestalt/profile.json and are never committed.

Code Knowledge Graph

Build a static dependency graph of your codebase and extract blast-radius impact files for any change — so Gestalt's review and evolution steps only process the files that actually matter.

# Build or incrementally update the graph
ges_code_graph({ action: "build", repoRoot: "/path/to/repo" })

# Find all files impacted by a commit
ges_code_graph({ action: "blast_radius", repoRoot: "...", commitSha: "abc123" })

# Find files impacted by uncommitted changes
ges_code_graph({ action: "diff_radius", repoRoot: "..." })

Stored at .gestalt/code-graph.db (WAL SQLite, separate from the event store). After gestalt init, a post-commit hook keeps it current automatically.

Language support:

Language	Extensions	Support level
TypeScript / JavaScript	`.ts`, `.tsx`, `.js`, `.jsx`	First-class — TypeScript Compiler API, full AST analysis
Python, Go, Java, Kotlin, Rust, Swift, Objective-C	various	Regex-based best-effort — basic function/class/import extraction; dynamic imports, macros, and metaprogramming may be missed

See Code Knowledge Graph docs for the full reference.

Execute → Evaluate → Evolve

These stages run in Passthrough mode — Claude Code performs the actual file edits and code execution through its tools (Bash, Edit, etc.). Execute carries out real work; Gestalt manages state and advances the pipeline. No API key is used in this stage.

3. Execute

Transform the Spec into a dependency-aware execution plan and run it:

/execute

Planning applies four Gestalt principles in a fixed sequence:

Step	Principle	What it does
1	Figure-Ground	Classifies acceptance criteria as critical vs. supplementary
2	Closure	Decomposes ACs into atomic tasks, including implicit ones
3	Proximity	Groups related tasks by domain
4	Continuity	Validates the dependency DAG — no cycles, topological order confirmed

Execution runs tasks in topological order. After each task, drift detection checks alignment with the Spec:

3-dimensional score: Goal (50%) + Constraint (30%) + Ontology (20%)
Jaccard similarity measurement
Auto-triggers a retrospective when drift exceeds the threshold

Parallel Execution

The plan_complete response includes parallelGroups: string[][]. Tasks with no mutual dependencies are placed in the same group and can run concurrently:

"parallelGroups": [
  ["setup-db", "setup-env"],
  ["create-schema"],
  ["seed-data", "run-tests"]
]

Resuming an Interrupted Session

ges_execute({ action: "resume", sessionId: "<id>" })

Returns ResumeContext: completed task IDs, next task, and progressPercent. The ges_status response also includes resumeContext automatically for any active session.

Brownfield Audit

When a codebase already exists, audit it against the Spec before running new tasks:

# Step 1: request audit context
ges_execute({ action: "audit", sessionId: "<id>" })
# → returns auditContext (systemPrompt, auditPrompt)

# Step 2: submit codebase snapshot + audit result
ges_execute({
  action: "audit",
  sessionId: "<id>",
  codebaseSnapshot: "...",
  auditResult: {
    implementedACs: [0, 2],
    partialACs: [1],
    missingACs: [3],
    gapAnalysis: "..."
  }
})

Sub-Agent Spawning

Decompose a complex task into sub-tasks dynamically during execution:

ges_execute({
  action: "spawn",
  sessionId: "<id>",
  parentTaskId: "task-3",
  subTasks: [
    { title: "Write DB schema", description: "..." },
    { title: "Run migration", description: "...", dependsOn: ["spawned-<id>"] }
  ]
})

Real-Time Progress Panel

The /execute slash command displays live execution status in the Claude Code Task panel — completed/total tasks, current task name, failed count, and parallel group progress. Updated automatically at each planning step, task completion, and evaluation stage.

4. Evaluate

Execution triggers a two-stage evaluation automatically:

Stage	Method	On failure
1	Structural — runs lint → build → test	Short-circuits; Stage 2 is skipped
2	Contextual — LLM validates each AC and goal alignment	Enters the Evolution Loop

Success condition: score ≥ 0.85 AND goalAlignment ≥ 0.80

5. Evolve

When evaluation fails, the Evolution Loop engages. Three recovery flows are available:

Flow A — Structural Fix (when lint/build/test fails)

evolve_fix → submit fix tasks → re-evaluate

Flow B — Contextual Evolution (when AC score is too low)

evolve → patch Spec (ACs/constraints) → re-execute impacted tasks → re-evaluate

Spec patch scope: ACs and constraints are freely editable; ontology can be extended; goal is immutable.

Flow C — Lateral Thinking (when stagnation is detected)

Gestalt rotates through lateral thinking personas rather than terminating:

Stagnation Pattern	Persona	Strategy
Hard cap hit	Multistability	View from a different angle
Oscillating scores	Simplicity	Strip down and converge
No progress (no drift)	Reification	Fill in what's missing
Diminishing returns	Invariance	Replicate what worked

When all four personas are exhausted, the session ends with Human Escalation — a structured list of actionable suggestions for manual resolution.

Termination conditions:

Condition	Trigger
`success`	score ≥ 0.85 AND goalAlignment ≥ 0.80
`stagnation`	2 consecutive rounds with delta < 0.05
`oscillation`	2 consecutive score reversals
`hard_cap`	3 structural + 3 contextual failures
`caller`	Manual termination
`human_escalation`	All 4 lateral personas exhausted

Code Review

When evolution finishes, code review starts automatically:

review_start → agents submit perspectives → consensus → auto-fix

The review context-collector uses blastRadius() from the Code Knowledge Graph to scope analysis to impacted files only — falling back gracefully if no graph DB exists. See Agents for the full list of built-in reviewers.

Agents

Use any agent directly, outside the pipeline:

# List all available agents
/agent

# Run a specific agent on any task
/agent architect "review the module boundaries in this codebase"
/agent security-reviewer "check this authentication code for vulnerabilities"
/agent technical-writer "write a README for this module"

Role Agents

Nine built-in role agents provide multi-perspective review:

Agent	Domain
`architect`	System design, scalability
`frontend-developer`	UI, React, accessibility
`backend-developer`	API, database, server
`devops-engineer`	CI/CD, infrastructure, monitoring
`qa-engineer`	Testing, quality, automation
`designer`	UX/UI, design systems
`product-planner`	Roadmap, user stories, metrics
`researcher`	Analysis, data, benchmarks
`technical-writer`	Documentation, API docs, guides, README

Review Agents

Four built-in review agents run focused code analysis:

Agent	Focus
`security-reviewer`	Injection, XSS, auth vulnerabilities, secrets
`performance-reviewer`	Memory leaks, N+1 queries, bundle size, async
`quality-reviewer`	Readability, SOLID, error handling, DRY
`frontend-reviewer`	UI/React review, accessibility, bundle optimization
`comment-reviewer`	Comment hygiene — restated code, dead code, stale comments, untracked TODOs

Custom Agents

Generate a custom Role Agent from interview results:

# Step 1: get agent creation context
ges_create_agent({ action: "start", sessionId: "<id>" })
# → returns agentContext (systemPrompt, creationPrompt, schema)

# Step 2: submit the generated AGENT.md content
ges_create_agent({ action: "submit", sessionId: "<id>", agentContent: "..." })
# → creates agents/{name}/AGENT.md

CLI Mode

Run Gestalt without Claude Code. Requires ANTHROPIC_API_KEY.

# Start an interactive interview
npx @tienne/gestalt interview "my topic"

# Generate a Spec from a completed session
npx @tienne/gestalt spec <session-id>

# List all sessions
npx @tienne/gestalt status

# Generate gestalt.json config
npx @tienne/gestalt setup

# Start the MCP server manually
npx @tienne/gestalt serve

Configuration

Generate a gestalt.json with IDE autocomplete support:

npx @tienne/gestalt setup

{
  "$schema": "./node_modules/@tienne/gestalt/schemas/gestalt.schema.json",
  "llm": {
    "model": "claude-sonnet-4-20250514"
  },
  "interview": {
    "resolutionThreshold": 0.8,
    "maxRounds": 10
  },
  "execute": {
    "driftThreshold": 0.3,
    "successThreshold": 0.85,
    "goalAlignmentThreshold": 0.80
  },
  "client": "claude-code"
}

Config priority (highest → lowest): code overrides → shell env vars → .env → gestalt.json → built-in defaults

Client Setting

The client field controls where Gestalt writes the active session context during execution:

Value	Context file	When to use
`"claude-code"` (default)	`.claude/rules/gestalt-active.md`	Claude Code (CLI, Desktop, Plugin)
`"codex"`	`AGENTS.md` (managed section)	OpenAI Codex CLI, Google Gemini CLI
`"grok"`	`.grok/rules/gestalt-active.md`	Grok Build TUI/CLI
`"both"`	Claude + Codex only (not Grok)	Shared repos used by Claude Code and Codex

"codex" is the right value for both Codex CLI and Gemini CLI — both read AGENTS.md for persistent project context. "both" never writes .grok/rules/.

When client is "claude-code", "codex", or "grok", MCP interview/spec generation uses passthrough mode even if an Anthropic API key is configured, so the host remains the active LLM. "both" does not force passthrough.

Multi-Provider LLM Tiers

Route LLM calls by task complexity across three tiers:

Tier	Purpose	Example models	Where it runs today
frugal	Lightweight tasks — scoring, classification, short responses	`llama3.2`, `claude-haiku-4-5`	Interview resolution scoring (CLI and `client: "both"` only), per-file KB summaries (only with `summarize: true`)
standard	General tasks — interviews, spec generation	`claude-sonnet-4-20250514`	Question generation, spec generation
frontier	High-complexity reasoning	`claude-opus-4-20250514`	No direct call path yet

Configuring frugal moves both of those onto it. Leave it unset and scoring stays on standard while the KB summary step is skipped entirely — exactly as before. Configuring the tier alone does not enable KB summaries; call ges_generate_kb with summarize: true.

Under Claude Code or Codex the interview runs in Passthrough mode, so the host scores resolution and no adapter is involved; frugal scoring only applies to the CLI. The quality impact has not been measured yet — scripts/verify-frugal-scoring.ts compares both tiers against the golden set.

Mix providers freely. This example uses Anthropic for standard/frontier and a local Ollama model for frugal tasks:

{
  "$schema": "./node_modules/@tienne/gestalt/schemas/gestalt.schema.json",
  "llm": {
    "model": "claude-sonnet-4-20250514",
    "frugal": {
      "provider": "openai",
      "baseURL": "http://localhost:11434/v1",
      "apiKey": "ollama",
      "model": "llama3.2"
    },
    "standard": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    },
    "frontier": {
      "provider": "anthropic",
      "model": "claude-opus-4-20250514"
    }
  }
}

If no tiers are configured, all tiers fall back to the top-level llm.model with the Anthropic adapter — fully backward-compatible.

Environment Variables

Variable	Config path	Default	Description
`ANTHROPIC_API_KEY`	`llm.apiKey`	`""`	Required only for CLI direct mode
`GESTALT_MODEL`	`llm.model`	`claude-sonnet-4-20250514`	LLM model
`GESTALT_RESOLUTION_THRESHOLD`	`interview.resolutionThreshold`	`0.8`	Interview completion threshold
`GESTALT_MAX_ROUNDS`	`interview.maxRounds`	`10`	Max interview rounds
`GESTALT_DRIFT_THRESHOLD`	`execute.driftThreshold`	`0.3`	Task drift detection threshold
`GESTALT_EVOLVE_SUCCESS_THRESHOLD`	`execute.successThreshold`	`0.85`	Evolution success score
`GESTALT_EVOLVE_GOAL_ALIGNMENT_THRESHOLD`	`execute.goalAlignmentThreshold`	`0.80`	Goal alignment threshold
`GESTALT_DB_PATH`	`dbPath`	`~/.gestalt/events.db`	SQLite event store path
`GESTALT_SKILLS_DIR`	`skillsDir`	`skills`	Custom skills directory
`GESTALT_AGENTS_DIR`	`agentsDir`	`agents`	Custom agents directory
`GESTALT_LOG_LEVEL`	`logLevel`	`info`	Log level (`debug`/`info`/`warn`/`error`)
`GESTALT_CLIENT`	`client`	`claude-code`	MCP client type (`claude-code`/`codex`/`both`/`grok`)
`GESTALT_LLM_FRUGAL_PROVIDER`	`llm.frugal.provider`	`anthropic`	Frugal tier provider
`GESTALT_LLM_FRUGAL_API_KEY`	`llm.frugal.apiKey`	`""`	Frugal tier API key
`GESTALT_LLM_FRUGAL_BASE_URL`	`llm.frugal.baseURL`	`""`	Frugal tier base URL (e.g. Ollama)
`GESTALT_LLM_FRUGAL_MODEL`	`llm.frugal.model`	—	Frugal tier model
`GESTALT_LLM_STANDARD_PROVIDER`	`llm.standard.provider`	`anthropic`	Standard tier provider
`GESTALT_LLM_STANDARD_API_KEY`	`llm.standard.apiKey`	`""`	Standard tier API key
`GESTALT_LLM_STANDARD_BASE_URL`	`llm.standard.baseURL`	`""`	Standard tier base URL
`GESTALT_LLM_STANDARD_MODEL`	`llm.standard.model`	—	Standard tier model
`GESTALT_LLM_FRONTIER_PROVIDER`	`llm.frontier.provider`	`anthropic`	Frontier tier provider
`GESTALT_LLM_FRONTIER_API_KEY`	`llm.frontier.apiKey`	`""`	Frontier tier API key
`GESTALT_LLM_FRONTIER_BASE_URL`	`llm.frontier.baseURL`	`""`	Frontier tier base URL
`GESTALT_LLM_FRONTIER_MODEL`	`llm.frontier.model`	—	Frontier tier model

How It Works

Vague requirements are the primary cause of implementation drift. When the goal isn't precise, Claude fills gaps with assumptions — and those assumptions diverge from intent as the project grows.

Gestalt addresses this before any code is written. It runs a structured interview guided by five Gestalt psychology principles to raise requirement resolution to a measurable threshold (≥ 0.8). The result is a Spec: a validated JSON document that drives every subsequent step.

Passthrough Mode

Gestalt runs as an MCP server. In host passthrough mode, the connected coding agent, such as Claude Code or Codex, acts as the LLM: Gestalt returns prompts and context, and the host does the reasoning. Execute/review stages always use this pattern because the host owns file edits and command execution.

You (in Claude Code or Codex)
       │
       ▼  /interview "topic" or ges_interview
  Gestalt MCP Server
  (returns context + prompts)
       │
       ▼
  Host agent executes the prompts
  (generates questions, scores, plans)
       │
       ▼
  Gestalt MCP Server
  (validates, stores state, advances)
       │
       ▼  repeat until resolution ≥ 0.8
  Final Spec → Execution Plan

Architecture

Claude Code (you)
     │
     ▼  MCP / stdio transport
┌──────────────────────────────────┐
│        Gestalt MCP Server        │
│                                  │
│  Interview Engine                │
│  ├─ GestaltPrincipleSelector     │
│  ├─ ResolutionScorer             │
│  ├─ SessionManager               │
│  └─ ContextCompressor            │
│                                  │
│  Spec Generator                  │
│  ├─ PassthroughSpecGenerator     │
│  └─ SpecTemplateRegistry         │
│                                  │
│  Execute Engine                  │
│  ├─ DAG Validator                │
│  ├─ ParallelGroupsCalculator     │
│  ├─ DriftDetector                │
│  ├─ EvaluationEngine             │
│  ├─ AuditEngine                  │
│  └─ ExecuteSessionManager        │
│                                  │
│  Resilience Engine               │
│  ├─ StagnationDetector           │
│  ├─ LateralThinkingPersonas      │
│  └─ HumanEscalation              │
│                                  │
│  Review Pipeline                 │
│  ├─ AgentMatcher                 │
│  ├─ ContextCollector (blastRadius)│
│  └─ ReportGenerator              │
│                                  │
│  Agent System                    │
│  ├─ RoleAgentRegistry            │
│  ├─ RoleMatchEngine              │
│  └─ RoleConsensusEngine          │
│                                  │
│  Knowledge Base + Memory          │
│  ├─ KB Generator/Search/Sync     │
│  └─ ProjectMemoryStore           │
│                                  │
│  Code Graph Viz (D3.js, local HTTP)│
│                                  │
│  EventStore (SQLite WAL)         │
└──────────────────────────────────┘

Further reading:

MCP Reference — all tools, parameters, and action schemas
Getting Started — 5-minute walkthrough
Configuration Reference — full config options
Code Knowledge Graph — static analysis and blast-radius
Local PR — in-repo pull requests for agent-to-agent review

License

MIT © tienne

Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.claude-plugin		.claude-plugin
.claude		.claude
.github/workflows		.github/workflows
.grok-plugin		.grok-plugin
.grok		.grok
assets		assets
benchmarks		benchmarks
bin		bin
codex-skills		codex-skills
docs		docs
plugin		plugin
schemas		schemas
scripts		scripts
src		src
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmignore		.npmignore
.nvmrc		.nvmrc
.prettierrc.json		.prettierrc.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
README.ko.md		README.ko.md
README.md		README.md
eslint.config.js		eslint.config.js
gestalt.json		gestalt.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

Contents