Frequently asked questions

The questions that come up most often. For the canonical references see the install walkthrough, the configuration reference, and the reviewer pipeline overview.

What is Synthex?

Synthex is Claude-first agentic software delivery: a reusable collection of specialist agents and workflows that take software from a messy idea to a peer-reviewed plan to production-ready, parallel-executed code. It began as a Claude Code plugin and, as of version 1.0, is also distributed through Agent Skills for Codex CLI, Grok, Gemini CLI, OpenCode, and other compatible harnesses. The behavioral source is plain Markdown and YAML, distributed through the LumenAI marketplace at https://github.com/bluminal/lumenai, and inspectable end-to-end.

How is Synthex different from regular Claude Code?

Claude Code is Synthex's original and primary runtime, with native slash commands, plugin agents, hooks, and loops. Synthex prescribes how specialist workflows compose: a five-phase lifecycle (Discover → Plan → Build → Ship → Learn), parallel git-worktree execution, and peer-reviewer gates between plan and merge. The same canonical workflows are now available in other Agent Skills-compatible harnesses, although each host supplies its own command interface, permissions, and delegation features. Without Synthex you have a powerful generalist tool; with it you have a virtual engineering team that follows a structured delivery process.

Do I need to be a developer to use Synthex?

Yes — Synthex is built for engineering teams and engineers acting solo. The output is a git repository with peer-reviewed code, an implementation plan, and architecture decision records. You do not have to write every line yourself, but you do need to understand what you are shipping: approve plans, sign off on diffs, run the tests, deploy the result. If you are not comfortable doing those things, Synthex is the wrong tool — start with Claude Code's general assistant mode instead.

How do I install Synthex?

Claude Code: register the LumenAI marketplace with `/plugin marketplace add bluminal/lumenai`, install with `/plugin install synthex`, then run `/synthex:init` in your project. Codex CLI and Grok have native marketplace installs (`grok plugin marketplace add bluminal/lumenai`, then `grok plugin install synthex --trust` and `grok plugin enable synthex`). Gemini CLI and OpenCode use the shared Agent Skills bundle. See https://slashsynthex.com/docs/agent-compatibility for copyable instructions for each harness. Synthex has no separate SDK, account, or API key; your selected harness supplies its own model access.

Where does configuration live?

Project-level configuration lives at `.synthex/config.yaml` and overrides the plugin's shipped defaults. Anything you don't specify falls back, so the file only needs to contain values you actually want to override. The Configuration reference page documents every key and the resolution order: plugin defaults → project file → per-command overrides → per-invocation parameters.

What does parallel execution actually do?

Synthex's Build phase runs multiple plan tasks at the same time, each in its own isolated git worktree, each delegated to its own Tech Lead agent. A three-task batch produces three separate branches developed simultaneously; each goes through the reviewer gates independently; the orchestrator fast-forward-merges them into `main` one at a time as they pass. The isolation invariant — two concurrent tasks never share a working tree — is what makes this safe. See the Parallel execution concept page for the full picture.

How many tasks should I run in parallel?

The conservative default is 3 concurrent tasks (configurable via `next_priority.concurrent_tasks`). Most laptops handle ~75% of CPU cores comfortably (Aggressive). Going beyond that (Yolo mode, one task per core) maximises throughput but inflates `[H]` review queues — you'll be staring at a lot of pending approvals. The right value depends on your patience for review more than your machine's capacity.

Can I use models other than Claude for review?

Yes. The `code_review` and `implementation_plan` config blocks support a multi-model branch where the same artifact is sent to Claude and to one or more external CLI adapters running other LLM families. The Multi-Model Review Orchestrator fans them all out in parallel; the Findings Consolidator merges the outputs. Different model families have different blind spots — running multiple in parallel catches errors any single family would miss.

How do I contribute an agent or command back to Synthex?

Open a pull request against the LumenAI repository at https://github.com/bluminal/lumenai. The plugin source lives at `plugins/synthex/`. The Authoring agents and Authoring commands docs cover the conventions Synthex itself follows. Project-specific extensions — agents or commands that shouldn't go upstream — work as their own plugin alongside Synthex; the marketplace is just a Git repository so you can host one anywhere.

Where do I file bugs or feature requests?

Open an issue on the LumenAI repository at https://github.com/bluminal/lumenai/issues. Include the harness, agent or command name, your `.synthex/config.yaml` (with secrets redacted), and the expected versus actual behavior. For a harness issue, file with its maintainer: Claude Code at https://github.com/anthropics/claude-code/issues, Codex through OpenAI support, Gemini CLI at its GitHub repository, or OpenCode at its GitHub repository.