"`. Options: [skills/tfx-remote/SKILL.md](skills/tfx-remote/SKILL.md).
## Architecture
```mermaid
graph TD
User([Claude Code prompt / shell]) --> Skills["/tfx-auto · /tfx-live · /tfx-remote"]
User --> Lead["/tfx-lead"]
User --> CLI[tfx CLI]
Lead -->|"briefs, cross review, merge"| Live
Skills --> Route[tfx-route.sh]
Skills --> Live[tfx-live]
CLI --> Team["tfx multi"]
Route --> Codex[Codex CLI]
Route --> Agy[Antigravity agy]
Route --> Claude[Claude Code]
Team -->|headless workers| Route
Team --> Index[("results index: tfx-headless/*.results.json")]
Team --> Rows["claude agents rows"]
Rows -->|Enter| Room["worker tmux room"]
Live -->|"codex queue, tmux fallback"| CodexTUI[Codex TUI sessions]
Live -->|"UDS or tmux"| ClaudeTUI[Claude Code sessions]
Route --> HUD[HUD]
```
Package layout and execution paths: [ARCHITECTURE.md](ARCHITECTURE.md). Documentation map:
[docs/README.md](docs/README.md).
## Platforms
| Platform | Multiplexer | Notes |
| --- | --- | --- |
| macOS | tmux | Default path. Install `coreutils` (`gtimeout`) if you keep a positive hard ceiling. |
| Linux | tmux | Supported. |
| Windows | psmux + Windows Terminal | See below. |
**Windows.** psmux (a tmux fork) runs PowerShell by default. Callers do not run `wt.exe` or raw
`psmux kill-session` directly; tabs and panes go through the `tfx-wt` skill (set up only on
Windows) and `hub/team/wt-manager.mjs`. Agent rules:
[`.claude/rules/tfx-psmux.md`](.claude/rules/tfx-psmux.md).
## Security and guards
| Layer | Protection |
| --- | --- |
| Managed routes | Codex and Antigravity are called through `tfx-route.sh`, headless workers, or `tfx`, never through a bare `codex exec` or `agy`. This is a rule for callers; no hook enforces it. |
| MCP registry | Replaces stale or unsupported MCP entries with managed ones. |
| Consensus | Deep and consensus runs report degraded or disputed results instead of hiding them. |
### Jev data transfer policy
Jev is opt-in. It is enabled by `JEV_API_KEY` or `TYPESAFE_API_KEY`, by an explicit
`TFX_JEV_CLI` path, or by `TFX_JEV=1` with a discoverable Jev CLI. Built-in judgments
send inputs to the external Jev HTTP service when an API key is present, otherwise
to the configured CLI through its arguments.
A host can enable Jev for existing Claude, Codex, Antigravity, and HUD processes with
`~/.config/triflux/jev.json` (`$XDG_CONFIG_HOME/triflux/jev.json` when set):
`{"enabled":true,"apiKeyFile":"/absolute/path/private.env"}`.
The key file must be owned by the current user with mode `0600`; only literal
`JEV_API_KEY` or `TYPESAFE_API_KEY` assignments are read as data, never sourced.
Environment keys and CLI settings retain precedence. `TFX_JEV=0`, `false`, or `off`
disables Jev even with host configuration. The HUD badge indicates enabled
configuration, not successful authentication. Invalid credentials and failed calls
fall back to the existing deterministic behavior. No restart is needed for host-config reads.
Task prompts and instructions are sanitized before length limiting and again at
the HTTP or CLI boundary. Built-in task routing keeps up to 1,400 characters, MCP
task selection 1,200, busy actions and session selection 1,000, subtask assignment
800, injected instructions 600, and expected composer prefixes 200. General
stdout, stderr, rollout, worker output, and TUI captures contribute only metadata
such as character and line counts and progress, input-waiting, or error flags.
Only `judgeSameFailureCause` and `judgePeerConvergence` may send semantic excerpts
from failure reasons or peer replies. Each reason or reply must fit within 600
characters as one complete line; an optional peer task must fit within 500. These
limits use JavaScript string length (UTF-16 code units). No lines are selected
from a larger log, and these excerpts are never truncated or whitespace-normalized.
Empty, oversized, multiline, control-character, and structured log-like inputs
are rejected. If sanitization changes any excerpt, peer task, or assembled context, the judgment
returns `null` before calling a client, HTTP, or CLI. Rejecting every changed
candidate also prevents different originals from collapsing into the same
redacted excerpt. A rejected comparison adds no Jev evidence for STUCK or early
peer closure; existing deterministic control continues.
The sanitizer recognizes patterns such as credential assignments, Bearer tokens,
and private keys. Regular expressions cannot guarantee removal of every secret.
Set `TFX_JEV=0` to disable Jev, including when a key or CLI is configured, and keep
it disabled for sensitive tasks.
### Optional native peer adapter
`triflux setup` optionally approves only the dedicated `~/.claude/scripts/tfx-peer send` wrapper for local Claude and Codex peers, without broad Bash or sandbox approval; `~` is a shell example, while Codex rules match the exact absolute path printed by setup. Claude reports `written` after its UDS write without a receiver ACK, while Codex sends a typed `agent_message` only to an eligible same-daemon thread; neither result proves model completion. See the [tfx-live skill](skills/tfx-live/SKILL.md#선택적-전역-native-peer-어댑터) for setup trust limits, retry behavior, and revocation of the allow entry, rule, wrapper, and consent manifest.
## Contributing
Node 22 or newer. See [CONTRIBUTING.md](CONTRIBUTING.md) for tests, lint, package boundaries,
mirror and release checks, and state snapshots. Releases are automated: merging a version-bump
commit to `main` runs `release.yml` after CI passes; it tags, creates the GitHub release, and publishes to npm
through OIDC Trusted Publishing. Decisions are recorded in [docs/adr/](docs/adr/README.md).
MIT License · Made by tellang
