fluxion-bus: Instructions file for Codex

Fluxion Agent Guide

Project Goal

Fluxion is a local-first agent gateway. The primary agent keeps ownership of the task, while Fluxion can delegate scoped subtasks to local executors such as Antigravity, Codex, or Claude.

Fluxion Sub-Agent MCP

Use the Fluxion MCP server when a subtask is self-contained and delegating it can reduce the primary agent's context load.

Available MCP flow:

1. If the task is for a known repo, call mcp__fluxion__list_projects and use the matching project key instead of passing a raw absolute path.
2. Call mcp__fluxion__run_subagent. Use wait_for_result=true for short tasks that are expected to finish quickly; use wait_for_result=false for longer investigation or implementation work.
3. Poll mcp__fluxion__get_task_status with the returned run_id.
4. If the active run should be stopped, call mcp__fluxion__cancel_subagent_run with the same run_id.
5. When status is RETURNED, FAILED, or CANCELED, call mcp__fluxion__get_task_result.
6. Review the result before relying on it or continuing work.
7. If a workspace-writing run produced unwanted changes, call mcp__fluxion__revert_subagent_run only after reviewing the recorded change_set_file and conflict risk.

Polling and failure handling:

• Poll at a modest interval, such as every 2-5 seconds for short checks and less frequently for longer implementation tasks.
• For likely 10-30 second subtasks, prefer wait_for_result=true to avoid extra tool-call turns. For long-running tasks, keep async mode and avoid tight polling loops.
• wait_for_result waits on the whole lifecycle, including queue time. If it returns timed_out=true, check the returned status (QUEUED vs RUNNING) and continue with get_task_status; the task is not canceled by the wait timeout.
• If a run does not finish in a reasonable task-specific time, stop polling and report the current run_id, status, and blocker instead of looping forever.
• Use progress_signal, log_updated_at, and recent_output_tail from get_task_status to distinguish a long-running task that is still producing output from one that appears stuck. recent_output_tail is intentionally a short tail, not a full log.
• get_task_status returns a compact polling payload by default. Pass detail=true only when repeated metadata such as timestamps, subagent metadata, changed_files, diff_summary, artifacts, or change_set_file is needed before get_task_result.
• Use cancel_subagent_run when the sub-agent is no longer needed or appears stuck. Cancellation only applies to active runs owned by the current MCP server process.
• Treat FAILED and CANCELED as terminal states. Inspect summary and log_file before retrying.
• Reverts are hash-checked. If revert_subagent_run reports conflicts, inspect manually instead of forcing over later user or agent changes.
• Avoid launching multiple workspace-writing sub-agents in the same workspace at the same time unless the files are clearly disjoint.