Hegelion
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Hegelion Autocode a Python function that sorts a list."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Hegelion
"The True is the whole." — G.W.F. Hegel
Hegelion applies dialectical reasoning to LLMs: forcing models to argue with themselves before reaching conclusions. This produces better reasoning for questions and better code for implementations.
Hegelion is prompt-driven by default: it generates structured prompts for your editor to execute, no API keys required. Optional server-side backends enable direct execution and independent coach verification.
Use it via MCP in Claude Desktop, Cursor, VS Code, or any MCP-enabled editor, or via the Python API in your own agents.
Two Modes
Mode | Pattern | Use Case |
Dialectical Reasoning | Thesis → Antithesis → Synthesis | Deep analysis of questions, philosophy, strategy |
Autocoding | Player → Coach → Iterate | Verified code implementations with independent review |
Both modes use the same principle: force the model to oppose itself before concluding. This catches blind spots that single-pass approaches miss.
Related MCP server: Cognitive Diagram Navigation MCP Server
Autocoding: Player-Coach Loop
Updated in v0.5.0 — Based on Block AI's g3 agent research.
The Problem
Single-agent coding tools often:
Declare success prematurely ("I have successfully implemented all requirements!")
Accumulate context pollution over long sessions
Miss edge cases because they verify their own work
The Solution
Two roles iterate until requirements are verified:
REQUIREMENTS (Source of Truth)
│
▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ PLAYER │────▶│ COACH │────▶│ ADVANCE │
│ Implements │ │ Verifies │ │ State │
│ code & tests │ │ independently │ │ │
└───────────────┘ └───────────────┘ └───────┬───────┘
▲ │
│ ┌───────────┐ │
└──────────────│ APPROVED? │◀───────────────┘
└───────────┘
│ │
No Yes
│ │
▼ ▼
Continue DonePlayer: Implements requirements, writes tests, responds to feedback. Does NOT declare success.
Coach: Independently verifies each requirement, ignores player's self-assessment, outputs structured checklist. When Codex MCP is available, Hegelion can launch a separate Codex session to act as the coach while the current session remains the player.
Key Insight
"Discard the player's self-report of success. Have the coach perform independent evaluation."
The coach catches issues by re-reading requirements and actually running tests—not by trusting what the player says it did.
Quick Start (Autocoding)
In Claude Code, Cursor, or any MCP-enabled editor:
Tip: if your editor exposes slash commands, you can use /hegelion as a wrapper.
The underlying MCP tools are autocode and autocode_turn.
You: Call autocode with mode=init and these requirements:
- Add user authentication to src/api.py
- Add tests in tests/test_auth.py
- All tests must pass
[Session initializes]
You: Call autocode_turn with role=player and implement
[Player writes code and tests]
You: Call autocode_turn with role=coach, execute=true, backend=auto, cwd=<workspace>
[Separate Codex coach verifies the workspace when available]
You: Call autocode_turn with role=advance, coach_feedback, approved=false
[Loop until COACH APPROVED]State flow: Each autocode_turn returns an updated state for the next call — pass it into the next tool invocation. All outputs include schema_version for client stability. See MCP Integration for Codex coach setup.
MCP Tools
Tool | Purpose |
| Unified dialectical reasoning ( |
| Unified autocoding entrypoint ( |
| Execute one autocoding turn ( |
| Persist or restore sessions ( |
Codex Skill (optional)
This repo includes a Codex skill at skills/hegelion/SKILL.md. Install it with your skill
installer (for example, install-skill-from-github.py --repo Hmbown/Hegelion --path skills/hegelion).
It mirrors the /hegelion command, treats the current Codex session as the player, and routes coach turns to a separate Codex backend when available.
Why It Works
Problem | Single Agent | Coach-Player |
Anchoring | Drifts from requirements | Requirements anchor every turn |
Verification | Self-assessment (unreliable) | Independent verification |
Context | Accumulates pollution | Fresh context each turn |
Completion | Open-ended | Explicit approval gates |
Dialectical Reasoning: Thesis → Antithesis → Synthesis
For questions requiring deep analysis, Hegelion forces three separate LLM calls:
[Call 1] Thesis → LLM commits to a position
[Call 2] Antithesis → LLM attacks that position (separate call, no hedging)
[Call 3] Synthesis → LLM reconciles the oppositionWhy Separate Calls Matter
Method | Calls | Result |
Raw | 1 | "It depends on definitions..." |
Enhanced | 1 | "Hold both views in tension..." |
Hegelion | 3 | Novel framework with testable predictions |
When the model must commit to a thesis, then genuinely attack it in a separate call, the synthesis surfaces insights that single-call approaches shortcut.
Hegelion synthesis (after thesis and antithesis):
The deadlock dissolves when we recognize free will exists on a spectrum of self-authorship:
Minimal freedom: Acting on desires without external coercion
Reflective freedom: Second-order endorsement—I want to want this
Narrative freedom: Acting consistently with a coherent life narrative
Constitutive freedom: Recursive self-modification through deliberate habituation
Research proposal: Use fMRI to scan participants under (1) snap judgments, (2) brief reflection, (3) extended deliberation. Hypothesis: Condition (3) shows strongest correlation with self-reported decision "ownership."
This 4-level framework emerged from actually arguing with itself—not from asking for "thesis/antithesis/synthesis" in one prompt.
Quick Start (Dialectical)
pip install hegelion
# MCP setup (auto-detects OS)
hegelion-setup-mcp --host claude-desktop
# MCP setup for Claude Desktop (macOS)
hegelion-setup-mcp --write "$HOME/Library/Application Support/Claude/claude_desktop_config.json"Or use the prompt-driven Python API (you run the prompt with your LLM of choice):
from hegelion.core.prompt_dialectic import create_single_shot_dialectic_prompt
prompt = create_single_shot_dialectic_prompt(
"Is AI conscious?",
use_council=True,
response_style="sections",
)
print(prompt)Health check (lists tools + generates a sample prompt):
hegelion-server --self-testFeature Toggles
Option | Description |
| Three critics: Logician, Empiricist, Ethicist |
| Grounds arguments with web search |
|
|
Installation
pip install hegelionFor MCP integration (works with any MCP-enabled editor):
# Shortcuts
hegelion-setup-mcp --host claude-desktop
hegelion-setup-mcp --host cursor
hegelion-setup-mcp --host vscode
hegelion-setup-mcp --host windsurf
# Claude Desktop (macOS)
hegelion-setup-mcp --write "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
# Claude Desktop (Windows)
hegelion-setup-mcp --write "%APPDATA%\\Claude\\claude_desktop_config.json"
# Claude Desktop (Linux)
hegelion-setup-mcp --write "$HOME/.config/Claude/claude_desktop_config.json"
# Then restart your MCP hostClaude Code (no MCP setup needed):
# Use /hegelion command directly in any Hegelion repo clone
# Or add MCP server for tool access
claude mcp add hegelion python -- -m hegelion.mcp.serverManual config (any MCP host):
{
"mcpServers": {
"hegelion": {
"command": "python",
"args": ["-m", "hegelion.mcp.server"]
}
}
}If you run from source (not site-packages), set PYTHONPATH to the repo root. The hegelion-setup-mcp command writes this automatically.
If your host expects a full command path, use python -m hegelion.mcp.server instead of hegelion-server.
Supported editors: Claude Desktop, Claude Code, Cursor, VS Code + GitHub Copilot, Windsurf, Google Antigravity, Gemini CLI
See MCP Integration Guide for setup instructions.
Documentation
MCP Integration — Setup for Claude Desktop, Cursor, VS Code + Copilot, Windsurf, Antigravity, Gemini CLI
Python API — Prompt-driven API reference
CLI Reference — MCP server and setup commands
Configuration — Backends and feature toggles
Technical Specification — Output schemas, phase specs
Contributing
Issues and PRs welcome. For significant changes, open a discussion first.
Recent Changes
v0.5.0 (March 2026)
Execution backends: Added
prompt,cli,codex_mcp, andautobackend selection for MCP execution flowsIndependent Codex coach:
autocode_turn(role=coach, execute=true)can now run through a separate Codex MCP session and returncoach_feedbackPrompt fallback:
backend=autonow degrades cleanly to prompt-only output when no executable backend is availableLangGraph removal: Removed the LangGraph package, dependency extra, tests, and docs references
MCP tool consolidation: 14 tools simplified to 4 unified tools:
dialectic,autocode,autocode_turn,autocode_sessionState machine simplification:
AutocodingStatusremoved;phaseis now the only state indicatorSchema migration:
schema_versionbumped to2with backward-compatible v1-to-v2 loadingValidation cleanup: Added
@validateddecorator + typed specs to remove repetitive handler boilerplateDead code removal: Removed unused judge path, unused conversation state, and deprecated response styles
Python 3.13 support: Added to CI and classifiers
Public API exports:
hegelionnow exports key classes directly (DialecticalPrompt,PromptDrivenDialectic,AutocodingState, etc.)PEP 561
py.typedmarker: Enables type-checker support for library consumers--versionflag: Bothhegelion-serverandhegelion-setup-mcpnow support--version
Note: v0.4.x entries below reference pre-v0.5 tool names (e.g.
dialectical_single_shot). These were replaced by the unifieddialectictool in v0.5.0.
v0.4.6 (February 4, 2026)
CI fix: Fixed CI pipeline and automated release workflow
v0.4.5 (February 4, 2026)
Single-call CLI execution for
dialectical_single_shot:execute,timeout_seconds,max_retrieshegelion-setup-mcpflags:--llm-command-json,--llm-command,--auto-execute
v0.4.4 (January 21, 2026)
Simplified skill/command: Condensed to minimal routing tables, MCP-first approach
v0.4.3 (January 12, 2026)
MCP refactor: Split tooling, handlers, and validation to make the server easier to extend and maintain
Codex skill: Added
skills/hegelion/SKILL.mdfor the/hegelionworkflow
License: MIT
Available Tools
4 toolsautocodeB
Start autocoding (g3 coach-player paradigm). mode=init: create session state. mode=workflow: step-by-step recipe. mode=single_shot: one comprehensive prompt.
Inputs: requirements (required), mode, max_turns, session_name.
autocode_sessionB
Save or load an autocoding session. action=save: persist state to file. action=load: restore state from file.
Inputs: action (required), filepath (required), state.
autocode_turnA
Execute one step in the autocoding loop. role=player: generate implementation prompt (advances state to coach). role=coach: generate verification prompt. role=advance: advance state after coach review.
Inputs: role (required), state (required), cwd, backend, +4 more.
dialecticB
Dialectical reasoning (thesis → antithesis → synthesis). Modes: single_shot (one prompt), workflow (step-by-step recipe), thesis/antithesis/synthesis (individual phase prompts). Use response_style to control output: 'json', 'sections', or 'synthesis_only'.
Inputs: query (required), cwd, mode, format, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
autocode, autocode_turn, and autocode_session all relate to the same autocoding workflow, which creates moderate overlap—autocode handles the high-level entry points while the others handle sub-parts, but an agent might confuse 'autocode' with 'autocode_turn' since both generate prompts. dialectic is clearly distinct. The separation of concerns is mostly clear but the naming makes the boundaries less obvious than they could be.
All names are lowercase single words in snake_case convention, which is consistent. However, dialectic does not follow the verb-oriented pattern (autocode is a verb-noun, autocode_turn is a verb-noun, autocode_session is a verb-noun, but dialectic is a bare noun), making it the outlier in style.
Four tools for a reasoning/coaching paradigm server is a reasonable, focused scope. Each tool addresses a distinct slice (dialectic reasoning, autocoding orchestration, step execution, session persistence), and none feel redundant or extraneous.
The dialectic tool covers the reasoning workflow well, and the autocoding trio covers init, workflow, single-step execution, and session persistence. However, there's no session-management tool for the dialectic workflow (only autocode has save/load), and no explicit mechanism for resetting or inspecting sessions, which are notable gaps.
Maintenance
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server teaching AI agents to implement TideCloak: auth, E2EE, IGA, security analysis
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server implementing the Chain-of-Recursive-Thoughts (CoRT) methodology that makes AI think harder by making it argue with itself repeatedly through multiple rounds of alternative generation and evaluation.5MIT
- AlicenseBqualityDmaintenanceAn advanced MCP server implementing diagrammatic reasoning with memory-augmented spatial exploration, enabling structured chain-of-thought reasoning through visual reasoning spaces.18MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that enables verified code execution with LLM reasoning using Recursive Language Models (RLM). It supports tasks like code generation, data analysis, and complex task decomposition.2MIT
- FlicenseNot gradedqualityAmaintenanceAn MCP server that enables dialectical reasoning by forcing separate thesis, antithesis, and synthesis passes over questions, and verifies code implementations through an independent player-coach loop with explicit approval gates. It works in Claude Desktop, Cursor, VS Code, Windsurf, and other MCP-enabled editors without API keys.-