Flux Client Documentation

Getting Started

Prerequisites

• Windows 10/11 (64-bit). macOS and Linux coming soon.
• Git 2.0+ installed on your system
• A GitHub account (for cloud features)
• An API key from Groq, DeepSeek, Anthropic, OpenAI, xAI, or Google (for AI Agent)

Installation

Architecture Overview

Flux Client is built on Electron with a React 18 renderer and a Node.js main process.

Multi-Account Management

Seamlessly switch between Personal, Work, and Client GitHub accounts without logging out.

• Add Account: Click the "+" icon in the left sidebar to authenticate via GitHub OAuth.
• Context Switching: Click an avatar to activate that account. The active account is used for all pushes, pulls, and API calls.
• Security: tokens are encrypted at rest using machine-specific keys.

Changes & Staging

The Changes Tab (Ctrl+1) is your main workspace.

• Visual Diff: Click any file to see side-by-side changes in the Monaco diff editor with full syntax highlighting and line-level blame.
• Stage/Unstage: Use the "+" and "-" buttons or "Stage All".
• Commit: Write a message and press Ctrl+Enter to commit.
• Amend: Toggle "Amend last commit" to update the previous commit without creating a new one.

Commit History

View the log in the History Tab (Ctrl+3).

• Filtering: Filter commits by branch, author, or message text.
• Details: Click any commit to see full details, changed files, and parent hashes with Monaco diff preview.
• Actions: Revert, cherry-pick, or checkout commits from the context menu.
• Blame View: Switch the file viewer to Blame mode to see per-line author and commit attribution.

Branch Management

Manage local and remote branches in the Branches Tab (Ctrl+4).

Cloud Repositories

The Cloud Tab (Ctrl+5) lists all repositories from your connected GitHub account.

• Clone: One-click clone to any local directory.
• Create: Initialize new repos locally or publish to GitHub in one step.
• Manage: Toggle visibility (public/private), rename, or delete repos.
• Forks: Sync forks with upstream and manage pull request submissions.

AI Agent

Open the Agent Tab (Ctrl+K then "agent", or the Bot icon) to delegate Git tasks in plain English. The agent uses a PLAN → ACT → VERIFY → ADAPT loop to autonomously complete multi-step operations.

Supported Providers

Setup

1. Open the Agent Tab and click the Key icon in the header.
2. Select your provider and model from the dropdowns.
3. Paste your API key — stored locally only, never sent anywhere except directly to the provider.
4. Click Save Config and start chatting.

What the Agent Can Do

• Run git operations (status, stage, commit, push, pull, branch, merge, stash, reset)
• Read and write files directly on disk
• Verify action outcomes with check_path_exists, git_status, git_log
• Register new local repositories in the sidebar (add_repository)
• Control the app UI: switch tabs, open repos, edit workflow canvas nodes
• Adapt when an action fails — tries alternative strategies before escalating to the user

⚠️ Destructive operations (push, reset, delete) always require an explicit Allow click in the confirmation dialog — the agent never executes them silently.

Visual Workflow Editor

The Actions Tab → Workflow Editor provides a full React Flow canvas for editing GitHub Actions .yml files visually.

• Node Types: Trigger, Job, Step, Condition, Matrix Strategy, Sub-Workflow (call)
• Data Pins: Connect outputs to inputs with typed wires (string, boolean, number)
• Logic Flow: Fan-out/fan-in wires for conditional job ordering
• Matrix Strategy: Configure multi-dimensional build matrices visually
• YAML Sync: Monaco editor and canvas stay in sync — edit in either view
• GitHub Sync: Save directly to the repo; the agent can edit canvas nodes on your behalf

GitHub Actions Monitor

Monitor CI/CD pipelines in the Actions Tab (Ctrl+8). View live streamed logs, cancel in-progress runs, or re-run failed jobs — without opening a browser.

• Workflow Runs List: See status, duration, and trigger for every run.
• Job Logs: Streaming log output grouped by step with timestamps.
• Activity Panel: A unified feed of recent git events and CI status changes across all repos.

Multi-Terminal

Flux Client includes a full xterm.js terminal with support for multiple named tabs (Ctrl+J to toggle).

• Multiple Tabs: Open as many terminal sessions as you need, each with its own name and process.
• Credential Injection: GitHub credentials are auto-injected so git push works without password prompts.
• Persistent CWD: Each tab remembers its working directory across restarts.
• Agent Integration: The AI agent runs terminal commands in a dedicated background session.

Git LFS

Manage large binary assets directly from Flux Client without touching the command line.

• Detection: The Changes Tab automatically shows LFS-tracked files with a badge.
• Track / Untrack: Right-click any file → "Track with LFS" — updates .gitattributes automatically.
• Push: LFS pointers are pushed transparently during a normal commit + push flow.
• Requirements: Git LFS must be installed on your system (git lfs install).

Time Machine (Reflog)

The Time Machine view exposes the full git reflog — every HEAD position your repo has ever been in.

• Browse: See every checkout, commit, merge, rebase, and reset with timestamps.
• Restore: Jump to any historical state with one click — perfect for recovering from accidental force pushes or bad resets.
• Access: History Tab → click the clock icon, or use the Command Palette.

Command Palette

Press Ctrl+K from anywhere to open the Command Palette.

• Search and jump to any tab or view
• Switch active repository
• Run git operations (stage all, commit, push, pull) without clicking
• Open the AI Agent
• Create branches, stash changes, and more

Keyboard Shortcuts