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

Both modes use the same principle: force the model to oppose itself before concluding. This catches blind spots that single-pass approaches miss.

New in v0.4.0 — Based on Block AI's g3 agent research.

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

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.

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

In Claude Code, Cursor, or any MCP-enabled editor:

You: Use autocoding_init with these requirements:
     - Add user authentication to src/api.py
     - Add tests in tests/test_auth.py
     - All tests must pass

[Session initializes]

You: Generate player_prompt and implement

[Player writes code and tests]

You: Generate coach_prompt and verify

[Coach: ✓ auth endpoint exists, ✗ missing password validation test]

You: Call autocoding_advance and continue

[Loop until COACH APPROVED]

State passing note: player_prompt returns a player prompt plus an updated state advanced to phase: "coach" for the next call. For clarity, prompt outputs include current_phase (prompt phase) and next_phase (returned state's phase). All structured outputs include schema_version for client stability.

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

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.

pip install hegelion

# MCP setup for Claude Desktop (macOS)
hegelion-setup-mcp --write "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

Or use the Python API:

import asyncio
from hegelion import run_dialectic

async def main():
    result = await run_dialectic("Is AI conscious?")
    print(result.synthesis)

asyncio.run(main())

Or CLI:

hegelion --stream "Is consciousness fundamental or emergent?"

pip install hegelion

For MCP integration (works with any MCP-enabled editor):

# Claude Desktop (macOS)
hegelion-setup-mcp --write "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

# Then restart Claude Desktop

Supported editors: Claude Desktop, Claude Code, Cursor, VS Code + GitHub Copilot, Windsurf, Google Antigravity, Gemini CLI

See MCP Integration Guide for setup instructions.

• MCP Integration — Setup for Claude Desktop, Cursor, VS Code + Copilot, Windsurf, Antigravity, Gemini CLI
• Python API — Full API reference
• CLI Reference — Command-line usage
• Configuration — Backends and feature toggles
• Technical Specification — Output schemas, phase specs

Issues and PRs welcome. For significant changes, open a discussion first.

• Schema versioning: All structured outputs include schema_version for client stability
• Phase clarity: player_prompt and coach_prompt now include current_phase and next_phase fields
• Improved error handling: Invalid phase transitions return clear errors with expected, received, and hint fields
• State validation: Malformed state inputs return structured error responses instead of exceptions

• Autocoding system: Player-coach dialectical loop based on Block AI's g3 agent
• MCP tools: autocoding_init, player_prompt, coach_prompt, autocoding_advance
• Session persistence with autocoding_save / autocoding_load
• Single-shot mode for simpler use cases

• CLI streaming with --stream flag
• MCP progress notifications
• 470+ tests passing

License: MIT