{"id":50553428,"url":"https://github.com/jsuya/flowmux","last_synced_at":"2026-06-04T05:01:07.527Z","repository":{"id":356900744,"uuid":"1232918613","full_name":"JSUYA/flowmux","owner":"JSUYA","description":"FlowMux — Agent Workflow Multiplexer Terminal. Go with the agents' flow.","archived":false,"fork":false,"pushed_at":"2026-06-04T03:08:14.000Z","size":5857,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T04:07:40.145Z","etag":null,"topics":["ai-agent","claude-code","codex","flowmux","linux","mux","opencode","terminal"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JSUYA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-08T12:07:45.000Z","updated_at":"2026-06-04T03:08:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JSUYA/flowmux","commit_stats":null,"previous_names":["jsuya/flowmux"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/JSUYA/flowmux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSUYA%2Fflowmux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSUYA%2Fflowmux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSUYA%2Fflowmux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSUYA%2Fflowmux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JSUYA","download_url":"https://codeload.github.com/JSUYA/flowmux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSUYA%2Fflowmux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33890052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude-code","codex","flowmux","linux","mux","opencode","terminal"],"created_at":"2026-06-04T05:01:03.873Z","updated_at":"2026-06-04T05:01:07.519Z","avatar_url":"https://github.com/JSUYA.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cdiv align=\"center\"\u003e\n  \n# FlowMux\n![icon](resources/icons/flowmux-180.png)\n\n**Agent Workflow Multiplexer Terminal** — *Go with the agents' flow.*\n\n\u003cimg src=resources/screenshot/screenshot_1.png  width=\"850\"/\u003e\n\n\u003c/div\u003e\n\n### A terminal for AI agent workflows, browser control, and task signals.\n\nflowmux is a Linux/GTK4 terminal for AI coding agents. The terminal pane uses\n`libghostty-vt` for VT state, flowmux-owned PTYs, and an application-owned GTK\nrenderer.\n\n\u003e Unofficial GPL-3.0-or-later reimplementation inspired by [cmux](https://cmux.com/ko), a macOS/AppKit app. Not affiliated with cmux.\n  \n## Control internal browser\n\nA WebKitGTK 6.0 browser tab lives next to terminal tabs in the same pane tree.\nThe clip shows an AI agent driving the page over flowmux's IPC socket —\nsnapshot the DOM, click, type, read state back — with no system Chromium and\nno separate driver.\n\n![video](resources/screenshot/video_control_browser.gif)\n\n## AI Agent notification (Claude, Codex, OpenCode)\n\nflowmux installs lifecycle hooks into Claude Code, Codex, and OpenCode so\n*task complete*, *needs approval*, and *error* events surface as native\ndesktop notifications — routed to the workspace that fired them, suppressed\nwhile that surface is focused, and isolated per window.\n\n![video2](resources/screenshot/claude_notification.gif)\n\n## Features\n\n- **Workspaces \u0026 panes** — side-panel workspaces hold tasks side by side, each\n  split into multiple keyboard-navigable panes mixing terminal and browser\n  tabs. `Ctrl+Shift+K` copies the focused cwd; right-click for Copy path / URL.\n- **In-app browser** — a WebKitGTK tab next to your terminals, drivable by\n  agents in a neighbouring pane (snapshot, click, type, read state). Import a\n  session from Firefox / Chrome / Chromium / Brave / Edge / Arc; **Web\n  Inspector** opens WebKit dev tools.\n- **Notifications** — terminal \"task complete\" / \"needs attention\" signals\n  become desktop notifications, routed to the firing workspace and quiet while\n  focused. Bell popover **All Clear** clears all entries and toasts at once.\n- **AI agent integration** — Claude Code, Codex, OpenCode work out of the box;\n  sessions persist across restarts. `claude-teams` opens a workspace pre-split\n  into per-Claude panes. `flowmux doctor` / `fix` audit and repair wiring.\n- **Customizable keybindings** — Options → **Keybindings** rebinds any shortcut\n  (applies on OK, no restart), saved to\n  `$XDG_CONFIG_HOME/flowmux/options.json`. IME/scroll terminal shortcuts\n  (Shift+Enter Hangul flush, smart PgUp/PgDn) are fixed and not editable.\n\n## Layout\n\n```\nflowmux/\n├── crates/\n│   ├── flowmux-core/       Domain types: Workspace, Surface, Pane, Notification\n│   ├── flowmux-config/     cmux.json + ~/.config/ghostty/config readers\n│   ├── flowmux-state/      Persistent workspace/session state on disk\n│   ├── flowmux-terminal/   libghostty-oriented terminal backend + PTY env helpers\n│   ├── flowmux-browser/    WebKitGTK 6.0 browser surface + scriptable refs\n│   ├── flowmux-cookies/    Browser cookie/session import (libsecret + sqlite)\n│   ├── flowmux-notify/     OSC 9/99/777 parser + libnotify D-Bus sender\n│   ├── flowmux-ipc/        Unix-socket IPC (cmux socket-API compatible)\n│   ├── flowmux-daemon/     Background daemon orchestrating IPC and panes\n│   ├── flowmux-procmon/    PID-tree process / listening-port monitor\n│   ├── flowmux-ssh/        SSH workspaces via russh\n│   ├── flowmux-vcs/        Git/PR sidebar integration\n│   ├── flowmux-cli/        `flowmuxctl` helper for CLI subcommands\n│   └── flowmux/            GTK4 + libadwaita main app and public `flowmux` binary\n├── packaging/{debian,flatpak}/  Distro packaging metadata\n├── resources/             .desktop file, icons, screenshots, themes\n├── LICENSE                GPL-3.0-or-later (verbatim from gnu.org)\n├── THIRD_PARTY_LICENSES.md  Third-party dependency license inventory\n└── NOTICE                 Copyright + attribution\n```\n\n## Build prerequisites (Ubuntu 24.04 native)\n\n```bash\nsudo apt install \\\n    build-essential pkg-config \\\n    libgtk-4-dev libadwaita-1-dev \\\n    libwebkitgtk-6.0-dev libssl-dev \\\n    libssh2-1-dev libdbus-1-dev\n# For the patched VTE build (see \"Patched VTE\" below) — meson/ninja plus the\n# VTE source-build dependencies not already pulled in by libgtk-4-dev:\nsudo apt install \\\n    meson ninja-build \\\n    liblz4-dev libpcre2-dev libfribidi-dev libicu-dev libgnutls28-dev\n# rustup (Rust 1.93+) and Zig 0.15.x required; Zig builds the vendored\n# libghostty-vt used by the terminal pane.\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n```\n\n### Optional — full media playback in tab browser\n\nWebKitGTK decodes media via GStreamer. Without these plugins pages still load,\nbut YouTube / Twitch / `\u003cvideo\u003e` may stall, miss subtitles, or fail on DRM:\n\n```bash\nsudo apt install \\\n    gstreamer1.0-plugins-good \\\n    gstreamer1.0-plugins-bad \\\n    gstreamer1.0-plugins-ugly \\\n    gstreamer1.0-libav\n```\n\n## Build\n\n```bash\ncargo build --release --workspace\n```\n\nProduces two binaries under `target/release/`:\n\n- `flowmux` — GTK4 GUI; also forwards CLI subcommands to `flowmuxctl`.\n- `flowmuxctl` — CLI helper invoked by the GUI and by agent hooks.\n\nFor development:\n\n```bash\ncargo run -p flowmux           # debug GUI\ncargo check --workspace        # type-check everything\n```\n\n### Patched VTE (drag-selection in agent TUIs)\n\nUpstream VTE drops a text selection the instant the foreground application\nrewrites the cells under it. TUIs such as Codex and Claude Code repaint their\nUI continuously, so a drag-selection in their pane vanishes on the next frame —\nand VTE exposes no public API to disable that behaviour. flowmux therefore\nlinks a small patched copy of VTE (`packaging/vte-patches/`) that keeps the\nselection anchored across output. The system libvte other apps use is left\nuntouched.\n\nFor a native install, build the patched VTE and link flowmux against it in one\nstep (needs the `meson`/`ninja`/`liblz4-dev`/… packages listed in the\nprerequisites):\n\n```bash\nscripts/install-host.sh        # builds patched VTE → builds flowmux → installs\n```\n\nThis installs the patched VTE to `~/.local/flowmux-vte` and the binaries to\n`~/.local/bin` and `~/.cargo/bin`, baking a RUNPATH so the GUI loads the\npatched library at runtime. The Flatpak build (Ubuntu 22.04) applies the same\npatch automatically. A plain `cargo build --release --workspace` still works\nbut links the system VTE, so drag-selection will not survive a repaint.\n\n## Verify \u0026 repair\n\nflowmux wires into host pieces: agent SKILL files, agent hooks, the browser\ndata dir, host browsers for the cookie importer, and the daemon socket.\n\n```bash\nflowmux doctor   # read-only audit; non-zero exit if anything needs fixing\nflowmux fix      # re-install / refresh what doctor flagged\n```\n\n`doctor` prints one row per check with a status badge (`ok` / `fix` / `warn` /\n`info`); `NO_COLOR=1` or piping disables colour. Run it after a flowmux\ninstall/upgrade and after installing a new agent. `fix` is idempotent and\nnever clobbers hand-edited entries lacking the flowmux marker. Add `--json` to\neither for machine-readable output.\n\n## Ubuntu 22.04 (jammy)\n\n22.04 lacks the GTK/WebKit versions for a native build, so ship via Flatpak\n(GNOME 48 runtime). Host tools stay visible through `flatpak-spawn --host`,\nand GStreamer plugins are bundled, so no extra host packages are needed.\n\n```bash\nsudo apt install flatpak flatpak-builder\nflatpak remote-add --if-not-exists --user flathub https://flathub.org/repo/flathub.flatpakrepo\nflatpak install -y --user flathub org.gnome.Platform//48 org.gnome.Sdk//48\nflatpak-builder --user --install --force-clean build-flatpak packaging/flatpak/com.flowmux.App.yml\nflatpak run com.flowmux.App\n```\n\nBlank browser tabs (`EGL_BAD_PARAMETER`) mean the host GL stack is too old for\nthe sandbox Mesa — disable WebKit's GPU path:\n`flatpak override --user --env=FLOWMUX_WEBKIT_HW_ACCEL=never com.flowmux.App`.\n\n## License\n\nGPL-3.0-or-later. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).\nContributions accepted under the same license; see\n[`CONTRIBUTING.md`](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsuya%2Fflowmux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsuya%2Fflowmux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsuya%2Fflowmux/lists"}