Skip to main content
Glama
Hegelion

Hegelion

by Hmbown

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.

License: MIT Python 3.10+ PyPI version


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   Done

Player: 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

dialectic

Unified dialectical reasoning (mode: single_shot, workflow, thesis, antithesis, synthesis)

autocode

Unified autocoding entrypoint (mode: init, workflow, single_shot)

autocode_turn

Execute one autocoding turn (role: player, coach, advance)

autocode_session

Persist or restore sessions (action: save, load)

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 opposition

Why 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:

  1. Minimal freedom: Acting on desires without external coercion

  2. Reflective freedom: Second-order endorsement—I want to want this

  3. Narrative freedom: Acting consistently with a coherent life narrative

  4. 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-test

Feature Toggles

Option

Description

use_council

Three critics: Logician, Empiricist, Ethicist

use_search

Grounds arguments with web search

response_style

sections, json, or synthesis_only


Installation

pip install hegelion

For 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 host

Claude 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.server

Manual 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


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, and auto backend selection for MCP execution flows

  • Independent Codex coach: autocode_turn(role=coach, execute=true) can now run through a separate Codex MCP session and return coach_feedback

  • Prompt fallback: backend=auto now degrades cleanly to prompt-only output when no executable backend is available

  • LangGraph 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_session

  • State machine simplification: AutocodingStatus removed; phase is now the only state indicator

  • Schema migration: schema_version bumped to 2 with backward-compatible v1-to-v2 loading

  • Validation cleanup: Added @validated decorator + typed specs to remove repetitive handler boilerplate

  • Dead 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: hegelion now exports key classes directly (DialecticalPrompt, PromptDrivenDialectic, AutocodingState, etc.)

  • PEP 561 py.typed marker: Enables type-checker support for library consumers

  • --version flag: Both hegelion-server and hegelion-setup-mcp now support --version

Note: v0.4.x entries below reference pre-v0.5 tool names (e.g. dialectical_single_shot). These were replaced by the unified dialectic tool 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_retries

  • hegelion-setup-mcp flags: --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.md for the /hegelion workflow


License: MIT

Available Tools

4 tools
autocodeB

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

    B3.3/5.0

    Scored across 4 tools

    Disambiguation3/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      2
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      An 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.
      -