Skip to content

AGENTS.md

Latest commit

 

History

History
67 lines (51 loc) · 3.06 KB

AGENTS.md

File metadata and controls

67 lines (51 loc) · 3.06 KB
Raw

AGENTS.md

Setup guide for an AI agent (Claude Code, Codex, Gemini CLI, etc.) asked to install flux on the current user's machine. Follow the platform that matches the machine; do not guess. Prefer the user's stated preference if they have one.

What flux is

flux runs two AI agents in a tmux/psmux session - a "driver" (top-right) and a "helper" (bottom-right) - with the user's shell on the left. They collaborate over a bridge (tmux send-keys + capture-pane). flux --chat adds an IRC-style room; personas add optional character voices. The launcher is a single Bash script at bin/flux.

Prerequisites (check before installing)

  • claude on PATH (or another agentic CLI; see Providers). Required.
  • A multiplexer: tmux 3.2+ on Linux/macOS/WSL, or psmux on Windows.
  • Windows native mode also needs Git Bash (Git for Windows).

Install (run from the cloned repo directory)

  • Linux / macOS / WSL (inside the distro): ./install.sh Copies bin/flux and personas/ to ~/.flux, links ~/.local/bin/flux, and prompts for the user's chat handle. If ~/.local/bin is not on PATH, tell the user the export line to add.

  • Windows (native), in PowerShell from the repo: powershell -ExecutionPolicy Bypass -File .\install.ps1 Requires Git Bash and psmux (scoop install psmux or winget install psmux). Installs flux into the Git-Bash ~/.flux and adds a flux function to the user's $PROFILE. A new PowerShell window is needed afterward.

Verify

  • flux --persona list should list: plain droids asgard rickandmorty adventuretime bakerstreet xfiles
  • flux --version prints the version.
  • Do not run bare flux or flux --chat non-interactively; they take over the terminal. To smoke-test without attaching: flux --detach, then flux list, then flux kill.

Configure (optional)

  • Handle: flux me <name> (otherwise the user is asked on first chat).
  • Persona: flux --persona <name>, or set FLUX_PERSONA in ~/.flux/config.
  • Models: FLUX_MODEL_DRIVER (default opus), FLUX_MODEL_HELPER (default sonnet).
  • Providers: set driver_provider / helper_provider in ~/.flux/config (claude, gemini, codex, ollama). See docs/PROVIDERS.md. Only claude is verified.

Gotchas

  • bin/flux must keep LF line endings. .gitattributes enforces it and install.sh strips CRLF. Do not convert it to CRLF.
  • Security: by default flux launches agents with --dangerously-skip-permissions - no approval prompts and a full shell in the launch directory. Set it up only in directories the user trusts. To require approvals, set FLUX_PERMS='--permission-mode acceptEdits'. Tell the user about this; do not enable auto-permissions silently if they object.
  • The installer does not modify the user's Claude config.
  • Windows: psmux is third-party (tested v3.3.6). flux launches Git Bash via its 8.3 short path; do not rewrite that logic.
  • WSL /mnt/c is slow; prefer native Windows, or keep repos in the WSL filesystem.

Uninstall

  • Linux/macOS/WSL: rm -rf ~/.flux ~/.local/bin/flux
  • Windows: remove the # === flux === block from $PROFILE.