triflux

[English](README.md) | [한국어](README.ko.md)

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
    <img alt="triflux" src="docs/assets/logo-dark.svg" width="200">
  </picture>
</p>

<h3 align="center">CLI-first multi-model orchestration for Claude Code, Codex, and Antigravity</h3>

<p align="center">
  <a href="https://www.npmjs.com/package/triflux"><img src="https://img.shields.io/npm/v/triflux?style=flat-square&color=FFAF00&label=npm" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/triflux"><img src="https://img.shields.io/npm/dm/triflux?style=flat-square&color=F5C242" alt="npm downloads"></a>
  <a href="https://github.com/tellang/triflux/stargazers"><img src="https://img.shields.io/github/stars/tellang/triflux?style=flat-square&color=FFAF00" alt="GitHub stars"></a>
  <img src="https://img.shields.io/badge/node-%3E%3D22-374151?style=flat-square" alt="Node >= 22">
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-374151?style=flat-square" alt="License: MIT"></a>
</p>

triflux is a Claude Code plugin and npm CLI that routes coding work across Claude, Codex,
and Antigravity. You describe the task once with `/tfx-auto`; triflux picks the CLI lane
(Codex by default), runs it through managed routes instead of ad-hoc shell commands, and
can fan the work out to parallel workers, live Claude↔Codex sessions, or remote
hosts. Parallel code changes use separate worktrees and one session per worktree.
The `tfx` shell CLI covers setup, diagnostics,
and team orchestration.

## Install

```bash
npm install -g triflux   # postinstall runs the setup script
tfx doctor               # check CLIs, tmux, MCP, profiles, skills
```

npm 12 and newer block install scripts by default. Allow the setup script:

```bash
npm i -g triflux --allow-scripts=triflux
```

Setup registers the `triflux` marketplace and prints a mods installation hint. To install
usage bands and subagent effort enforcement (Claude Code 2.1.287 or newer):

```bash
tfx setup --mods
```

Or install the Claude Code plugin from this repository's marketplace:

```bash
claude plugin marketplace add tellang/triflux
claude plugin install triflux@triflux
```

`tfx doctor --fix` repairs common drift; `tfx doctor --json` is for automation.

## First steps

```text
/tfx-auto "fix the failing auth tests"
/tfx-auto "review this change for trust-boundary issues" --mode consensus
/tfx-auto "finish the migration and verify it" --mode deep --retry ralph --max-iterations 10
```

## Skills

Skills you invoke directly:

| Skill | Use |
| --- | --- |
| `/tfx-auto` | Front door for implementing, fixing, reviewing, and parallel work. Behavior is set by flags (below). |
| `/tfx-live` | Live Claude↔Codex sessions: `start`/`ask`/`wait`/`stop`, `peer` relay, `list-sessions`. |
| `/tfx-lead` | Lead role for running several Claude/Codex sessions: roles and models, briefs, cross review, merge and release coordination. |
| `/tfx-remote` | Remote Claude Code sessions over SSH: start, list, reattach, send, readiness probe, monitor, stop. |
| `/tfx-setup` | Setup: file sync, HUD, Codex and Antigravity profiles, MCP. `tfx setup --mods` installs mods. |
| `/tfx-doctor` | Diagnose and repair. |
| `/tfx-ship` | triflux release flow (maintainers). |
| `/tfx-wt` | Windows Terminal tabs and panes. `tfx setup` installs it on Windows only. |

Internal lanes (marked `internal: true`; other skills and the router call them, but you can name them explicitly):

| Skill | Use |
| --- | --- |
| `tfx-harness` | Meta routing: returns which skill or path fits a request, without running it. |
| `tfx-review` | Code review verdict (`--quick` for a lighter pass). |
| `tfx-research` | Web research with cross-checked sources (`--quick`, `--auto`, `--depth`). |

Use superpowers `writing-plans` for implementation plans, host `deep-interview` for requirements,
and Claude Code’s built-in `/goal` for goals. Use `/tfx-auto --mode deep` for multi-model planning
and execution. Manage Codex profiles directly in `~/.codex/<profile>.config.toml`.

## `/tfx-auto` flags

| Flag | Values | Effect |
| --- | --- | --- |
| `--mode` | `quick` (default), `deep`, `consensus`, `live` | `deep` = plan → execute → verify loop; `consensus` = multi-CLI agreement; `live` = hand off to `tfx-live peer` |
| `--shape` | `consensus`, `debate`, `panel` | Output shape for `--mode consensus` |
| `--cli` | `auto`, `codex`, `antigravity`, `claude` | Force a CLI lane |
| `--cli-set` | `triad`, `no-antigravity`, `custom` | Consensus participants |
| `--parallel` | `1`, `N` | `N` = local workers (`tfx multi`) |
| `--retry` | `0`, `1` (default), `ralph`, `auto-escalate` | `ralph` = retry state machine with stuck detection; `auto-escalate` = move up the model chain |
| `--max-iterations` | `N` | Cap for `ralph` / `auto-escalate` (`0` = unlimited) |

... (truncated)