Devkit

A deterministic development harness for AI agents. The MCP engine controls workflow execution (step ordering, gates, loops, branches). The agent handles creativity. Every step is tracked, measured, and auditable.

Works with Claude Code as the original full-enforcement host. Other host adapters can use the same MCP engine and workflows by registering bin/devkit mcp; the Codex adapter is distributed separately by devkit-codex. Optionally adds Codex and Gemini for multi-agent consensus.

Install

Claude Code

1. Devkit (required)

/plugin marketplace add 5uck1ess/marketplace
/plugin install devkit@5uck1ess-plugins

Auto-updates are enabled by default. Devkit updates itself when you restart Claude Code.

2. Multi-agent plugins (optional)

These enable tri:* commands (tri-review, tri-debug, tri-security, etc.) to run Claude + Codex + Gemini in parallel.

# Codex plugin
/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex

# Gemini plugin
/plugin marketplace add abiswas97/gemini-plugin-cc
/plugin install gemini@abiswas97-gemini

If plugins aren't installed, the CLI fallbacks work too:

brew install codex gemini-cli

3. Companion plugins (optional)

These handle concerns devkit doesn't — methodology, specialized reviews, and context management. No overlap.

# Methodology — brainstorming, planning, TDD, verification, debugging
/plugin install superpowers@claude-plugins-official

# Specialized review agents — comment accuracy, type design, silent failures
/plugin install pr-review-toolkit@claude-plugins-official

# Deep feature exploration — parallel codebase analysis, architecture proposals
/plugin install feature-dev@claude-plugins-official

# Quick commits — /commit, /commit-push-pr, /clean_gone
/plugin install commit-commands@claude-plugins-official

# Hook creation — markdown rules, hot reload, conversation analysis
/plugin install hookify@claude-plugins-official

# Skill development — eval/benchmark framework, blind A/B testing
/plugin install skill-creator@claude-plugins-official

# Context window management — sandboxes large outputs, 98% token savings
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Codex

Codex support lives in the separate devkit-codex adapter. That adapter installs Codex-specific hooks/config and points Codex at this repo's MCP server (bin/devkit mcp). This repo remains the core workflow engine and shared workflow/skill source of truth.

Manual MCP registration shape for host adapters:

[mcp_servers.devkit]
command = "/absolute/path/to/devkit/bin/devkit"
args = ["mcp"]

Optional tools

brew install rtk       # Token optimization (60-90% savings on Bash output)
brew install ast-grep  # AST-based repo mapping (used by onboard skill)

# Browser automation — enables scrape (JS-rendered), screenshot, and browser skills
npx playwright install chromium

Playwright (optional) enables three skills: enhanced scrape for JS-heavy sites, screenshot for page captures, and browser for full automation (clicking, form filling, multi-step flows, codegen). Free and local — no API keys. Install only the browsers you need (chromium is ~170MB).

Verify

/health

This shows which CLIs are installed, which agents are available, and which commands are ready.

Quick Start

# These activate automatically — just ask naturally:
# "write tests for src/parser.ts"
# "generate a changelog"
# "help me understand this codebase"
# "research the best auth library for Node"

# Slash commands for complex workflows:
/tri-review                   # Multi-agent code review
# Or just describe: "submit a PR", "ship this" → pr-ready skill auto-activates

Local models (optional)

devkit can dispatch fast-tier work (doc generation, changelogs, summarization, test stubs) to any OpenAI-compatible local inference server. Cloud tiers — Claude, Codex, Gemini — still handle tri-review, architecture planning, and security review.

Environment variables

Default ports by stack

Port 8080 is the llama.cpp convention; llama-swap reuses it since it fronts llama-server processes.

Examples

Single model, no router (llama-server, LM Studio, vLLM, SGLang):

export DEVKIT_LOCAL_ENABLED=1
export DEVKIT_LOCAL_ENDPOINT=http://<host>:<port>/v1
export DEVKIT_LOCAL_MODEL=<model-loaded-at-launch>
devkit-engine probe-local

Multi-model via router (Ollama, llama-swap, LocalAI — LocalAI supports either mode depending on how it's configured):

export DEVKIT_LOCAL_ENABLED=1
export DEVKIT_LOCAL_ENDPOINT=http://<host>:<port>/v1
export DEVKIT_LOCAL_MODEL=<name-the-router-recognizes>
devkit-engine probe-local

Verifying the setup

devkit-engine probe-local calls $DEVKIT_LOCAL_ENDPOINT/models, reports reachability and latency, and checks whether your configured model is present in the server's model list. Exit 0 on healthy (or when the local runner is disabled), 1 otherwise. Add --json for structured output.

Limits

• Fast tier only — local models have higher tool-call error rates than cloud tiers, so tri-review / architecture / security still go to the cloud.
• No function-calling (plain /v1/chat/completions only).
• No streaming.

How It Works

Devkit runs as an MCP server inside the host agent. Under Claude Code it is packaged as a plugin; other adapters register bin/devkit mcp through their host-specific MCP config. When a workflow starts, the engine takes control:

devkit_start("research", "best Go testing frameworks")
  → Engine creates session, returns Step 1 + condensed principles
  → Host agent executes the step using standard tools
  → Host agent calls devkit_advance(session_id)
  → Engine validates, records output, returns Step 2
  → ...repeat until WORKFLOW COMPLETE

Claude Code enforcement (runs automatically):
  PreToolUse hook → blocks out-of-step actions during command steps
  Stop hook → prevents session end during active workflows

External adapters:
  Register the same MCP server and provide host-specific hooks/guardrails.

Why MCP? The host agent can't skip steps because the engine controls what comes next. The engine holds state — the agent doesn't self-report workflow position. Claude Code additionally blocks invalid tools through hooks; other hosts can add equivalent adapter-side guardrails while still relying on engine-owned command steps.

Workflows

All 22 YAML workflows are invoked via the MCP engine. Every workflow has a trigger skill so natural-language keywords dispatch deterministically — saying "build a feature", "fix this bug", "tri review", or "deep research X" fires the matching skill, which calls devkit_start and the engine takes over.

Every workflow is also a tab-completable slash command. Bare names work (/feature, /bugfix, /tri-review, /health, /setup-rules); the fully-qualified /devkit:<name> form also works if you want to disambiguate from another plugin or a Claude Code built-in.

Skills

Skills activate automatically based on context. No slash command needed. Every workflow has a matching trigger skill — saying the keyword dispatches to the engine which then enforces every step.

Workflow trigger skills (dispatch to engine-enforced workflows):

Other skills (tools, meta-orchestration, content):

Coding principles (clean-code, dry, yagni, dont-reinvent, executing, stuck, scratchpad) are injected as condensed rules (~120 tokens) per workflow step — not loaded as full skill files.

Hooks

12 hooks across 4 lifecycle events. All installed automatically with the plugin.

Agents

All agents run in worktree isolation.

Coding Rules

Language-specific rules that auto-activate when Claude reads matching files. Installed to ~/.claude/rules/ — rules guide how to write, hooks catch what you missed. Other host adapters should load the matching files from resources/rules/.

/setup-rules

Architecture

MCP Server (bin/devkit mcp — auto-started by plugin)
  ├── bin/devkit = POSIX shell wrapper (committed to git)
  │   └── On first run, downloads matching release asset from GitHub,
  │       verifies SHA256, caches as bin/devkit-engine-v<ver>-<os>-<arch>,
  │       then execs it. Local dev builds (make install-plugin) are used
  │       directly via the fast path.
  ├── Tools: devkit_start, devkit_advance, devkit_status, devkit_list
  ├── State: session.json (hot, <50ms reads) + SQLite (cold history)
  ├── Parse YAML → validate steps, branches, budget
  ├── Walk steps:
  │   ├── Command steps → engine executes shell directly ($0 cost)
  │   │   Values passed via $DEVKIT_INPUT / $DEVKIT_OUT_<step_id>
  │   │   env vars — never interpolated into the command string.
  │   ├── Prompt steps → host agent works, calls devkit_advance when done
  │   ├── Loop with gate → run, verify, keep or revert
  │   ├── Branch → case-insensitive word-boundary match → goto
  │   └── Parallel → host subagent/external runner dispatch
  └── Principles injected per step (~120 tokens, not full skill files)

Enforcement:
  ├── MCP state — host agent can only progress by calling devkit_advance
  ├── Claude Code: PreToolUse hook exits 2 to block invalid tools
  ├── Claude Code: Stop hook blocks session end during active workflows
  └── External adapters: host-specific hooks/proxies enforce what their host exposes

Terminal usage (devkit workflow <name> "<description>"):
  ├── Subprocess runners for Codex/Gemini CLI
  └── In-process HTTP runner for Ollama/llama-server/vLLM (opt-in via DEVKIT_LOCAL_ENABLED=1)

Repository Structure

devkit/
├── commands/          # Legacy (references/ only); new entry points go in skills/
├── skills/            # 39 skills (workflow triggers, principles, tools, utilities) + _principles.yml
├── agents/            # 6 agents (reviewer, researcher, improver, ...)
├── hooks/             # 12 hooks (safety, security, quality gates, workflow enforcement)
├── workflows/         # 22 YAML workflow definitions
├── resources/rules/   # Language-specific coding rules
├── src/               # Go engine + MCP server
│   ├── mcp/           # MCP server (tools, principles loader, session management)
│   ├── engine/        # YAML workflow engine (parser, executor, tests)
│   ├── runners/       # Claude/Codex/Gemini CLI interfaces + local HTTP runner (Ollama-compat, opt-in)
│   ├── lib/           # DB, git, metrics, session state, reporting
│   └── cmd/           # CLI entry points (including `devkit mcp`)
├── bin/               # devkit wrapper (committed) + downloaded engine binaries (gitignored)
└── .github/workflows/ # CI (build+test+vet) + auto-release (6 platforms)

Support

If devkit saved you time: