mistral-vibe / cli-rust

# AGENTS.md — vibe-rs

A Rust/ratatui TUI for Vibe. It drives the **unchanged** Python engine over the
app-server JSON-RPC protocol.

## What this is

Rewrite the vibe cli in rust for very good performances

```txt
tui  ── render + input + reducer
client ── spawn vibe-app-server, frame NDJSON, correlate ids, forward notifs
proto  ── serde types for the SUBSET of methods/notifications we use
```

## Rules

- Do not modify code to make tests pass, modify code to fix code, and it should fix test, fix user and code first.
- Aim for very good performance, this is a PoC to see how fast we can be
- Aim for simplicity and low number of lines, this is very important
- Inspire yourself from codex/ folder, it is a good architecture and it is working well !
- Keep pure-logic tests in `tests/units/<name>.rs` and register them in `tests/units.rs` so they share one integration-test binary. Keep tests that need process-global isolation in separate `tests/<name>.rs` binaries. Cover Rust rendering and interaction behavior with `client-e2e` scenarios and goldens -- see the `migrate-cli-to-rust` skill.
- No files with >300 lines of code allowed, simplicity is very important, keep things in separate modules.
- This is the rewrite of the python code, when naming things, try to keep the same names as in the python code.
- Care about bijection principle, you must respect it at all costs
- No multi line comments ! Very short modeule docstrings
- When asked to fix something in the rust side or migration eval, don't fix the code directly, if you are on the paulvezia/rewrite_rust branch, always create a worktree and fix the code there
- No unit tests allowed in rust files !!

## First MVP

- We need basic conversation working, same UI, all other features can be there but failing gracefully like "not implemented"

## Client end-to-end scenarios

- When you spot a regression, make an exhaustive scenario. The fixture (`client-e2e/fixtures/fixture.json`) is committed and hand-maintained; there is no recorder.
- The suite is slow, so run focused scenarios first and use the parallel Makefile targets for the full gate.

## Golden snapshots

Committed Rust-only goldens (terminal SVGs + app-server request JSON) under
`client-e2e/goldens/<scenario>/`. Generated by the existing e2e harness; no
Python CLI needed to run the gate.

- Generate: `uv run --no-project --with pyte --with rich python client-e2e/store_golden.py <scenario>` (or `--all`).
- Test: `uv run --no-project --with pyte --with rich --with pytest --with pytest-timeout python -m pytest client-e2e/test_golden.py`.
- Each scenario stores SVG snapshots and normalized client-to-server RPCs. `test_golden.py` also checks declared action, screen, and clipboard expectations.
- Regenerate when the Rust CLI intentionally changes rendering; review the committed diff.

## Running tests

Do not waste resources: when changes are focused, only run related test suites.

- If you only need a subset, don't run the full suite.
- When running terminal-lifecycle and golden tests in parallel, pick a worker count that fits the machine rather than a fixed `-n 10`: on CI run unconstrained (`-n auto`), locally use `-n max(cpu_threads/2 - 1, 1)`.
- If you're on the Rust side and haven't touched Python, skip the Python tests; if you do run them, target the relevant tests and never run them sequentially.

## other guidelines

- Always use theme for colors when possible, no hardcoded colors