Thanks for helping make Luvus better. Bug fixes, documentation, tests, and new features are all welcome.

Unless explicitly stated otherwise, contributions submitted for inclusion in Luvus are provided under the Apache License, Version 2.0.

Small fixes can go directly to a pull request. For a large UI, architecture, or behavior change, open an issue first so we can agree on the direction before you spend time building it.

Functionality around Luvus, such as panels, integrations, and automations, may fit better as a module than a core change. See MODULE-GUIDE.md. Modules live in separate repositories, can use any language, and need no SDK.

Luvus requires Rust 1.88 or newer. Fork the repository on GitHub, then clone your fork and create a focused branch:

git clone https://github.com/RizRiyz/luvus.git
cd luvus
git switch -c fix/short-description
cargo build

Debug builds keep their state in ~/.luvus-dev/, separate from your installed Luvus session in ~/.luvus/.

For the quickest local UI run:

cargo run -- --local

For changes involving the client, server, sockets, or keyboard input, test the real debug client and server from a normal terminal outside your production Luvus session:

cargo run -- server restart
cargo run

Running a debug Luvus inside an older production Luvus pane can hide input bugs because the outer process handles the keys first.

• Keep changes focused. Solve one user-facing problem at a time. Keep unrelated formatting, cleanup, and refactors separate.
• Performance first. Avoid per-frame allocations, unbounded scans, and blocking work on the event loop. Shell commands and filesystem scans belong on worker threads.
• Keep state predictable. Application state is separate from runtime and IO. Preserve the single event loop and follow the patterns around the code you edit.
• Preserve user sessions. Development and tests must not modify production state, close active panes, or connect to the production socket unexpectedly.
• Keep behavior cross-platform. CI builds Luvus on Linux, macOS, and Windows. Keep operating-system code in platform.rs behind cfg gates when possible.
• Update related documentation. CLI, API, configuration, or visible behavior changes should update the matching public documentation.
• Keep CLI translations complete. Command names, flags, JSON, and UHP stay canonical. Add human CLI text to src/i18n/cli.rs with all eight language values, preserve placeholders and literal user data, and run the focused CLI localization tests. Do not add a partial English fallback for a registered language.

Add a regression test for behavior changes when practical. Use cargo test <substring> while developing to run one focused test.

Before submitting your change, run the same checks as CI:

cargo fmt --all --check
cargo clippy --all-targets -- -D warnings
cargo test --locked

UI tests render into an off-screen buffer, and many terminal tests exercise real PTYs without requiring an interactive terminal. Test visible changes manually, measure performance changes before and after, and test platform-specific code on the affected platform when available.

Lifecycle tests must isolate the state home and clear inherited socket/session selectors before spawning a server. Use an explicit shell when testing process behavior rather than shell integration. Bound startup and socket waits, check early child exits, retain a bounded excerpt of failure diagnostics, and use a child-handle cleanup guard. Tests that change process-global configuration must hold persist::test_env(...) for their entire lifetime.

Detailed terminal-history inspection has an opt-in, in-process benchmark:

cargo test --locked history_inspection_benchmark -- --ignored --nocapture

It reports three warmed trials for 1, 20, and 50 engines with 10,000 retained rows each. These are engine-accounting timings, not end-to-end API latency or process memory measurements. Record the commit and build profile when comparing runs. Ordinary test runs do not execute this workload.

To isolate cold-history maintenance from ingestion, run:

cargo test --release --locked history_maintenance_benchmark -- --ignored --nocapture

This uses 80x24 engines with 10,000 retained rows, both printable text and per-cell RGB styling, and three trials per corpus. It reports total maintenance, turn count, and per-turn p95/p99/maximum lock-held work, not end-to-end input/scroll latency. Run separate live latency checks before changing maintenance scheduling, especially on Windows.

To check CLI/UHP responsiveness while configuration storage is locked (Unix):

cargo build --locked
python3 examples/uhp/terminal/io_responsiveness.py --luvus target/debug/luvus

This starts its own isolated development server, reports baseline and contended request timings, deliberately exercises the lock timeout, and verifies that retry persists the setting. It never attaches to an existing session. Timings are host measurements, not hard CI thresholds or proof of Windows/TUI rendering latency.

Use a detection manifest when an agent only needs identity and live-state recognition. Built-in session discovery, resume, fork, usage, or lifecycle integration belongs in one modular adapter under src/agent/<agent>/; do not spread new agent-name branches across the UI, CLI, IPC, or Settings.

The Adding Agent Support guide covers the descriptor fields, scoped interpreter packages, manifests, session and integration boundaries, registry entry, documentation parity, and required cross-platform tests. Detection must work without installing a skill or hook, and optional integrations must preserve unrelated user configuration.

Use concise Conventional Commit messages:

fix(input): preserve navigation modifiers on Windows
feat(cli): add pane move command
perf(render): avoid repeated frame allocations
docs: clarify module setup

Luvus squash-merges pull requests, so follow-up commits during review are fine. You do not need to rebuild a perfect commit history before submitting changes.

Maintainers may ask for a regression test, a smaller scope, or another compatibility check. Keep review discussions focused on the behavior being changed and push follow-up commits to the same branch.

Include clear reproduction steps, your OS and terminal, and the output of:

luvus server status
luvus doctor

Screenshots and the name of the running agent are often helpful. For security issues, follow SECURITY.md and do not open a public issue.