@tienne/gestalt

Gestalt — AI Development Harness
Turn vague requirements into structured, executable plans — right inside Claude Code.

한국어

Gestalt is an MCP (Model Context Protocol) server that runs inside Claude Code. It conducts a structured requirement interview, generates a validated Spec — a JSON document capturing your goal, constraints, and acceptance criteria — and transforms that Spec into a dependency-aware execution plan.

Claude Code acts as the LLM throughout. Gestalt manages state, validates results, and advances the pipeline. No API key required.

In two lines: describe what you want in plain language, and Gestalt interviews you until the requirement is sharp, then turns it into a validated Spec and a dependency-ordered execution plan. Everything runs inside Claude Code — no extra services, no API key.

/interview "user authentication system"   # clarify requirements (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.

Contents

• Quick Start
• Installation
• The Pipeline
  • 1. Interview
  • 2. Spec Generation
  • 3. Execute
  • 4. Evaluate
  • 5. Evolve
  • 6. Code Review
• Agents
• CLI Mode
• Project Memory
• Configuration
• How It Works
• 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	/interview, /spec, /execute, /agent
Agents	5 pipeline agents + 9 Role agents + 3 Review agents
CLAUDE.md	Project context and MCP usage guide auto-injected

Option 2: Claude Code Desktop

Add this to your settings.json (or claude_desktop_config.json) and restart:

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

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

Option 3: Claude Code CLI

claude mcp add gestalt -- npx -y @tienne/gestalt

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

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

Option 4: OpenAI Codex CLI

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.

All 12 MCP tools (ges_interview, ges_generate_spec, ges_execute, etc.) are available immediately. Slash commands and the Claude Code Task panel are not available in Codex — the pipeline runs entirely through MCP tool calls.

Option 5: 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.

The Pipeline

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 a specific resolution dimension:

• Closure — What's missing? What did you assume but not say?
• Proximity — Which features belong together?
• Similarity — Are there repeating patterns across requirements?
• Figure-Ground — What's the core MVP vs. what's optional?
• Continuity — Any contradictions or conflicts?

The interview continues until the resolution score reaches ≥ 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

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

3. Execute

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

/execute

Execute always runs in Passthrough mode — Claude Code performs the actual file edits and code execution through its tools (Bash, Edit, etc.). Configuring an API key does not switch Execute to a self-contained LLM mode; there is no such mode by design.

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

6. Code Review

When evolution finishes, code review starts automatically:

review_start → agents submit perspectives → consensus → auto-fix

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

Three 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

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

Project Memory

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": []
}

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

Context injection. Prior goals and architecture decisions are automatically injected into the next spec prompt.

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

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
"both"	Both locations	Shared repos used by multiple agents

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

Multi-Provider LLM Tiers

Route LLM calls by task complexity across three tiers:

Tier	Purpose	Example models
frugal	Lightweight tasks — scoring, classification, short responses	llama3.2, claude-haiku
standard	General tasks — interviews, spec generation, execution	claude-sonnet-4-20250514
frontier	High-complexity reasoning — architecture, code review, evolution	claude-opus-4-20250514

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)
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.

The Five Gestalt Principles

Principle	Role
Closure	Finds what's missing; surfaces implicit requirements
Proximity	Groups related features and tasks by domain
Similarity	Identifies repeating patterns across requirements
Figure-Ground	Separates MVP (figure) from nice-to-have (ground)
Continuity	Validates dependency chains; detects contradictions

Passthrough Mode

Gestalt runs as an MCP server. Claude Code acts as the LLM: Gestalt returns prompts and context, and Claude Code does the reasoning. The server makes no API calls.

Note: The Execute stage always runs in Passthrough mode, regardless of whether an API key is configured. Execute carries out real file edits and code execution through Claude Code's tools (Bash, Edit, etc.), so Claude Code must be the LLM that drives it — this is by design, not a missing feature.

You (in Claude Code)
       │
       ▼  /interview "topic"
  Gestalt MCP Server
  (returns context + prompts)
       │
       ▼
  Claude Code 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              │
│                                  │
│  Agent System                    │
│  ├─ RoleAgentRegistry            │
│  ├─ RoleMatchEngine              │
│  └─ RoleConsensusEngine          │
│                                  │
│  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

License

MIT © tienne