English | 한국어

Tri-CLI Orchestration with Consensus Intelligence

Route tasks across Claude + Codex + Gemini — 13 public core skills, natural language routing,
cross-model review, and reflexion-based adaptive learning.

_{+ 11 compatibility aliases}

Quick Start · Core Engine · Killer Skills · All 13 Skills · Deep vs Light · Architecture · Security

---

What is triflux?

Most AI coding tools talk to one model. triflux talks to three — and makes them argue.

triflux is not a collection of skills. It is a multi-model parallel orchestration harness. The 13 public core skills, 11 compatibility aliases, and internal routed helpers are what it does. The harness — consensus engine, message bus, router, and security guard — is what makes it different.

Every Deep skill runs Claude, Codex, and Gemini independently (no cross-visibility), then cross-validates their findings. Only consensus-verified results survive. The result: 87% fewer false positives compared to single-model review.

Phase 4 folds the legacy surface into one front door: tfx-auto with flag-based routing. Old skill names still work as thin aliases.

You don't need to memorize commands. Say what you want in natural language — triflux routes to the right skill automatically:

"review this"          → /tfx-review       (Deep by default — 3-party consensus)
"review this --quick"  → /tfx-review --quick  (quick opt-out)
"리뷰해줘"              → /tfx-review       (Korean works too)
"제대로 리뷰해"          → /tfx-review       (depth modifier detected)

---

Quick Start

Claude Code (recommended) — run inside a Claude Code session:

/plugin marketplace add tellang/triflux
/plugin install triflux@tellang

npm:

npm install -g triflux

Then run tfx setup to configure your environment.

Use

# 3-party consensus — three models argue, only consensus survives
/tfx-review
/tfx-plan "migrate REST to GraphQL"

# Swarm — split PRD into shards, parallel worktree execution
/tfx-swarm

# Team — Claude + Codex + Gemini on parallel tasks
/tfx-multi "refactor auth + update UI + add tests"

# Persist — or call the front door directly
/tfx-auto "implement full auth flow with tests" --retry ralph

# Remote — single front door for setup, spawn, attach, resume
/tfx-remote spawn ryzen5-7600 "run security review"

Note: Deep skills require psmux (or tmux), triflux Hub, Codex CLI, and Gemini CLI for full Tri-CLI consensus. Without these, skills automatically degrade to Claude-only mode. Run tfx doctor to check your environment.

State Snapshots

Hub startup also takes a best-effort daily snapshot of selected ~/.codex/ and ~/.gemini/ state into references/codex-snapshots/ and references/gemini-snapshots/. Snapshot archives are rolling backups capped at 10 files per tool and are ignored by git.

Manual commands:

npm run snapshot:codex
npm run snapshot:gemini
npm run snapshot:all

---

Core Engine

The infrastructure that makes triflux triflux. If any of these break, everything breaks.

Tri-CLI Consensus

The core innovation. Instead of trusting a single model, every Deep skill runs:

Phase 1: Independent Analysis (Anti-Herding)
  ├─ Claude Opus  → Analysis A  (isolated, no cross-visibility)
  ├─ Codex CLI    → Analysis B  (isolated, no cross-visibility)
  └─ Gemini CLI   → Analysis C  (isolated, no cross-visibility)

Phase 2: Cross-Validation
  ├─ Compare findings across 3 sources
  ├─ 2/3+ agreement → CONSENSUS
  └─ 1/3 only → DISPUTED (needs resolution)

Phase 3: Resolution (if consensus < 70%)
  ├─ Each CLI reviews opposing arguments
  ├─ Accept or rebut with evidence
  └─ Unresolved → user decides

Hub — Singleton MCP Message Bus

triflux Hub runs as a singleton daemon per machine. A filesystem lock prevents duplicate instances.

Local agents ──→ Named Pipe (NDJSON, sub-ms latency) ──→ Hub
Remote/Dashboard ──→ HTTP/REST ──────────────────────→ Hub

The bridge client tries Named Pipe first and falls back to HTTP automatically. Sessions auto-expire after 30 minutes, and the Hub self-terminates when idle. Run tfx hub ensure to guarantee the Hub is alive from any context.

Router — Natural Language Skill Mapping

tfx-auto is the unified entry point. Natural language input → keyword detection → skill routing → CLI dispatch. Depth modifiers ("thoroughly", "제대로") auto-escalate Light skills to Deep. The router handles Korean and English natively.

tfx-auto flags now express all legacy behaviors:

• --retry ralph / --retry auto-escalate (true state machine, Phase 3)
• --lead codex / --no-claude-native (Codex-led pipeline, Phase 3)
• --shape debate|panel|consensus (ensemble fold, Phase 4)

Guard — Security Perimeter

Two layers that enforce the safety boundary:

• headless-guard: Blocks direct codex exec / gemini -y outside tfx skills. Wrapper bypass, pipe bypass, env escape vectors all covered.
• safety-guard: SSH bash-syntax forwarding prevention, injection-safe shell execution.

Every CLI invocation flows through the guard layer. No exceptions.

Reflexion Adaptive Learning

Errors become knowledge automatically. The Reflexion Engine runs a closed-loop learning pipeline:

safety-guard blocks command
  → error normalized (paths, timestamps, UUIDs stripped)
  → pattern stored in pending-penalties
  → promoted to adaptive rule (Bayesian confidence scoring)
  → injected into CLAUDE.md when confidence > threshold

Three-tier memory:
  Tier 1 (Session)   → cleared on session end
  Tier 2 (Project)   → decays -0.2 confidence per 5 unobserved sessions
  Tier 3 (Permanent) → auto-injected into CLAUDE.md as machine-readable rules

A blocked command in Session 1 becomes a proactive warning in Session 2 and eventually a permanent instruction. Your AI agent literally gets smarter over time.

Pipeline Quality Gates

Every Deep task runs through a 10-phase state machine with quality gates:

plan → PRD → confidence gate → execute → deslop → verify → selfcheck → complete
                                                              ↓
                                                          fix (max 3) → retry

• Confidence Gate (pre-execution): 5 weighted criteria must score >= 90% before execution starts
• Hallucination Detection (post-execution): 7 regex patterns catch AI claims without evidence:
  • "tests pass" without test output
  • "performance improved" without benchmarks
  • "backward compatible" without verification
  • "no changes needed" when diff exists
• Bounded loops: Fix attempts capped at 3, ralph iterations at 10. State persists in SQLite for crash recovery.

---

Killer Skills

These are why you use triflux. Each one depends on the Core Engine above.

Multi-CLI Team Orchestration — tfx-multi (alias for tfx-auto --parallel N)

Run Claude + Codex + Gemini as a coordinated team on parallel tasks. Phase 4 keeps tfx-multi as a compatibility alias while tfx-auto --parallel N becomes the canonical surface.

/tfx-multi "refactor auth + update UI + add tests"
/tfx-multi --agents codex,gemini "frontend + backend"

Multi-Machine x Multi-Model Swarm — tfx-swarm

One PRD, multiple machines, multiple models. Write a PRD with agent: and host: per shard, and triflux distributes work across local and remote machines using Claude + Codex + Gemini in parallel.

/tfx-swarm    # select PRDs, choose remote/model config, launch workers

Example PRD shard:

## Shard: security-audit
- agent: claude
- host: ryzen5-7600
- critical: true
- files: src/security.mjs
- prompt: Security vulnerability audit

Each shard gets its own git worktree, file-lease enforcement prevents conflicts, and results merge automatically in dependency order. Critical shards run on two different models for redundant verification.

Remote Sessions — tfx-remote

tfx-remote is the consolidated remote surface. Setup, spawn, attach, send, resume, probe, and rules now live behind one command family. tfx-remote-spawn remains as a thin alias during the transition.

/tfx-remote spawn ryzen5-7600 "run security review"
/tfx-remote list           # see active remote sessions

Persistence Loop — tfx-persist (alias for tfx-auto --retry ralph)

"Don't stop until it's done." Phase 3 turns --retry ralph into the real persistence state machine, with --max-iterations N and the four-step DEFAULT_ESCALATION_CHAIN available from the unified surface.

/tfx-persist "implement full auth flow with tests"
/tfx-auto "implement full auth flow with tests" --retry ralph --max-iterations 10

3-Party Consensus Reviews — tfx-review / tfx-plan

The bread-and-butter Deep skills. Three models independently review your code or plan your implementation, then cross-validate. Only consensus-verified findings survive.

/tfx-review            # 3-party code review by default
/tfx-plan "migrate to GraphQL"  # 3-party planning by default

Structured Debate — tfx-debate (alias for tfx-auto --mode consensus --shape debate)

Three models take independent positions on a technical question, debate, and converge on a recommendation. Anti-herding ensures genuine independence, while Phase 4 folds the output shape into tfx-auto.

/tfx-debate "Redis vs PostgreSQL LISTEN/NOTIFY for real-time events"

---

All 13 Core Skills (plus compatibility aliases)

Expand full skill list

Research & Discovery

Skill	Type	Description
tfx-index	Core	Project indexing and context compression

Internal routed helpers: tfx-research, tfx-find

Analysis & Planning

Skill	Type	Description
No standalone public surface	—	Analysis, planning, and interview route through internal helpers

Internal routed helpers: tfx-analysis, tfx-plan, tfx-interview

Execution

Skill	Type	Description
tfx-auto	Core	Unified CLI orchestrator — auto-triage, flag-based routing, and legacy surface folding

Compatibility aliases: tfx-autopilot, tfx-fullcycle, tfx-multi, tfx-persist, tfx-swarm

Review & QA

Skill	Type	Description
No standalone public surface	—	Review, QA, and cleanup route through internal helpers

Internal routed helpers: tfx-review, tfx-qa, tfx-prune

Debate & Decision

Skill	Type	Description
No standalone active surface	—	Debate, consensus, and panel shapes now route through tfx-auto --mode consensus

Compatibility aliases: tfx-consensus, tfx-debate, tfx-panel

Persistence & Routing

Skill	Type	Description
tfx-hooks	Core	Claude Code hook priority manager
tfx-profile	Core	Codex/Gemini CLI profile management

Internal routed helper: tfx-ralph

Orchestration & Infrastructure

Skill	Description
tfx-hub	MCP message bus — Named Pipe & HTTP bridge
merge-worktree	Worktree merge helper for swarm results

Swarm execution is exposed through tfx-auto --parallel swarm and the tfx swarm CLI.

Remote

Skill	Description
tfx-remote	Unified remote command family — setup, spawn, list, attach, send, resume, probe, rules

Compatibility aliases: tfx-remote-spawn, tfx-remote-setup, tfx-psmux-rules — rules moved to .claude/rules/tfx-psmux.md in Phase 4

Meta & Tooling

Skill	Description
tfx-forge	Create new skills interactively
tfx-setup	Initial setup wizard
tfx-doctor	Diagnostics and auto-repair
tfx-ship	Ship workflow orchestration
tfx-wt	Windows Terminal tab/pane control
star-prompt	GitHub star prompt for postinstall

---

Deep vs Light

Every domain offers both modes. Depth modifiers in natural language auto-escalate:

Phase mapping:

• --mode deep is the direct Light → Deep switch from Phase 2
• --retry ralph / --retry auto-escalate add Phase 3 persistence and escalation semantics
• --shape consensus|debate|panel adds Phase 4 output-shape routing on top of consensus mode

Dimension	Light	Deep
Models	Single (usually Codex)	3-party (Claude + Codex + Gemini)
Tokens	3K–15K	20K–80K
Speed	Seconds	Minutes
Accuracy	Good (single perspective)	Excellent (consensus-verified)
Bias	Possible	Eliminated via anti-herding
Trigger	Default, "quick", "fast"	"thoroughly", "carefully", "제대로"

---

Architecture

Interactive diagram

graph TD
    User([User / Claude Code]) <-->|"Skills & Natural Language"| TFX[tfx Skills Layer]
    TFX <-->|Consensus Engine| CONSENSUS[tfx-consensus]

    subgraph "Tri-CLI Consensus"
        CONSENSUS -->|Independent| CLAUDE[Claude Opus/Sonnet]
        CONSENSUS -->|Independent| CODEX[Codex CLI]
        CONSENSUS -->|Independent| GEMINI[Gemini CLI]
        CLAUDE --> MERGE[Cross-Validation]
        CODEX --> MERGE
        GEMINI --> MERGE
        MERGE --> GATE{Consensus >= 70%?}
        GATE -->|Yes| OUTPUT[Verified Output]
        GATE -->|No| RESOLVE[Resolution Round]
        RESOLVE --> MERGE
    end

    TFX <-->|Named Pipe / HTTP| HUB[triflux Hub]

    subgraph "Hub Services"
        HUB <--> STORE[(SQLite Store)]
        HUB <--> REFLEXION[Reflexion Engine]
        HUB <--> ADAPTIVE[Adaptive Rules]
        HUB <--> MONITOR[TUI Monitor]
    end

    REFLEXION -->|"Feedback Loop"| TFX
    HUB -.->|MCP Bridge| External[External MCP Clients]

Loading

---

TUI Routing Monitor

Available in v10.11.0 — tfx monitor launches an interactive terminal dashboard:

┌─ Routing Monitor ─────────────────────────────────────────┐
│                                                           │
│  Active Skills    Success Rate    Avg Latency    Model    │
│  ─────────────    ────────────    ───────────    ─────    │
│  tfx-review       94.2%           3.2s           codex    │
│  tfx-auto         87.1%           5.8s           mixed    │
│  tfx-research     91.0%           4.1s           claude   │
│                                                           │
│  Reflexion Store: 142 rules  │  Adaptive: 28 promoted     │
│  Q-Table entries: 89         │  Pending penalties: 3      │
│                                                           │
└───────────────────────────────────────────────────────────┘

The monitor visualizes:

• Real-time skill routing decisions and model selection
• Success/failure rates per skill and per model
• Reflexion store growth and adaptive rule promotions
• Q-Learning weight evolution (when TRIFLUX_DYNAMIC_ROUTING=true)

---

What's New

v10.11.0 — Phase 3: Retry, Escalation, Codex Lead

Feature	Description
True Ralph Retry	--retry ralph now maps to the real persistence state machine instead of a bounded placeholder
Auto Escalation	--retry auto-escalate enables the four-step DEFAULT_ESCALATION_CHAIN
Codex-Led Pipeline	--lead codex and --no-claude-native expose the Codex-first execution lane
Iteration Budgeting	--max-iterations N makes retry loops explicit and reviewable
Reflexion + Guards	safety-guard and headless-guard continue feeding adaptive learning and hard security boundaries
Routing Monitor	tfx monitor remains the live view over skill routing, model mix, and latency

v10.11.0 — Phase 4: Flag-Based Surface Consolidation

Expand Phase 4 details

• One front door — tfx-auto now absorbs legacy behaviors through flags instead of one-off top-level surfaces
• Consensus shapes — --shape consensus|debate|panel folds ensemble behaviors into the main router
• Remote consolidation — tfx-remote becomes the single remote surface while tfx-remote-spawn remains a thin alias
• Rules relocation — tfx-psmux-rules moved out of the skill surface to .claude/rules/tfx-psmux.md
• Legacy compatibility — 11 compatibility aliases remain for transition safety and are slated for later removal

v9 — Harness-Native Intelligence

Expand v9 details

• Natural Language Routing — Say "review this" or "리뷰해줘" instead of memorizing skill names
• Cross-Model Review — Claude writes → Codex reviews. Same-model self-approve blocked
• Context Isolation — Off-topic requests auto-detected; spawns a clean psmux session
• Codex Swarm Hardened — PowerShell .ps1 launchers, profile-based execution

v8 — Tri-Debate Foundation

Expand v8 details

• Tri-Debate Engine — 3-CLI independent analysis with anti-herding and consensus scoring
• Deep/Light Variants — Every domain has both a fast mode and a thorough mode
• Expert Panel — Virtual expert simulation via tfx-panel
• Hub IPC — Named Pipe & HTTP MCP bridge
• psmux — Windows Terminal native multiplexer

---

Security

Layer	Protection
Hub Token Auth	Secure IPC via TFX_HUB_TOKEN (Bearer Auth)
Localhost Binding	Hub defaults to 127.0.0.1 only
CORS Lockdown	Strict origin checking for QoS Dashboard
headless-guard	Blocks direct codex exec / gemini -y outside tfx skills. Wrapper bypass, pipe bypass, env escape vectors all covered
safety-guard	SSH bash-syntax forwarding prevention, injection-safe shell execution
Consensus Verification	Deep skills prevent single-model hallucination via 3-party consensus
Reflexion Feedback	Security events feed adaptive rules for continuous improvement

---

Platform Support

Platform	Multiplexer	Status
Windows	psmux (PowerShell) + Windows Terminal	Full support (CP949 encoding handled)
Linux	tmux	Full support
macOS	tmux	Full support

---

5-Tier Adaptive HUD

The Claude Code status bar auto-adapts to any terminal width:

 full (120+ cols)  ██████░░░░ claude 52%  ██████░░░░ codex 48%  savings: $2.40
 compact (80 cols) c:52% x:48% g:Free  sv:$2.40  CTX:67%
 minimal (60 cols) c:52% x:48% sv:$2.40
 micro (<60 cols)  c52 x48 sv$2
 nano (<40 cols)   c:52%/x:48%

Zero config. Open a vertical split pane and the HUD auto-collapses. Close it and it expands back. When tfx-multi is active, a live worker row appears showing per-CLI progress: x✓ g⋯ c✗ (completed/running/failed).

Context token attribution tracks usage by skill, file, and tool call, with warnings at 60%/80%/90% context fill.

---

Windows Terminal Orchestration

triflux doesn't just run in a terminal -- it orchestrates it. The WT Manager API provides:

• Tab creation with PID-tracked lifecycle (temp file polling for readiness)
• Split-pane layouts via applySplitLayout() for multi-agent dashboards
• Dead tab pruning using cross-platform PID liveness detection
• Base64 PowerShell encoding eliminating all quoting/escaping issues

Every direct wt.exe call is blocked by safety-guard. Agents can only use the managed API path, preventing uncontrolled terminal sprawl.

---

Research Foundation

The triflux skill suite was shaped by patterns from across the Claude Code ecosystem:

Project	Inspiration
everything-claude-code	Instinct-based learning patterns
Superpowers	TDD enforcement, composable skills
oh-my-openagent	Category routing, Hashline edits
SuperClaude	index-repo 94% token reduction, expert panels
oh-my-claudecode	Ralph persistence, CCG tri-model
ruflo	60+ agent orchestration
Exa / Brave / Tavily MCP	Neural search, deep research pipeline

5-language research (EN/CN/RU/JP/UA) uncovered unique patterns: WeChat integration (CN), Discord mobile bridges (JP), GigaCode alternatives (RU), and community-driven localization efforts.

---

_{MIT License · Made by tellang}