Getting Started

Getting Started Mochi is currently an experimental Linux desktop companion under active development.

This guide covers development checkout setup rather than a polished end-user installer.

Supported development target Primary environment:

Fedora Linux GNOME Wayland session Python 3.11+ Mochi may use XWayland for behavior that native GNOME Wayland restrictions make difficult.

System packages On Fedora:

sudo dnf install python3 python3-gobject gtk4 gtk4-layer-shell Package names may differ on other distributions.

Clone the repository git clone https://github.com/miflow13/mochi-desktop.git cd mochi-desktop Install development checkout python3 -m pip install -e . This installs the Python package in editable mode so source changes are reflected without rebuilding the package after every edit.

Launch Mochi mochi Useful modes:

mochi --debug mochi --reset-position mochi --preview-animations Run tests python3 -m unittest discover -s tests -v For a wider validation pass:

python3 -m compileall -q src tests python3 -m unittest discover -s tests -v git diff --check Build a wheel python3 -m pip wheel . --no-deps --no-build-isolation -w /tmp/mochi-wheel When animation assets or packaging rules change, inspect the wheel contents before treating the build as valid.

Current user interactions The project is evolving quickly, but the intended public-alpha interaction model centers on:

idle/breathing click reactions double-click heart reaction right-click context menu walking sleep/wake pickup/drag/drop ambient and explicit emotes such as computer/typing See Interaction Core for the detailed state model.

Context menu terminology The menu opened by right-clicking Mochi is the context menu.

Use this term consistently in issues, code comments, and documentation.

Wayland notes Wayland intentionally restricts arbitrary synthetic input and certain window-management behavior.

Mochi should work within those constraints rather than requiring invasive permissions.

Normal runtime should not request:

remote desktop screen sharing screen recording synthetic input control Development automation may need separate desktop-control permissions for testing, but those are not part of Mochi's runtime design.

Pixel-art expectations If Mochi looks blurry, inspect rendering configuration before editing the art.

Runtime rules:

128×128 logical frame nearest-neighbor scaling bottom-center anchoring transparent RGBA assets no bilinear smoothing See Animation and Art Pipeline.

If Mochi becomes unresponsive Record the exact sequence that caused it.

For example:

IDLE → RIGHT CLICK → WALK → DRAG → INPUT FREEZE Then consult Troubleshooting and Regressions and the repository REGRESSION_WATCHLIST.md.

Current release status Mochi is not yet presented as a stable public release. The project is currently focused on interaction-core stability and public-alpha readiness.

Do not assume package metadata, README status text, and local development branches always advance at the same moment; verify the branch/commit you are testing.