{"id":43640416,"url":"https://github.com/hmbown/hegelion","last_synced_at":"2026-02-04T18:03:02.184Z","repository":{"id":324763847,"uuid":"1097223877","full_name":"Hmbown/Hegelion","owner":"Hmbown","description":"Dialectical reasoning architecture for LLMs (Thesis → Antithesis → Synthesis)","archived":false,"fork":false,"pushed_at":"2026-01-21T22:39:40.000Z","size":2932,"stargazers_count":107,"open_issues_count":0,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-22T11:56:44.230Z","etag":null,"topics":["ai-safety","anthropic","auto-code","benchmarking","dialecticism","evaluation","hegelian","llm","mcp","ollama","openai","pair-programming","reasoning","research"],"latest_commit_sha":null,"homepage":"https://hegelion-web.pages.dev/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hmbown.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"Hmbown"}},"created_at":"2025-11-15T19:06:33.000Z","updated_at":"2026-01-21T22:38:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Hmbown/Hegelion","commit_stats":null,"previous_names":["hmbown/hegelion"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/Hmbown/Hegelion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hmbown%2FHegelion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hmbown%2FHegelion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hmbown%2FHegelion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hmbown%2FHegelion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hmbown","download_url":"https://codeload.github.com/Hmbown/Hegelion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hmbown%2FHegelion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29092732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-safety","anthropic","auto-code","benchmarking","dialecticism","evaluation","hegelian","llm","mcp","ollama","openai","pair-programming","reasoning","research"],"created_at":"2026-02-04T18:02:57.699Z","updated_at":"2026-02-04T18:03:02.179Z","avatar_url":"https://github.com/Hmbown.png","language":"Python","funding_links":["https://github.com/sponsors/Hmbown"],"categories":[],"sub_categories":[],"readme":"# Hegelion\n\n\u003e \"The True is the whole.\" — G.W.F. Hegel\n\nHegelion 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.\n\nHegelion is prompt-driven by default: it generates prompts for your editor or LLM to execute, with no API keys required.\nUse it via MCP in editors like Claude Desktop/Cursor/VS Code, or via the Python API in your own agents.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg) [![PyPI version](https://img.shields.io/pypi/v/hegelion.svg)](https://pypi.org/project/hegelion/)\n\n---\n\n## Two Modes\n\n| Mode | Pattern | Use Case |\n|------|---------|----------|\n| **Dialectical Reasoning** | Thesis → Antithesis → Synthesis | Deep analysis of questions, philosophy, strategy |\n| **Autocoding** | Player → Coach → Iterate | Verified code implementations with independent review |\n\nBoth modes use the same principle: **force the model to oppose itself** before concluding. This catches blind spots that single-pass approaches miss.\n\n---\n\n## Autocoding: Player-Coach Loop\n\n**New in v0.4.0** — Based on [Block AI's g3 agent research](https://block.xyz/documents/adversarial-cooperation-in-code-synthesis.pdf).\n\n### The Problem\n\nSingle-agent coding tools often:\n- Declare success prematurely (\"I have successfully implemented all requirements!\")\n- Accumulate context pollution over long sessions\n- Miss edge cases because they verify their own work\n\n### The Solution\n\nTwo roles iterate until requirements are verified:\n\n```\nREQUIREMENTS (Source of Truth)\n        │\n        ▼\n┌───────────────┐     ┌───────────────┐     ┌───────────────┐\n│    PLAYER     │────▶│     COACH     │────▶│    ADVANCE    │\n│  Implements   │     │   Verifies    │     │    State      │\n│  code \u0026 tests │     │ independently │     │               │\n└───────────────┘     └───────────────┘     └───────┬───────┘\n        ▲                                           │\n        │              ┌───────────┐                │\n        └──────────────│ APPROVED? │◀───────────────┘\n                       └───────────┘\n                         │       │\n                        No      Yes\n                         │       │\n                         ▼       ▼\n                     Continue   Done\n```\n\n**Player**: Implements requirements, writes tests, responds to feedback. Does NOT declare success.\n\n**Coach**: Independently verifies each requirement, ignores player's self-assessment, outputs structured checklist.\n\n### Key Insight\n\n\u003e \"Discard the player's self-report of success. Have the coach perform independent evaluation.\"\n\nThe coach catches issues by re-reading requirements and actually running tests—not by trusting what the player says it did.\n\n### Quick Start (Autocoding)\n\nIn Claude Code, Cursor, or any MCP-enabled editor:\n\nTip: if your editor exposes MCP tools as slash commands, use `/hegelion` (tool `hegelion`)\nas the branded autocoding entrypoint.\n\n```\nYou: Use autocoding_init with these requirements:\n     - Add user authentication to src/api.py\n     - Add tests in tests/test_auth.py\n     - All tests must pass\n\n[Session initializes]\n\nYou: Generate player_prompt and implement\n\n[Player writes code and tests]\n\nYou: Generate coach_prompt and verify\n\n[Coach: ✓ auth endpoint exists, ✗ missing password validation test]\n\nYou: Call autocoding_advance and continue\n\n[Loop until COACH APPROVED]\n```\n\n**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.\n\n### MCP Tools\n\n| Tool | Purpose |\n|------|---------|\n| `hegelion` | Brand-first autocoding entrypoint (`mode`: `init`, `workflow`, `single_shot`) |\n| `autocoding_init` | Start session with requirements checklist |\n| `player_prompt` | Generate implementation prompt |\n| `coach_prompt` | Generate verification prompt |\n| `autocoding_advance` | Update state after coach review |\n| `autocoding_single_shot` | Combined prompt for simpler tasks |\n| `autocoding_save` / `autocoding_load` | Persist and resume sessions |\n\n### Codex Skill (optional)\n\nThis repo includes a Codex skill at `skills/hegelion/SKILL.md`. Install it with your skill\ninstaller (for example, `install-skill-from-github.py --repo Hmbown/Hegelion --path skills/hegelion`).\nIt mirrors the `/hegelion` command and uses MCP tools when available.\n\n### Why It Works\n\n| Problem | Single Agent | Coach-Player |\n|---------|--------------|--------------|\n| **Anchoring** | Drifts from requirements | Requirements anchor every turn |\n| **Verification** | Self-assessment (unreliable) | Independent verification |\n| **Context** | Accumulates pollution | Fresh context each turn |\n| **Completion** | Open-ended | Explicit approval gates |\n\n---\n\n## Dialectical Reasoning: Thesis → Antithesis → Synthesis\n\nFor questions requiring deep analysis, Hegelion forces three separate LLM calls:\n\n```\n[Call 1] Thesis     → LLM commits to a position\n[Call 2] Antithesis → LLM attacks that position (separate call, no hedging)\n[Call 3] Synthesis  → LLM reconciles the opposition\n```\n\n### Why Separate Calls Matter\n\n| Method | Calls | Result |\n|--------|:-----:|--------|\n| **Raw** | 1 | \"It depends on definitions...\" |\n| **Enhanced** | 1 | \"Hold both views in tension...\" |\n| **Hegelion** | 3 | Novel framework with testable predictions |\n\nWhen the model must commit to a thesis, then genuinely attack it in a separate call, the synthesis surfaces insights that single-call approaches shortcut.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExample: \"Is free will compatible with determinism?\"\u003c/b\u003e\u003c/summary\u003e\n\n**Hegelion synthesis** (after thesis and antithesis):\n\n\u003e The deadlock dissolves when we recognize free will exists on a **spectrum of self-authorship**:\n\u003e\n\u003e 1. **Minimal freedom**: Acting on desires without external coercion\n\u003e 2. **Reflective freedom**: Second-order endorsement—I want to want this\n\u003e 3. **Narrative freedom**: Acting consistently with a coherent life narrative\n\u003e 4. **Constitutive freedom**: Recursive self-modification through deliberate habituation\n\u003e\n\u003e **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.\"\n\nThis 4-level framework emerged from actually arguing with itself—not from asking for \"thesis/antithesis/synthesis\" in one prompt.\n\u003c/details\u003e\n\n### Quick Start (Dialectical)\n\n```bash\npip install hegelion\n\n# MCP setup (auto-detects OS)\nhegelion-setup-mcp --host claude-desktop\n\n# MCP setup for Claude Desktop (macOS)\nhegelion-setup-mcp --write \"$HOME/Library/Application Support/Claude/claude_desktop_config.json\"\n```\n\nOr use the prompt-driven Python API (you run the prompt with your LLM of choice):\n\n```python\nfrom hegelion.core.prompt_dialectic import create_single_shot_dialectic_prompt\n\nprompt = create_single_shot_dialectic_prompt(\n    \"Is AI conscious?\",\n    use_council=True,\n    response_style=\"sections\",\n)\nprint(prompt)\n```\n\nHealth check (lists tools + generates a sample prompt):\n\n```bash\nhegelion-server --self-test\n```\n\n### Feature Toggles\n\n| Option | Description |\n|--------|-------------|\n| `use_council` | Three critics: Logician, Empiricist, Ethicist |\n| `use_judge` | Final quality evaluation |\n| `use_search` | Grounds arguments with web search |\n| `response_style` | `sections`, `json`, or `synthesis_only` |\n\n---\n\n## Installation\n\n```bash\npip install hegelion\n```\n\nFor MCP integration (works with any MCP-enabled editor):\n\n```bash\n# Shortcuts\nhegelion-setup-mcp --host claude-desktop\nhegelion-setup-mcp --host cursor\nhegelion-setup-mcp --host vscode\nhegelion-setup-mcp --host windsurf\n\n# Claude Desktop (macOS)\nhegelion-setup-mcp --write \"$HOME/Library/Application Support/Claude/claude_desktop_config.json\"\n\n# Claude Desktop (Windows)\nhegelion-setup-mcp --write \"%APPDATA%\\\\Claude\\\\claude_desktop_config.json\"\n\n# Claude Desktop (Linux)\nhegelion-setup-mcp --write \"$HOME/.config/Claude/claude_desktop_config.json\"\n\n# Then restart your MCP host\n```\n\nClaude Code (no MCP setup needed):\n\n```bash\n# Use /hegelion command directly in any Hegelion repo clone\n# Or add MCP server for tool access\nclaude mcp add hegelion python -- -m hegelion.mcp.server\n```\n\nManual config (any MCP host):\n\n```json\n{\n  \"mcpServers\": {\n    \"hegelion\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"hegelion.mcp.server\"]\n    }\n  }\n}\n```\n\nIf you run from source (not site-packages), set `PYTHONPATH` to the repo root. The `hegelion-setup-mcp` command writes this automatically.\nIf your host expects a full command path, use `python -m hegelion.mcp.server` instead of `hegelion-server`.\n\n**Supported editors:** Claude Desktop, Claude Code, Cursor, VS Code + GitHub Copilot, Windsurf, Google Antigravity, Gemini CLI\n\nSee [MCP Integration Guide](docs/guides/mcp-integration.md) for setup instructions.\n\n---\n\n## Documentation\n\n- **[MCP Integration](docs/guides/mcp-integration.md)** — Setup for Claude Desktop, Cursor, VS Code + Copilot, Windsurf, Antigravity, Gemini CLI\n- **[Python API](docs/guides/python-api.md)** — Prompt-driven API reference\n- **[CLI Reference](docs/guides/cli-reference.md)** — MCP server and setup commands\n- **[Configuration](docs/getting-started/configuration.md)** — Backends and feature toggles\n- **[Technical Specification](docs/HEGELION_SPEC.md)** — Output schemas, phase specs\n\n---\n\n## Contributing\n\nIssues and PRs welcome. For significant changes, open a discussion first.\n\n---\n\n## Recent Changes\n\n### v0.4.4 (January 21, 2026)\n\n- **Simplified skill/command**: Condensed to minimal routing tables, MCP-first approach\n\n### v0.4.3 (January 12, 2026)\n\n- **MCP refactor**: Split tooling, handlers, and validation to make the server easier to extend and maintain\n- **Codex skill**: Added `skills/hegelion/SKILL.md` for the `/hegelion` workflow\n\n### v0.4.2 (January 2026)\n\n- **Unified `/hegelion` command**: Single entry point for dialectical and autocoding workflows\n- **Host shortcuts**: `hegelion-setup-mcp --host claude-desktop|cursor|vscode|windsurf`\n- **Code quality**: Formatted with black, ruff checks passing\n\n### v0.4.1 (December 2025)\n\n- **Schema versioning**: All structured outputs include `schema_version` for client stability\n- **Phase clarity**: `player_prompt` and `coach_prompt` now include `current_phase` and `next_phase` fields\n- **Improved error handling**: Invalid phase transitions return clear errors with `expected`, `received`, and `hint` fields\n- **State validation**: Malformed state inputs return structured error responses instead of exceptions\n\n### v0.4.0 (December 2025)\n\n- **Autocoding system**: Player-coach dialectical loop based on Block AI's g3 agent\n- MCP tools: `autocoding_init`, `player_prompt`, `coach_prompt`, `autocoding_advance`\n- Session persistence with `autocoding_save` / `autocoding_load`\n- Single-shot mode for simpler use cases\n\n### v0.3.x\n\n- CLI streaming with `--stream` flag\n- MCP progress notifications\n- 470+ tests passing\n\n---\n\n**License:** MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmbown%2Fhegelion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhmbown%2Fhegelion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmbown%2Fhegelion/lists"}