Connect an agent

flux-connect brings an agent up to speed on Flux, your preferences and a project. It gives the agent a reading plan and asks it to confirm what it read and saw, then wait for your instructions. Use Claude Code, Codex, or another agent in its own app or your preferred terminal. Flux includes the tools, skills and context they need.

Click AI in the title bar, or use Ctrl+K → AI status, to open the AI status panel. Pin moves the panel into its own window; Dock brings it back.

Connect Claude Code or Codex#

Click Connect on the agent’s card. Flux installs its skill, registers its MCP server and installs supported refresh hooks. A replacement shows the exact before and after text for your confirmation. Flux preserves unrelated settings and keeps backups. Restart open agent sessions afterward. In Codex, review and trust new hooks in /hooks.

Copy the command on the card into your agent: /flux-connect <project path> for Claude Code, or $flux-connect <project path> for Codex. With no project open, the command uses global to introduce Flux and your user context. Other agents… gives manual MCP instructions.

Repair checks and repairs the same integration. Disconnect removes only Flux-owned integration and restores prior registrations where safe; edited skills are kept. Your projects stay available. Connecting or repairing another app’s configuration always starts with your click.

Set up from a terminal#

The same setup is available through the installed launcher:

flux connect setup --dry-run
flux connect setup
flux connect doctor

Use --agents claude,codex to choose vendors. Setup preserves unrelated configuration and backs up changed files; --yes confirms replacement of an existing Flux registration. --use-this-install explicitly chooses the launcher owner. flux connect remove --agents codex --yes disconnects that vendor without removing the shared launcher.

For another agent, give it the Other agents… MCP configuration, or ask it to run flux-connect /path/to/project (equivalently flux connect /path/to/project) in its shell and follow the printed reading plan. The MCP route provides tools to read the pack and images even when the agent’s shell cannot access the cache.

What the agent reads#

Default connection depth is core:

• The short Flux primer and connection contract.
• Your UserContext text; your reference images and skills are indexed for use when needed.
• ProjectContext and its directly linked files, project Rules, and the recent Log with an index of all entry titles.
• A project map of documents, figures, decks and plots, open inbox items, and recent activity.
• Rendered canvas overviews so the agent can see the figures.

FluxLib is introduced by its purpose, location and tools; connect does not summarize your papers. Task manuals and other project documents are indexed for reading on demand. Large linked files may be shortened; the brief reports omissions and rendering problems. --depth full includes all documents and Log entries, follows project-context links more deeply, and adds individual figure images and deck contact sheets.

The command returns a brief, a short reading plan. The bundle holds the text; together with the rendered images and manifest, it forms a cached pack. The agent’s receipt names the project and pack, states what it read and saw, lists open items, and ends with Ready. Its Proof: line repeats codes from the ends of bundle sections and image corners. A receipt should acknowledge anything it could not read or view. Check a receipt from a terminal:

flux connect --check-receipt <packId> "<proof line>"

Connect is passive: it does not start editing, watching the inbox, or writing the Log. Give the agent its task after the receipt. See Comments and Inbox for the review loop and Context and memory for what to maintain.

Global connection, refresh and live pairing#

Use /flux-connect global, $flux-connect global, or flux-connect global to introduce Flux and your personal context without choosing a project. It also lists known projects. An already-bound MCP session keeps its project binding when you connect globally.

Connected MCP tools add a ↻ Since you last looked notice when others change the project; the agent can read the details with read_delta. Setup also installs supported prompt hooks so changes can reach the agent on your next message. Claude Code’s hook refreshes automatically; Codex hooks require the installed version’s support and your /hooks trust decision. For a fresh reading plan on demand, ask the agent to reconnect with --refresh (flux connect /path/to/project --refresh).

Add --live when connecting to pair with the open project. The agent checks the current selection each turn and can use get_view when you mean “this” or “what I’m seeing.” The title bar briefly shows a notice such as ◉ heron viewed your window, naming the session. Settings → General → Allow agents to view the Flux window controls this access and is on by default. Capture covers only that project’s Flux window. See live pairing for handoffs through Annotate.

Read the status#

The status dot on AI in the title bar is green when the bundle is ready for a connected agent, amber when it needs attention, and red when a connected integration or shared part is broken. Detected agents that are not connected need attention. Dismissing the one-time Connect an AI agent Home card remembers that choice; it never hides an actual error.

The panel has four sections:

• Agents shows installed versions and each agent’s skill, registration, responding MCP, published user skills and refresh hook.
• Bundle shows the launcher and its owning install, the manual, user context, rendering and your Skills.
• Sessions shows the agents connected to this project, their watching and live badges, queues, current claims and connection times. Stop watching releases the session’s claims and tells its wait loop to stop.
• This project shows this window’s live bridge, saved inbox counts and last connection. Save edits to margin comments to include them in these counts.

Expand a row for its paths, version, last check, error and available fix. Run doctor performs fresh execution checks, including the MCP handshake and a small figure render, with results as each check finishes. Copy diagnostics runs those checks and copies the doctor JSON. Vendor configuration values are kept out of status and diagnostics; they appear only in a replacement you are confirming.

The panel paints its cached status immediately. Cheap probes refresh it on open, after setup and every ten minutes. Full doctor checks run only when requested. Execution checks say Not checked until a doctor result is available.

Your skills#

In Bundle → Skills, click New skill…, or use Ctrl+K → New agent skill…. Enter a short lowercase name with hyphens, such as stats-conventions. Flux creates a folder with a starter SKILL.md and opens it in your default editor, just like Open global rules. Describe when to use the procedure, its steps and checks.

Reveal in folder opens the skills location. Skills are published to connected agents and kept in sync: invoke /stats-conventions in Claude Code or $stats-conventions in Codex. Re-publish checks publication now. Name collisions and edited vendor copies are reported and preserved.

What is the AI bundle?#

The bundle ships with Flux. Connect is the step that registers it with an agent. See Comments and Inbox for routing and replies, and Context and memory for the files agents read.

Troubleshooting#

If a row is red, expand it and run Fix when offered. Run doctor gives the latest execution evidence. Use this Flux for agents explicitly chooses this installation when the launcher belongs to another checkout or install.

If a new skill does not appear, check its name and description in the frontmatter, use Re-publish, and restart your agent session. Flux leaves edited and unmanaged files alone; the row explains any collision or permission error.

If no sessions appear, run the copied connection command in the agent. Presence appears after an explicit project connection and expires when its heartbeat stops. The monitor does not start an agent or enable watch mode by itself.

If flux is not on PATH, use the full launcher path from the command-line guide. Run flux connect doctor (or --json) for the same diagnostics from a terminal. If an agent’s shell cannot write outside its workspace, use the registered MCP tools; connect also has a temporary-cache fallback. Setup does not change the agent’s sandbox policy.