limux CLAUDE.md

CLAUDE.md — project context for Claude Code

Short, Claude-oriented companion to AGENTS.md. For architecture and the full CLI surface, read AGENTS.md. For roadmap status, read docs/cmux-parity-plan.md.

What is this project?

Limux is a GTK4 + libadwaita + libghostty terminal workspace manager for Linux, ported from manaflow-ai's macOS cmux. It exposes a Unix-socket control API so coding agents can drive the GUI from a terminal inside a limux workspace.

Before editing

Run the quality gate before and after your changes:

./scripts/check.sh   # fmt --check, clippy -D warnings, test --workspace

Heads-up: as of this writing one test is failing (cli_arg_tests::hook_session_id_falls_back_to_transcript_stem, assertion at rust/limux-cli/src/main.rs:3893). Don't assume a clean baseline — run the gate first to see the current state.

The two-binary gotcha

• target/debug/limux — the GTK app (limux-host-linux). Only understands GTK flags. Installed users get this as limux-host under libexec.
• target/debug/limux-cli — the CLI (limux-cli), which implements agent-team, notify, hooks setup, send, read-screen, etc. Installed users get this as limux.

Run ./target/debug/limux-cli --help for the full subcommand list — treat it as the source of truth, not this file.

Finding code (anchors, not line numbers)

The crates churn, so search by symbol:

rg -n "fn agent_launch_command|fn build_agents_md" rust/limux-cli/src/main.rs
rg -n "\"agent-team\" =>"                          rust/limux-cli/src/main.rs
rg -n "PaneCallbacks \{"                           rust/limux-host-linux/src/window.rs

Task	Crate / module
New agent in agent-team	agent_launch_command in rust/limux-cli/src/main.rs
Generated AGENTS.md template	build_agents_md in rust/limux-cli/src/main.rs
New CLI subcommand	dispatch match in rust/limux-cli/src/main.rs
GUI bridge routing	rust/limux-host-linux/src/control_bridge.rs
Full-vocabulary control (no GUI)	limux-core::Dispatcher + ControlState
Pane / surface UI state	rust/limux-host-linux/src/window.rs (PaneCallbacks)
Terminal IME / dead-key / compose	rust/limux-host-linux/src/ime/ (state.rs state machine, routing.rs decide_routing / is_compose_initiator, contexts.rs GTK + ghostty wiring)
Agent-hook installers + templates	hooks/ + limux hooks setup
Packaging (AppImage / AUR)	scripts/package.sh, scripts/appimage-webkit.sh, PKGBUILD.template