English | 한국어

What is triflux?

triflux is a Claude Code plugin + npm CLI for routing AI coding work across Claude, Codex, and Antigravity without letting ad-hoc shell commands or stale skill aliases become the control plane.

The current design is intentionally simpler than the old README implied:

• /tfx-auto is the canonical Claude Code skill front door. Use flags to express quick/deep/consensus/parallel/retry behavior.
• tfx is the shell CLI. Use it for setup, diagnostics, hub lifecycle, MCP sync, team/swarm orchestration, and handoffs.
• Compatibility aliases still exist, but they are not the primary API. They are documented in docs/legacy-skill-aliases.md so the main README stays focused on the supported path.
• Host-local Codex harnesses are out of package scope. For example, a local ~/.codex/skills/tfx-harness can recommend workflows on one machine, but it is not shipped in this repository, npm package, or Claude plugin.

Quick Start

1. Install

Claude Code plugin install:

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

npm install:

npm install -g triflux

Then run the setup/diagnostic path from a terminal:

tfx setup
tfx doctor

Use tfx doctor --json when you need machine-readable status for automation.

2. Use the canonical front doors

Claude Code slash skills:

/tfx-auto "review this change" --mode consensus
/tfx-auto "implement auth flow with tests" --mode deep --retry ralph
/tfx-auto "split this PRD across isolated shards" --parallel swarm --mode consensus --isolation worktree
/tfx-remote spawn ryzen5-7600 "run a security review"
/tfx-doctor

Shell CLI:

tfx list
tfx hub ensure
tfx mcp list
tfx handoff --target remote --output .omx/handoff.md
tfx swarm preflight docs/prd/example.md --json
tfx codex-team "refactor auth + add tests"

Deep, consensus, team, and swarm paths need the relevant CLIs and a terminal multiplexer. Run tfx doctor first; it reports missing Codex/Antigravity/Claude, psmux/tmux, Hub, MCP, profile, and stale-skill issues.

Current Surface

Shell commands

The tfx CLI currently exposes these primary commands:

| Command | Use | | --- | --- | | tfx setup | Sync scripts, HUD, hooks, MCP, and profiles. Supports --dry-run. | | tfx doctor | Diagnose and repair installation state. Supports --fix, --reset, --diagnose, --json. | | tfx auto | Preview the tfx-auto routing decision. Supports --cli, --mode, --parallel, --json. | | tfx mcp | Manage MCP registry targets with list, sync, add, and remove. | | tfx hub | Start, stop, ensure, or inspect the local MCP message bus. | | tfx list | Show installed package and user skills. | | tfx handoff | Serialize the current context for local or remote continuation. | | tfx schema | Print CLI and Hub delegator schemas. | | tfx hooks | Scan, diff, apply, restore, or inspect hook orchestrator state. | | tfx tray | Start the tray/HUD status process; use --attach for foreground debugging. | | tfx multi | Launch local multi-agent team mode through tmux/psmux + Hub. | | tfx swarm | Plan, preflight, run, or list PRD-based worktree-isolated swarm work. | | tfx synapse | Inspect swarm registry and leases. | | tfx review | Run Codex-backed git diff review. | | tfx codex-team | Codex-led team mode convenience wrapper. | | tfx notion-read | Convert Notion pages to Markdown through configured MCP clients. | | tfx why | Read intent trailers from the last commit touching a path. | | tfx update | Update to the latest stable or dev package. | | tfx monitor | Open the terminal TUI monitor. | | tfx version | Print version information. | | tfx-profile | Convenience binary for interactive Codex profile management. |

Run tfx schema <command> for the exact argument contract.

Claude Code skills

The package ships 34 skill files. The important split is:

• Canonical entrypoints: tfx-auto, tfx-remote, tfx-doctor, tfx-setup, tfx-profile, tfx-hub, tfx-hooks, tfx-ship, tfx-wt.
• Task helpers: tfx-plan, tfx-review, tfx-qa, tfx-research, tfx-analysis, tfx-find, tfx-index, tfx-interview, tfx-prune, tfx-forge, merge-worktree, star-prompt.
• Deprecated compatibility aliases: 11 legacy names remain only as transition shims. Prefer the canonical commands above and see the alias table only when migrating old prompts.

Canonical flag map

Most old skill names now map to explicit tfx-auto flags:

| Intent | Canonical form | | --- | --- | | quick single-lane work | /tfx-auto "task" --mode quick | | deeper plan/execute/verify loop | /tfx-auto "task" --mode deep | | persistent retry loop | /tfx-auto "task" --retry ralph | | consensus review | /tfx-auto "task" --mode consensus | | debate or panel report | /tfx-auto "task" --mode consensus --shape debate|panel | | local parallel work | /tfx-auto "task" --parallel N --mode deep or shell tfx multi ... | | PRD/worktree swarm | /tfx-auto "task" --parallel swarm --mode consensus --isolation worktree or shell tfx swarm ... | | force a CLI lane | /tfx-auto "task" --cli codex|antigravity|claude |

Control-plane boundaries

Keep these surfaces separate when debugging or extending triflux:

| Surface | Source of truth | Ships in npm/plugin? | | --- | --- | --- | | Public CLI/runtime | bin/, scripts/, hub/, hooks/, skills/ | Yes | | Published mirror | packages/triflux/ | Yes; must match root runtime files | | Claude plugin metadata | .claude-plugin/ | Yes; points at npm package contents | | Codex-local harness experiments | ~/.codex/skills/* | No | | Legacy aliases | skills/<alias>/ + docs/legacy-skill-aliases.md | Yes, but deprecated |

If a local Codex harness recommends a workflow, treat that as host-local routing advice. The package contract is still the CLI, Claude skill, hook, and Hub surface above.

Canonical Workflows

Direct implementation or review

/tfx-auto "fix the failing auth tests" --risk-tier medium
/tfx-auto "review this PR for SQL and trust-boundary issues" --mode consensus

Use --risk-tier low|medium|high when you want verification intensity to be explicit. Use --mode quick|deep|consensus when you already know the mode.

Persistent completion loop

/tfx-auto "finish the migration and verify it" --mode deep --retry ralph --max-iterations 10

--retry ralph uses the retry state machine and stuck detection. Set --max-iterations when the loop must be bounded.

Consensus, debate, or panel output

/tfx-auto "Postgres LISTEN/NOTIFY vs Redis Streams" --mode consensus --shape debate
/tfx-auto "review the migration strategy" --mode consensus --shape panel

Consensus participants are the configured Claude/Codex/Antigravity lanes. If a lane is unavailable, the result should report partial/degraded status instead of hiding it.

Local team or PRD swarm

# Local team mode
tfx multi "refactor auth + update UI + add tests"

# Worktree-isolated PRD swarm
tfx swarm preflight docs/prd/my-feature.md --json
tfx swarm run docs/prd/my-feature.md

Swarm work uses isolated worktrees and file leases. Use preflight before running a large PRD so missing hosts, CLI profiles, and lease conflicts are caught first.

Remote sessions

/tfx-remote setup
/tfx-remote spawn ryzen5-7600 "run security review"
/tfx-remote list
/tfx-remote attach <session>
/tfx-remote send <session> "continue with fixes"

tfx-remote is the consolidated Claude skill surface for setup/spawn/list/attach/send/resume/probe/kill flows.

Save or restore context

tfx handoff --target remote --decision "Keep README canonical; move aliases to docs" --output .omx/handoff.md

Use handoffs when a session is ending or when another host/agent needs the current state without replaying the entire conversation.

Architecture

graph TD
    User([User / Claude Code / shell]) --> Skills[Claude skills]
    User --> CLI[tfx CLI]
    Skills --> Auto["/tfx-auto"]
    Skills --> Remote["/tfx-remote"]
    CLI --> Hub[triflux Hub]
    CLI --> Team[tfx multi / swarm]
    Auto --> Route[tfx-route.sh + guards]
    Team --> Hub
    Remote --> Hub
    Route --> Codex[Codex CLI]
    Route --> Antigravity[Antigravity agy CLI]
    Route --> Claude[Claude Code]
    Hub --> MCP[MCP registry + bridge]
    Hub --> Store[(SQLite or memory store)]
    Hub --> Dashboard[HUD / monitor]

The common routing path is:

1. Claude Code prompt or explicit skill invocation.
2. Keyword/routing hooks may add context or choose a skill.
3. tfx-auto normalizes intent into mode, retry, parallelism, risk tier, and target CLI lane.
4. tfx-route.sh, Hub workers, or the tfx CLI execute the actual Codex/Antigravity/ Claude-backed work.
5. Hub records team messages, leases, retries, handoffs, and status surfaces.

Hub

The Hub is the local message bus for teams, remote sessions, MCP tools, and status surfaces. It binds to localhost, uses pipe/HTTP transports, and can be managed with:

tfx hub ensure
tfx hub status --json
tfx hub stop

macOS may show a firewall prompt when tests or Hub startup open a localhost port through node. For normal documentation work this is not needed; for active Hub, team, or MCP workflows allow localhost access if your environment requires it.

Guards

triflux keeps risky execution behind managed routes:

• CLI calls should flow through tfx-route.sh, Hub workers, or the tfx CLI.
• Direct codex exec, unmanaged agy, and deprecated gemini routes are guarded in the installed workflow.
• psmux/Windows Terminal flows must use the managed API and documented rules, not ad-hoc wt.exe or psmux send-keys snippets.

Profiles and model routing

Use tfx-profile for Codex profiles and tfx setup/tfx doctor for Antigravity plus legacy Gemini compatibility state. Do not hardcode model and effort flags in launcher scripts when a profile already owns them.

Operations

Diagnostics

tfx doctor
tfx doctor --json
tfx doctor --fix
tfx doctor --diagnose

doctor checks CLI availability, profiles, hooks, skills, Hub, MCP registry, route-script sync, stale teams, and common local configuration drift.

MCP registry

tfx mcp list
tfx mcp sync
tfx mcp add context7 --url https://mcp.context7.com/mcp
tfx mcp remove context7

The registry is the source of truth for managed MCP targets. Avoid hand-editing Codex/Antigravity/Claude MCP files unless you are intentionally debugging drift.

State snapshots

Hub startup can take best-effort daily snapshots of selected ~/.codex/ and Antigravity/Gemini ~/.gemini/ state into ignored references/*-snapshots/ folders. Manual helpers:

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

Release and mirror checks

For repository changes that affect package contents, run the release gates before shipping:

npm run lint:skills
npm run gen:skill-manifest
npm run release:check-sync
npm run release:check-mirror
npm run lint

packages/triflux is the npm-publishable mirror for several top-level runtime folders. Keep it synchronized when touching mirrored runtime files.

Platform Support

| Platform | Multiplexer | Notes | | --- | --- | --- | | macOS | tmux | Supported. Requires a timeout provider such as gtimeout for some flows. | | Linux | tmux | Supported. | | Windows | psmux + Windows Terminal | Supported through managed psmux/WT paths. PowerShell is the default psmux shell. |

See AGENTS.md and .claude/rules/tfx-psmux.md for the stricter Windows/psmux rules used by agents and launch scripts.

Security and Guards

| Layer | Protection | | --- | --- | | Hub token auth | Local bearer token for Hub APIs where configured. | | Localhost binding | Hub defaults to 127.0.0.1. | | MCP registry guard | Replaces unsupported or stale MCP records with managed HTTP entries. | | Headless guard | Blocks unmanaged Codex/Antigravity headless execution paths and deprecated Gemini routes. | | Safety guard | Sanitizes shell-sensitive psmux/SSH/WT flows. | | Consensus reporting | Deep/consensus workflows should report degraded or disputed findings explicitly. |

Development

npm ci
npm test
npm run lint
npm run release:check-sync
npm run release:check-mirror

Notes for contributors:

• Keep deprecated alias details out of the main README; update docs/legacy-skill-aliases.md instead.
• Keep Codex-local experiments under ~/.codex/skills, not in this package, unless the package boundary is intentionally changed.
• For docs-only changes, targeted checks such as npm run lint and release sync checks are usually enough; full integration tests may start Hub servers and local listener prompts.