{"id":50523677,"url":"https://github.com/lukaskellerstein/dex","last_synced_at":"2026-06-03T06:30:36.893Z","repository":{"id":351170915,"uuid":"1209814857","full_name":"lukaskellerstein/dex","owner":"lukaskellerstein","description":"Autonomous feature implementation engine — spawns fresh Claude Code agents per phase (Ralph Wiggum loop) with spec-kit planning, real-time trace UI, and git automation","archived":false,"fork":false,"pushed_at":"2026-05-24T13:07:20.000Z","size":4583,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T15:06:27.979Z","etag":null,"topics":["ai-agents","autonomous-coding","claude-agent-sdk","claude-code","electron","react","spec-kit","sqlite","typescript","vite"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukaskellerstein.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T20:07:28.000Z","updated_at":"2026-05-24T13:03:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lukaskellerstein/dex","commit_stats":null,"previous_names":["lukaskellerstein/ralph-claude","lukaskellerstein/dex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lukaskellerstein/dex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaskellerstein%2Fdex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaskellerstein%2Fdex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaskellerstein%2Fdex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaskellerstein%2Fdex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukaskellerstein","download_url":"https://codeload.github.com/lukaskellerstein/dex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukaskellerstein%2Fdex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33852288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-agents","autonomous-coding","claude-agent-sdk","claude-code","electron","react","spec-kit","sqlite","typescript","vite"],"created_at":"2026-06-03T06:30:34.548Z","updated_at":"2026-06-03T06:30:36.887Z","avatar_url":"https://github.com/lukaskellerstein.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dex\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/logo/logo-medium.png\" alt=\"Dex Logo\" width=\"128\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAutonomous feature engine — fresh agents per phase, structured planning, full trace visibility.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-0.1.0-7C3AED?style=flat-square\" alt=\"Version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/electron-30-47848F?style=flat-square\u0026logo=electron\" alt=\"Electron\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/react-18-61DAFB?style=flat-square\u0026logo=react\" alt=\"React\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/typescript-strict-3178C6?style=flat-square\u0026logo=typescript\" alt=\"TypeScript\" /\u003e\n\u003c/p\u003e\n\n---\n\nDex is an Electron desktop app that automates feature implementation using the [Ralph Wiggum loop](https://ghuntley.com/ralph/) philosophy, the [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-agent-sdk), and [spec-kit](https://github.com/anthropics/claude-code/tree/main/skills). It spawns a fresh Claude Code agent per **phase** of work — each with clean context to prevent token bloat — while streaming every tool call, subagent spawn, and thinking step to a real-time trace UI.\n\n## Why Dex? The Three-Pillar Synthesis\n\nEach pillar alone has critical gaps. Dex exists because the combination eliminates what each one lacks:\n\n| Used alone | What breaks |\n|---|---|\n| **Ralph Wiggum loop** | No structured specs — the agent picks tasks from a free-form TODO, builds the wrong thing, and burns budget. No UI, no abort, no cost tracking, no failure recovery beyond \"kill the terminal.\" |\n| **Spec-kit** | No autonomous loop — specs are great but someone has to manually run each phase, check results, and decide what's next. It's a sequential human-driven workflow. |\n| **Claude Code (interactive)** | Single session degrades after ~100K tokens. No persistent memory across sessions. No structured planning. No verification beyond \"it compiles.\" One task at a time, human-driven. |\n\n**Dex fuses all three:**\n\n- **Ralph's loop** provides context isolation and self-improvement — fresh `query()` per phase, learnings persist via filesystem\n- **Spec-kit** provides structured planning — specs with acceptance criteria before any code is written, constitution-governed consistency\n- **Claude Agent SDK** provides programmatic control — typed hooks, abort, MCP browser verification, session management\n\nThe result: describe a project, clarify it into a complete plan, then walk away. Dex autonomously specs, plans, implements, verifies (including browser E2E), and recovers from failures — feature by feature, phase by phase.\n\n## Features\n\n- **Phase-level orchestration** — parses `tasks.md` specs into phases and spawns one agent per phase, keeping context focused\n- **Real-time agent trace** — streams tool calls, thinking blocks, subagent activity, and results as they happen with GSAP-animated timeline\n- **Spec-kit integration** — discovers specs in `specs/` or `.specify/specs/`, uses `/speckit-plan` and `/speckit-implement` skills\n- **Git automation** — creates branches, commits per phase, and opens PRs with cost/duration metrics\n- **Execution history** — persists all runs, phases, steps, and subagent metadata to per-project JSON for replay and analysis\n- **Checkpoints — time-travel over the pipeline** — every completed stage auto-captures a named checkpoint; go back, try again, fan out into N parallel variants, and keep the ones you want. Git under the hood, invisible to the user.\n- **Frameless desktop UI** — custom title bar, 3-column layout (sidebar → task board → agent trace), Catppuccin-inspired dark theme\n\n## Checkpoints (008)\n\nDex runs a project as a sequence of discrete stages (clarification → constitution → gap-analysis → specify → plan → tasks → implement → verify → learnings). Every completed stage automatically captures a **checkpoint** — a named save point you can rewind to later.\n\nFour user-facing verbs, no git knowledge required:\n\n- **Go back** to any past checkpoint.\n- **Try again** — re-run the current stage (or later stages) differently.\n- **Try N ways** — fork N parallel variants of the next stage, compare, pick one. Spec-only stages run in parallel worktrees, so 3 variants of `plan` take ≈ 1× the wall time, not 3×.\n- **Keep this** — accept a stage's output as the new canonical state.\n\nPlus **Record mode** (top-bar REC badge) — auto-promote every completed stage for team-shared baselines or CI fixtures.\n\nAll checkpoints travel via standard `git push --tags`; a collaborator who clones a Record-mode-produced project sees the same checkpoint tree. Power users can query the tree from the terminal:\n\n```sh\ngit log --all --grep='^\\[checkpoint:'   # every auto-capture commit\ngit tag --list 'checkpoint/*'           # every named save point\n```\n\n## Architecture\n\n```mermaid\ngraph TD\n    subgraph Renderer[\"Renderer (React 18)\"]\n        UI[3-Column UI]\n        Hooks[useOrchestrator / useProject]\n    end\n\n    subgraph Main[\"Main Process (Electron)\"]\n        IPC[IPC Handlers]\n        Preload[contextBridge → dexAPI]\n    end\n\n    subgraph Core[\"Core Engine (Pure Node.js)\"]\n        Orch[Orchestrator]\n        Parser[tasks.md Parser]\n        Git[Git Operations]\n        DB[(SQLite)]\n    end\n\n    SDK[Claude Agent SDK]\n\n    UI \u003c--\u003e|window.dexAPI| Preload\n    Preload \u003c--\u003e|ipcMain.handle / webContents.send| IPC\n    IPC --\u003e Orch\n    Orch --\u003e Parser\n    Orch --\u003e Git\n    Orch --\u003e DB\n    Orch \u003c--\u003e|\"query() + hooks\"| SDK\n\n    style Renderer fill:#1E1E2E,stroke:#7C3AED,color:#CDD6F4\n    style Main fill:#1E1E2E,stroke:#45475A,color:#CDD6F4\n    style Core fill:#1E1E2E,stroke:#45475A,color:#CDD6F4\n    style SDK fill:#7C3AED,stroke:#7C3AED,color:#FFF\n```\n\n**Data flow:** User action → React UI → IPC → Core orchestrator → Claude Agent SDK → hooks capture steps → IPC events → React hooks → UI updates (real-time streaming).\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js** \u003e= 18\n- **Claude Code CLI** installed and authenticated\n- **GitHub CLI** (`gh`) for PR creation\n\n### Installation\n\n```bash\ngit clone https://github.com/lukaskellerstein/dex.git\ncd dex\nnpm install\n```\n\n### Development\n\n```bash\n./dev-setup.sh\n```\n\nThis starts the Vite dev server (port 5500) and launches Electron with hot reload. Logs go to `/tmp/dex-logs/`.\n\n### Production Build\n\n```bash\nnpm run build:start\n```\n\n## Usage\n\n1. **Open a project** — click the folder icon to select a directory containing spec-kit specs\n2. **Select a spec** — the overview shows all discovered specs with phase/task counts\n3. **Start a run** — choose plan or build mode; the orchestrator begins phase-by-phase execution\n4. **Watch the trace** — tool calls, thinking blocks, and subagent activity stream in real-time\n5. **Review the PR** — on completion, a PR is created with commit history and cost metrics\n\n## Configuration\n\n| Setting | Description | Default |\n|---------|-------------|---------|\n| `mode` | `plan` (spec planning) or `build` (implementation) | `build` |\n| `model` | Claude model to use | SDK default |\n| `maxTurns` | Max agent turns per phase | `200` |\n| `phases` | `\"all\"` or specific phase numbers `[1, 3]` | `\"all\"` |\n\n## Project Structure\n\n```\ndex/\n├── src/\n│   ├── main/               # Electron main process\n│   │   ├── index.ts        # App lifecycle, BrowserWindow, IPC\n│   │   ├── preload.ts      # contextBridge → window.dexAPI\n│   │   └── ipc/            # Handler modules (orchestrator, project, history)\n│   ├── core/               # Orchestration engine (pure Node.js, no Electron imports)\n│   │   ├── orchestrator.ts # Phase loop, agent spawning, event emission\n│   │   ├── parser.ts       # tasks.md → Phase[] with Task[]\n│   │   ├── git.ts          # Branch creation, PR generation\n│   │   ├── database.ts     # SQLite schema \u0026 queries (runs, traces, steps)\n│   │   └── types.ts        # Shared interfaces (Phase, Task, AgentStep, etc.)\n│   └── renderer/           # React 18 UI\n│       ├── App.tsx          # Root component, view switching\n│       ├── hooks/           # useOrchestrator, useProject\n│       ├── components/\n│       │   ├── layout/      # AppShell, Topbar, WindowControls\n│       │   ├── project-overview/  # Spec cards grid\n│       │   ├── task-board/  # Phase/task views, progress bar\n│       │   └── agent-trace/ # Step timeline, tool cards, subagent pills\n│       └── styles/          # Catppuccin-inspired CSS custom properties\n├── tests/                   # Diagnostic scripts\n├── docs/                    # Logo assets\n├── dev-setup.sh             # Development environment bootstrap\n├── vite.config.ts           # Vite config (renderer build)\n├── tsconfig.json            # TypeScript (main + core)\n└── package.json\n```\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Desktop | Electron 30 (frameless BrowserWindow) |\n| UI | React 18, CSS Custom Properties, GSAP, Lucide React |\n| Engine | Pure Node.js orchestrator, Claude Agent SDK |\n| Data | better-sqlite3 (execution history) |\n| Build | Vite, TypeScript (strict mode) |\n| Git | GitHub CLI (`gh`) for automated PRs |\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukaskellerstein%2Fdex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukaskellerstein%2Fdex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukaskellerstein%2Fdex/lists"}