Luotsi

Luotsi is a host-driven Android device automation and replay CLI for AI agents and CI. It talks to real Android devices over ADB, returns structured JSON/JSONL contracts, and preserves replayable evidence so a run can be inspected after the device is gone.

Use Luotsi when you need real-device state, lab-coordinated execution, and artifact-backed triage instead of a browser mock, ad hoc adb script, or heavyweight device-farm control plane.

Public docs: digablesolutions.github.io/luotsi

Start Here

• First five minutes
• Installation
• Quickstart
• AI agent workflows
• Live view
• Scenario playbooks
• Replay and artifacts
• CLI command groups

Why Luotsi

• Real devices, structured contracts. Commands return JSON envelopes; inspect and view --json expose JSONL streams for agents and host-side tooling.
• Replay-first triage. Runs preserve screenshots, hierarchies, logcat, telemetry, timelines, reports, and replay bundles.
• CI and lab discipline. Device readiness, claims, queues, quarantine, health, JUnit, and governance signals share the same CLI surface.
• Host-driven by design. Orchestration, policy, and diagnostics stay on the engineer, agent, or runner machine while the Android helper remains thin.

Install

Windows:

iex (irm https://github.com/digablesolutions/luotsi/releases/latest/download/luotsi-install.ps1)

macOS / Linux:

curl -fsSL https://github.com/digablesolutions/luotsi/releases/latest/download/luotsi-install.sh | sh

Verify:

luotsi --version
luotsi version
luotsi devices

For installer options, manual archives, source builds, and first-run setup, use the Installation guide.

First Run

luotsi quickstart --human
luotsi doctor
luotsi doctor --device <serial> --fix

If you already know the target app and device:

luotsi quickstart --device <serial> --package <app.id> --artifacts artifacts/first-run --write-json --write-markdown
luotsi doctor --device <serial> --package <app.id> --fix

Main Workflows

Need	Start with	Docs
Human/operator device loop	luotsi view --device <serial>	Live view
AI agent exploration	luotsi inspect --device <serial>	AI agent workflows
Repeatable scenario CI	luotsi scenario-init, luotsi scenario-validate, luotsi run	Scenario playbooks
Evidence review after a run	luotsi replay packet --artifacts <artifact-root>	Replay and artifacts
Shared lab execution	luotsi run --claim-device --claim-wait-sec 60 ...	Shared lab operations
Android CLI Journey handoff	luotsi journey-intake init ...	Evidence-backed Android Journeys

Command Surface

The maintained command reference lives in the docs site: CLI command groups.

Common first commands:

luotsi devices
luotsi screen-state --device <serial>
luotsi inspect --device <serial>
luotsi scenario-init --file scenarios/smoke.json --name smoke
luotsi scenario-validate --path scenarios
luotsi run --path scenarios --device <serial> --report-junit junit.xml
luotsi artifacts verify <artifact.zip> --require-lab-safe --sha256 <digest>

Output Model

Normal commands return one JSON envelope by default. Human output is available with --human or --console-output human; JSONL sessions are used by inspect and view. Artifact roots are durable evidence, and luotsi replay packet --artifacts <artifact-root> writes the first-minute investigation packet before replay commands reopen them later.

Read the full model in Output envelopes.

Build From Source

The repo is pinned to .NET SDK 10.0.300 in global.json.

dotnet build Luotsi.sln
dotnet test Luotsi.sln
dotnet run --project Luotsi.Cli -- devices

AI agents working in this repository should start with AGENTS.md. Contributors should use the Contribution guide.