Getting started

Choose the coding agent you use below. Every supported harness loads the same Synthex workflows: a messy idea becomes a peer-reviewed implementation plan and parallel-executed, tested code. Claude Code is Synthex's home and has the richest native experience; the other harnesses use the shared Agent Skills layer.

#1. Install Synthex

#Claude Code

Run these commands inside Claude Code:

/plugin marketplace add bluminal/lumenai
/plugin install synthex

Claude Code provides Synthex's native plugin experience: namespaced slash commands, plugin agents, hooks, and native looping.

#Codex CLI

Run these commands in a terminal, then start a new Codex session:

codex plugin marketplace add bluminal/lumenai
codex plugin add synthex@lumenai

Codex exposes the Synthex workflows and specialists as skills. Invoke one with $, such as $review-code or $architect, or select it from /skills.

#Grok

Run these commands in a terminal, then start a new Grok session:

grok plugin marketplace add bluminal/lumenai
grok plugin install synthex --trust

Grok exposes the Synthex workflows and specialists as skills. Invoke one as /synthex:review-code or /synthex:architect. When the name is unambiguous, /review-code works too.

#Gemini CLI

Gemini CLI installs Synthex's generated Agent Skills bundle (portable-skills/) as workspace skills, with the sibling agents/, commands/, config/, scripts/, and docs/ directories alongside so each skill can load its canonical source. From the project root:

git clone --depth 1 --filter=blob:none --sparse https://github.com/bluminal/lumenai.git .synthex-source
git -C .synthex-source sparse-checkout set plugins/synthex
mkdir -p .gemini
cp -R .synthex-source/plugins/synthex/{agents,commands,config,scripts,docs} .gemini/
for skill in .synthex-source/plugins/synthex/portable-skills/*; do
  gemini skills install "$skill" --scope workspace --consent
done

Use gemini skills list to confirm the inventory. If .gemini/ already contains project-managed files, merge the copied directories deliberately rather than overwriting them.

#OpenCode

Copy the bundle and its sibling directories into the project:

git clone --depth 1 --filter=blob:none --sparse https://github.com/bluminal/lumenai.git .synthex-source
git -C .synthex-source sparse-checkout set plugins/synthex
mkdir -p .agents
cp -R .synthex-source/plugins/synthex/{portable-skills,agents,commands,config,scripts,docs} .agents/

OpenCode's built-in discovery only scans .claude/skills/ and .agents/skills/, so point it at the bundle with an opencode.json at the project root:

{
  "$schema": "https://opencode.ai/config.json",
  "skills": { "paths": [".agents/portable-skills"] }
}

If .agents/ already contains project-managed files, merge the copied directories deliberately rather than overwriting them.

#Hermes Agent

Hermes can't install a skill from a local path, so place the whole plugin tree in the project and link its skills directory:

cp -R path/to/plugins/synthex <project>/.agents/synthex
ln -s .agents/synthex/portable-skills <project>/.agents/skills
cd <project> && hermes skills trust

Keep commands/ and agents/ outside every skill folder, as this layout does; Hermes quarantines skills that contain them. hermes skills trust is per checkout, so run it again after re-cloning.

#Cursor

Synthex ships Cursor Task agent wrappers in the plugin's cursor-agents/ directory. Copy or symlink it to your project's .cursor/agents/ so Synthex roles appear as named Cursor subagents. On Cursor, /synthex:next-priority/synthex:next-priority can also run parallel tasks as cloud subagents; see Cloud agents.

#Upgrading an older manual install

Gemini CLI and OpenCode installs made before the bundle was renamed from skills/ to portable-skills/ point at a directory that no longer exists. On Gemini CLI, uninstall each old skill (gemini skills uninstall <id> --scope workspace) and reinstall from portable-skills/. On OpenCode, re-copy the bundle and update opencode.json as above; without that, OpenCode silently stops seeing Synthex skills.

#2. Initialize your project

From the project you want Synthex to manage, run the init workflow:

This scaffolds the standard project layout:

• .synthex/config.yaml — project configuration (review loops, concurrent task count, multi-model review opt-in)
• docs/reqs/ — product requirements documents
• docs/plans/ — implementation plans
• docs/specs/ — technical specifications
• docs/specs/decisions/ — Architecture Decision Records (ADRs)
• docs/specs/rfcs/ — Requests for Comments
• docs/runbooks/ — operational runbooks
• docs/retros/ — retrospective documents

In Claude Code, /synthex:init also adds .claude/worktrees/ and .synthex/config.local.yaml (your personal overrides for this repo; see where settings can live) to your .gitignore and asks you to pick a concurrent_tasks value: Yolo (every CPU core), Aggressive (75% of cores), or the conservative default of 3. This initialization is optional; the workflows have sensible defaults if you want to start without a project config.

#3. Describe what you want, then ship it

Write a PRD at docs/reqs/main.md. The fastest way is conversational:

This pulls in the Product Manager agent. PM interviews you, drafts the plan, runs it through a peer review loop with the Architect, Design System Agent, and Tech Lead, then writes the finalized plan to docs/plans/main.md.

Then execute:

This identifies the next batch of unblocked, non-overlapping tasks (up to your concurrent_tasks limit), spins up a git worktree per task, delegates each to a Tech Lead instance, and merges the results back as they pass review. Run it repeatedly — once per delivery batch — until the plan is done.

#What happens behind the scenes

Every plan task carries a typed acceptance criterion:

Code reviews run automatically before any merge: code review + security review as mandatory gates, with optional performance, design-system, and reliability reviewers configurable per project.

#Next

• The full plan — read the plugin README for the complete command + agent reference
• Source — the plugin's markdown-and-YAML source on GitHub
• Agent compatibility — install the same workflows in Codex, Grok, Gemini CLI, OpenCode, or another Agent Skills host