# Chrome Remote Desktop Instructions

Instructions that are relevant when working with the Chrome Remote Desktop (aka.
CRD and chromoting) host binaries, or code located in //remoting.

While code for the Chrome Remote Desktop host lives in the Chromium repo (this
repo), it is mostly an independent product, separate from Chrome, except for
ChromeOS, where the IT2ME native messaging host is part of the Chrome binary.

## Relevant Documentation

When working on specific domains, **you MUST use the `read_file` tool to load
these documents:**
*   **Testing:** See `docs/testing.md` if you are writing, modifying, or
    debugging tests.

*   **Architecture & IPC:** See `docs/architecture.md` if you are modifying host
    architecture, IPC, or adding/removing processes.

*   **Native Client:** See `client/GEMINI.md` if you are working on the native
    client code (ChromeOS/Boca).

*   **D-Bus Interface Generation:** See `host/linux/dbus_interfaces/GEMINI.md`
    if you need to generate missing D-Bus headers for Linux.

*   **Linux Host Implementation Details:** See `host/linux/GEMINI.md` for
    information about Linux-specific libraries like GVariant and D-Bus
    wrappers.

## Security Context

CRD host processes often run with high privileges (e.g., `SYSTEM` on Windows,
`root` on Linux) while receiving input from the network. You **MUST** be
extremely careful with memory safety, bounds checking, and input sanitization.
Correctness is critical to prevent security vulnerabilities.

## Platform Context

Code in `//remoting` is built for many platforms. The file suffix often
indicates conditional compilation:
* `_chromeos.cc`: ChromeOS specific.
* `_mac.cc` / `_mac.mm`: MacOS specific
* `_posix.cc`: Linux and MacOS.
* `_win.cc`: Windows specific.
* `_wayland.cc`: Linux/Wayland specific.
* `_x11.cc`: Linux/X11 specific.

*   **Cross-Platform Testing Limits:** Always be aware of the host OS you are
    currently running on (e.g., Linux). Do **NOT** attempt to build or run tests
    for a different platform locally (e.g., do not try to build Mac-only code or
    run ChromeOS-specific tests on a Linux workstation).
*   **Try-Bots (`git cl try`):** If you modify code for a platform that cannot
    be tested locally, stop and inform the user. Suggest using `git cl try` to
    verify the changes on the appropriate CQ bots. Common try-bots include:
    `linux-rel`, `mac-rel`, `win-rel`, and `chromeos-rel`. Example command: `git
    cl try -B luci.chromium.try -b mac-rel`. After triggering a try-bot, pause
    and wait for the human to provide the failure logs. Do not attempt to poll
    `git cl status` or download massive raw logs via `bb` unless explicitly
    asked.

## Coding Standards

*   **Finch & UMA:** Chrome Remote Desktop does **NOT** use Finch
    (`base::FeatureList`) or UMA (`base::UmaHistogram*`) for non-ChromeOS
    platforms. Do not introduce these into the codebase unless you are
    specifically modifying ChromeOS-only code.
*   **Headers:** Always check headers to add missing ones and remove obsolete
    headers.
*   **Containers:** Consult `base/containers/README.md` when choosing a
    container (list, map, etc.).
*   **std::optional:** Prefer `has_value()` for boolean testing and `*` for
    dereferencing.
*   **Logical Chunks:** Break work into logical chunks. Perform a build and test
    cycle after each chunk to prevent compounding failures.

## Code Review and CL Structure

Our team strongly prefers small, easily reviewable CLs (Changelists).
*   **Separation of Concerns:** Do not mix refactoring or reformatting with new
    feature development in the same CL.
*   **Pre-work CLs:** If a task requires refactoring/reformatting existing code
    to support a new feature, do this *first* in a dedicated "pre-work" CL. Give
    it a clear CL description explaining *why* the refactoring is being done
    (e.g., "Prep work for feature X").
*   **Proactive Communication:** If you (the agent) realize a request will
    involve a large diff, **pause and ask the human upfront**. Ask if they want
    one large CL or if they prefer you to manage a chain of smaller, focused CLs
    to make the work easier to review later.

## Automated Review via MAGI Protocol

Before finalizing any task or uploading a CL in `//remoting`, you **MUST**
invoke the `magi-mode` skill (defined in `//agents/skills/magi-mode/SKILL.md`)
to run a multi-agent verification loop.

*   **Execution:** Activate the `magi-mode` skill. The protocol handles review
    and verification via its specialized sub-agents.
*   **Domain-Specific Review Criteria:** When initiating the review, you MUST
    instruct the MAGI agents to include the following `//remoting`-specific
    review criteria in their checklist/context:
    1.  **Memory safety in high-privilege processes:** Check for potential
        Use-After-Free (UAF) and out-of-bounds errors, especially in host
        components running as `SYSTEM` or `root`.
    2.  **Platform-specific logic bugs:** Ensure proper use of
        `#if BUILDFLAG(...)` guards and correct platform suffix compilation.
    3.  **Adherence to the 'Small CLs' mandate:** Verify the change size is
        minimal and focused. Suggest split points if the CL is large.
    4.  **GEMINI.md compliance:** Confirm all changes adhere strictly to the
        rules defined in `//remoting/GEMINI.md`.
*   **Path Selection:** The protocol automatically selects `FAST_PATH` for
    low-ambiguity tasks or `RIGOR_PATH` for complex, high-stakes, or
    security-sensitive changes.
*   **Checks Integrated:** The verification loop automatically runs and
    integrates the required repository checks, including presubmits
    (`git cl presubmit -u --force`), dependency checks
    (`gn check {OUT_DIR} //remoting/*`), and unit tests
    (`remoting_unittests`).

## Workflow Efficiency (Optimizing for Wall-Clock Time)

When executing tasks, optimize for **total human wall-clock time** rather than
just the fastest individual command execution. Every shell command requires
human approval via the CLI, which causes expensive context switches for the
developer.

*   **MAGI Design Debates:** For highly complex, high-stakes, or ambiguous
    architectural problems, invoke the `magi-mode` skill *before* starting
    implementation. This triggers a multi-agent scoping debate (Stage 1 & 2)
    to explore security, performance, and maintainability trade-offs and
    establish design consensus.
*   **Batch Commands:** Combine related shell commands using `&&` whenever
    logical. For example, instead of running a build and then asking to run a
    test, combine them:
    `autoninja -C {OUT_DIR} {TARGET} && tools/autotest.py...`.
*   **Parallel Execution:** Use the `wait_for_previous: false` parameter in tool
    calls to perform independent reads or searches in parallel within a single
    turn.
*   **Minimize Interruptions:** Gather all necessary information (e.g., listing
    directories and reading related headers) in a single turn. Avoid asking the
    human for permission at every micro-step; only pause for intervention when a
    step is destructive, risky, or requires a strategic decision.

IMPORTANT: When making suggestions for CRD code changes, make sure they are
actually relevant to CRD. For example, code changes outside of //remoting
usually aren't relevant.

## Code Health & Modernization

`//remoting` contains legacy code (10+ years old) that may not align with modern
Chromium standards or may duplicate functionality now available in `//base`.

*   **Proactive Observation:** If you notice code that is significantly out of
    date, or a `/remoting/base` utility that could be replaced by a standard
    `//base` equivalent, **flag it to the human in the chat**.
*   **TODOs:** Do NOT add `TODO` comments for code health improvements unless
    explicitly asked by the human.
*   **Judgment:** Prioritize the task at hand. Only suggest modernization if it
    directly relates to the area you are already modifying or if it
    significantly improves the safety/readability of your new changes.

## Knowledge Preservation & Documentation

To maintain context efficiency, **this root `GEMINI.md` MUST remain lean.** It
should only contain critical safety rules, high-level workflow mandates, and
routing pointers.

If you discover a complex architectural pattern, a non-obvious dependency, or a
critical threading constraint (especially one that differs from standard
Chromium conventions):
1. **Verify your discovery:** Ensure your understanding is correct by reading
   the relevant source code and headers.
2. **Broad/Global Knowledge:** Do **NOT** add deep technical references,
   architectural explanations, or domain-specific guides directly to this root
   file. Instead, create or update a specific Markdown file in the `docs/`
   directory (e.g., `docs/audio.md`, `docs/style.md`).
   * When creating a new doc, add a single bullet point to the
     `## Relevant Documentation` section at the top of this file, instructing
     future agents on *when* to load it.
3. **Local Knowledge:** If the discovery applies only to a specific
   sub-directory of `//remoting`, create a new `GEMINI.md` file in that
   sub-directory or update the existing one. Focus on "Why" and "Architecture,"
   not "What."
4. **Be concise:** All system instructions and documentation should be
   high-signal and low-noise to save tokens for future agents.

# Validation & Pre-Commit

Whenever you make any code or build changes in `//remoting`, you **MUST** run
the following:

1.  **Code Formatting:** Run `git cl format` to ensure all changes follow
    Chromium style.
2.  **Dependency Check:** Run `gn check {OUT_DIR} //remoting/*` to ensure no
    circular or missing dependencies were introduced.
3.  **Unit Tests:** Run `remoting_unittests` to verify your changes. You can use
    `tools/autotest.py --run-all -C {OUT_DIR} remoting/` to run all tests in the
    remoting directory.
4.  **Static Analysis:** Run `git cl presubmit -u --force` after you have
    finished all other validation steps.

### Common Build Targets

*   **Debug binaries** are preferred by default.
*   `remoting_all`: Build everything related to remoting.
*   `remoting_unittests`: Run remoting unit tests.
*   `remoting_dev_me2me_host`: Build a set of targets for running the host
    locally.
*   `remoting_me2me_host`: The Me2Me host binary.
*   `remoting_native_messaging_host`: Native Messaging host for Me2Me.
*   `remote_assistance_host`: Native Messaging host for It2Me.