Getting started

This guide is the shortest path from zero setup to a first useful Conflux run.

Prerequisites

Before you install Conflux, confirm three things:

• Rust and Cargo are available.
• You already have a git-managed project, or you can create one.
• At least one external coding agent CLI is installed and authenticated.

cargo --version claude --version claude -p 'hi'

If you prefer another agent, replace the claude checks with the CLI you actually plan to use.

Install the CLI

Use crates.io unless you are intentionally testing a local build.

cargo install cflx cflx --version

Prepare a project directory

Conflux uses git worktree, so the target project must be under git.

mkdir -p ~/myproject cd ~/myproject git init

If you already have a repository, switch into it instead.

Install bundled skills

The first practical setup step is to install the bundled cflx-* skills for your coding agent.

cflx install-skills --claude

This places the skills under ./.claude/skills/ for the current project.

Generate the config file

Conflux uses .cflx.jsonc.

cflx init

The generated template is usually enough for the first run. If you need another template, use cflx init --template codex or cflx init --template opencode.

Create the first change proposal

Conflux works on OpenSpec changes. A minimal way to create one is to invoke the proposal skill from your coding agent session.

/cflx-proposal display hello world in python

Review the generated change directory and make sure these files look sensible:

• proposal.md
• tasks.md
• specs/.../spec.md

When the proposal is acceptable, commit it.

git add openspec/changes/add-hello-world git commit -m 'proposal:
add-hello-world'

Run Conflux

Make sure the working tree is clean first.

git status

Then choose one of these modes:

In the TUI, the shortest path is:

1. Select the change with arrow keys or j/k.
2. Press Space to mark it.
3. Press F5 to start execution.

What success looks like

A successful first run usually means all of these are true:

• A change moved through apply and acceptance without leaving the repository in a confusing state.
• You can inspect logs and understand what happened.
• You know whether the generated diff is ready to merge or needs follow-up work.

Common first-run problems

The agent command fails immediately

Check that the CLI works outside Conflux first. If claude -p 'hi' or the equivalent direct command fails, fix that before debugging Conflux.

The proposal is too large

Split the work into smaller OpenSpec changes. Conflux performs best when a change is clear and bounded.

The repository is dirty before execution

Clean the working tree before you run. Unrelated local edits make it harder to trust the result.