# QUICKSTART
[](./QUICKSTART.ja.md) [](./QUICKSTART.md) [](./QUICKSTART.zh-CN.md) [](./QUICKSTART.es.md) [-QUICKSTART-blue?style=flat-square)](./QUICKSTART.pt-BR.md) [](./QUICKSTART.ko.md) [](./QUICKSTART.fr.md) [](./QUICKSTART.de.md) [](./QUICKSTART.ru.md) [](./QUICKSTART.vi.md)
This is the shortest guide to install `cflx` for the first time, set up a project, create an OpenSpec change, and complete an implementation through the TUI.
Conflux is implemented as the `cflx` command.
## 0. Prerequisites
- Rust / Cargo is available: [Install Rust](https://rust-lang.org/tools/install/)
- [Claude Code](https://claude.com/product/claude-code) is available
- You have a git-managed project such as `~/myproject`
> Conflux is an orchestrator that launches and controls AI agents. It is not itself a coding agent.
> It can use CLIs such as [Claude Code](https://claude.com/product/claude-code), [OpenCode](https://opencode.ai/), and [Codex](https://developers.openai.com/codex/cli).
> This QUICKSTART uses Claude Code as the example.
Check the prerequisites:
```bash
cargo --version
claude --version
claude -p 'hi'
```
## 1. Install `cflx`
Install it from crates.io.
```bash
cargo install cflx
```
Verify the installation:
```bash
cflx --version
```
## 2. Prepare a project
From here on, work inside your project directory. This guide uses `~/myproject` as an example.
Conflux uses `git worktree`, so the project must be managed with git.
```bash
cd ~/myproject
```
For a new project:
```bash
mkdir -p ~/myproject
cd ~/myproject
git init
```
## 3. Install the bundled skills
Add Conflux’s bundled skills for Claude Code to the project.
```bash
cflx install-skills --claude
```
This installs `cflx-*` skills under `./.claude/skills`.
You can decide later, together with `.cflx.jsonc`, whether to commit them to Git.
## 4. Create the config file
The config file is named `.cflx.jsonc`, not `.cflx.conf`.
The quickest way is to generate it from the template.
```bash
cflx init
```
This creates `.cflx.jsonc` in the current directory.
## 5. Check `.cflx.jsonc`
At minimum, it works as long as it contains the commands for the agent you want to use.
Example Claude Code template:
```jsonc
{
"analyze_command": "claude --dangerously-skip-permissions --verbose --output-format stream-json -p {prompt}",
"apply_command": "claude --dangerously-skip-permissions --verbose --output-format stream-json -p '{prompt}'",
"archive_command": "claude --dangerously-skip-permissions --verbose --output-format stream-json -p '{prompt}'",
"acceptance_command": "claude --dangerously-skip-permissions --verbose --output-format stream-json -p '{prompt}'",
"resolve_command": "claude --dangerously-skip-permissions --verbose --output-format stream-json -p {prompt}"
}
```
For the first run, using the content generated by `cflx init` as-is is enough.
## 6. Decide what to put in Git
During the initial setup, decide whether to add these two items to Git.
- `./.claude/skills/cflx-*`
- `./.cflx.jsonc`
Recommended:
- If you want the same behavior across a team or across multiple machines, commit both
- If you will use it locally only and treat it as disposable, add both to `.gitignore`
If you are unsure, committing both is a fine default. It is easier to manage if you avoid writing secrets directly into `.cflx.jsonc`.
If you want to add both to `.gitignore`:
```bash
printf ".claude/skills/cflx-*\n.cflx.jsonc\n" >> .gitignore
git add .gitignore
git commit -m 'Ignore Conflux local setup files'
```
If you want to add both to the repository:
```bash
git add .claude/skills/cflx-* .cflx.jsonc
git commit -m 'Add Conflux setup files'
```
## 7. Create your first change proposal
Conflux processes OpenSpec changes.
Even if you are not familiar with OpenSpec yet, that is fine. The bundled skills are already installed, so you can have Claude Code create a proposal.
For example:
```text
/cflx-proposal display hello world in python
```
This generates a change directory such as `openspec/changes/add-hello-world/`, and it includes at least the following two files.
- `proposal.md`: what to change
- `tasks.md`: what to implement
For the shortest path, it is enough to quickly review these two files and commit them as-is if there are no problems.
Checkpoints:
- The content of `proposal.md` matches the change you want to make
- The implementation tasks in `tasks.md` are complete and not excessive
- No unrelated changes are mixed in
If needed, edit the proposal or tasks, then commit them once the content looks good.
```bash
git add openspec/changes/add-hello-world
git commit -m 'proposal: add-hello-world'
```
The detailed structure looks like this.
```text
openspec
└── changes
└── add-hello-world
├── proposal.md
├── specs
│ └── hello-world
│ └── spec.md
└── tasks.md
```
## 8. Make sure the workspace is clean
Before launching the TUI, make sure the working tree is clean.
```bash
git status
```
If it is clean, it will look like this.
```text
On branch main
nothing to commit, working tree clean
```
## 9. Launch the TUI
Start Conflux in TUI mode.
```bash
cflx
```
You will see a screen like this.
## 10. Run it from the TUI
Basic controls:
- `↑/↓` or `j/k`: select a change
- `Space`: mark it for execution
- `F5`: start execution
- `Ctrl+C`: exit
Shortest flow:
1. Launch `cflx`
2. Move to the change you want to process
3. Press `Space` to select it
4. Press `F5` to run it
In this example, there is only one change, so run it with `Space` → `F5`.
Conflux automatically runs the following loop.
- apply
- accept
- archive
- resolve / merge
Once it reaches `merged`, it is complete.
## 11. Check the result
Confirm that the implementation is in place.
```bash
tree
cat hello.py
```
Example:
```text
.
├── hello.py
└── openspec
├── changes
└── specs
```
```python
print("hello world")
```
The OpenSpec side is also updated.
```bash
tree openspec -L 10
```
Example:
```text
openspec
├── changes
│ └── archive
│ └── add-hello-world
│ ├── proposal.md
│ ├── specs
│ │ └── hello-world
│ │ └── spec.md
│ └── tasks.md
└── specs
└── hello-world
└── spec.md
```
You can see that the change proposal has been archived and that the final specification has been promoted to `openspec/specs`.
For example:
```bash
cat openspec/specs/hello-world/spec.md
```
```markdown
## Requirements
### Requirement: hello-world-output
The program must print "hello world" to standard output when executed.
#### Scenario: default-execution
**Given**: The user has Python installed
**When**: The user runs `python hello.py`
**Then**: The program prints `hello world` to stdout and exits with code 0
```
With this spec, Conflux can quickly understand the software’s behavior and proceed more reliably with the next change.
---
This completes the simplest implementation cycle.
This QUICKSTART stops at getting your first run working in the shortest possible way.
In actual use, you may need more detailed techniques such as refining proposals, tuning settings, running in parallel, and troubleshooting.
For the next steps, see the README or `cflx --help`.
For feedback or questions, please open a [GitHub Issue](https://github.com/tumf/conflux/issues) or mention `@tumf` on X.