Skip to content

AGENTS.md

Latest commit

 

History

History
138 lines (100 loc) · 4.81 KB

AGENTS.md

File metadata and controls

138 lines (100 loc) · 4.81 KB
Raw

AGENTS.md - Limux contributor guide

This file is for agents editing the Limux source tree. Do not confuse it with the AGENTS.md generated by limux agent-team inside a user's shared cwd; that generated file documents the runtime agent message protocol.

What Limux Is

Limux is a GTK4 + libadwaita terminal workspace manager for Linux. Terminal rendering is embedded Ghostty (libghostty.so), and external automation drives the running app through a Unix socket and the limux-cli crate.

Crates

Crate Role
limux-protocol JSON request/response envelope types.
limux-core In-process command dispatcher and state engine. Core IDs are u64.
limux-control Unix socket path, auth, framing, and standalone control server.
limux-ghostty-sys Raw FFI bindings to ghostty/include/ghostty.h.
limux-host-linux GTK host binary, window/pane/tab UI, terminal integration, live control bridge.
limux-cli User-facing CLI and agent integration commands.

Binaries

Local debug builds produce two important binaries:

  • target/debug/limux is the GTK host from limux-host-linux; it only accepts GTK/GApplication flags.
  • target/debug/limux-cli is the CLI; use this for subcommands such as identify, agent-team, notify, read-screen, and send.

Installed packages expose limux as the CLI. Running installed limux with no arguments launches the private host binary (limux-host) from libexec.

cargo build -p limux-cli --bin limux-cli
./target/debug/limux-cli --help

Quality Gate

The canonical check is:

./scripts/check.sh

It runs cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, and cargo test --workspace. Run narrower checks while iterating:

cargo check -p limux-host-linux
cargo test -p limux-cli
cargo check --workspace

For live agent/control-socket behavior, prefer the maintained smoke harness:

./scripts/xvfb-smoke-test.sh
LIMUX_SMOKE_PROFILE=debug ./scripts/xvfb-smoke-test.sh

Runtime Control Path

There are two control-server paths:

  • Production GUI path: limux-cli talks over the runtime Unix socket to the embedded GTK bridge in rust/limux-host-linux/src/control_bridge.rs.
  • Standalone/test path: limux-control-server uses limux_core::Dispatcher and ControlState without the GTK host.

When fixing user-visible CLI behavior, verify the production GTK bridge path, not only the standalone dispatcher. The live bridge supports workspace, pane, surface, terminal send/key/read/health, notification, and terminal pane-create commands. Browser command bridge parity remains separate work; check docs/cmux-parity-plan.md before changing agent or browser automation.

IDs And Env

GTK and core IDs are intentionally different:

  • GTK host: workspace id is String, pane id is u32, tab id is a UUID String, and surface id is "<pane_id>:<tab_id>".
  • Core dispatcher: workspace/surface ids are u64, encoded externally as handles/refs.

Every Limux-spawned terminal inherits:

  • LIMUX_WORKSPACE_ID
  • LIMUX_SURFACE_ID
  • LIMUX_PANE_ID
  • LIMUX_TAB_ID
  • LIMUX_SOCKET

New CLI subcommands should follow the existing pattern: explicit flags first, then LIMUX_* env fallbacks.

Pane And Terminal Gotchas

Panes do not own workspace state. PaneCallbacks in rust/limux-host-linux/src/pane.rs is wired from the single construction site in window.rs; add host-level behavior there instead of reaching around the callback boundary.

For Ghostty terminal env vars, build short-lived CString storage and ghostty_env_var_s entries for the ghostty_surface_new call. Ghostty copies the strings into its own config arena, so no static lifetime or leaked storage is needed.

Agent Integrations

The CLI surface lives in rust/limux-cli/src/main.rs:

  • agent_launch_command maps supported agents to launch commands.
  • run_agent_team splits the current workspace and launches peers.
  • build_agents_md writes the generated runtime protocol file.

Keep limux agent-team --dry-run working without a host. For live behavior, the headless Weston smoke script exercises terminal surface health, input and screen readback, bridge routing, generated AGENTS.md, and session restart.

Repository Rules

  • Treat vendored ghostty/ as read-only from the Limux layer; use the C API.
  • Keep command metadata, flags, validation, and policy in one canonical path.
  • Prefer small domain modules over monolithic files.
  • Do not commit generated artifacts, build output, or caches.
  • Add regression tests when fixing behavior or moving risky logic.
  • Treat clippy findings as required maintainability work.

Useful references:

  • Roadmap/current bridge status: docs/cmux-parity-plan.md
  • Maintainability rules: docs/maintainability.md
  • CLI usage: README.md and ./target/debug/limux-cli --help