Real-device Android automation for agents and CI

Android automation that leaves evidence.

Luotsi keeps the control loop on your machine: inspect real Android devices, run governed scenarios, and replay failures from durable artifacts after the session ends.

Install Luotsi Understand the output Replay failures

Open sourceADB-firstJSONL sessionsReplay artifacts

Beyond screen sharing Live view is one surface in a workflow that also emits machine-readable state, reports, and replay bundles.

Host-side by design Policy, orchestration, diagnostics, and artifacts stay on the engineer, agent, or CI machine.

$ luotsi inspect --device pixel-lab-3
session: real-device JSONL
actions: tap_text, wait_visible, screenshot

$ luotsi replay packet --artifacts ./artifacts/smoke-run
packet: run-summary.json, run-summary.md
next: focused triage command

Live mirror Physical Android device

Buggy Controller running on a real Android device during a Luotsi session.

Mode Host-driven

Device Physical Android

Evidence Replay-ready

Inspect JSONL

{"type":"session_started","session_id":"...","started_at":"..."}
{"type":"screen_snapshot","session_id":"...","state":{"captured_at":"...","element_count":18,"elements":[...]}}
{"type":"command_result","id":"2","command":"tap_text","ok":true}

Replay bundle

artifact_root: ./artifacts/smoke-run
guide: replay packet writes run-summary.json and run-summary.md
next: luotsi replay packet --artifacts ./artifacts/smoke-run

Real device A physical Android screen under test, not a browser mock.

Structured sessions Inspect and view emit machine-readable state instead of terminal prose.

Replay artifacts Every run leaves behind a trail you can inspect after the session ends.

Positioning

Three questions the tool has to answer.

Luotsi is useful when the answer needs to be a machine-readable device session and a durable artifact trail, not just a live screen or a pass/fail bit.

Can my agent inspect and act on a real Android device?

Yes. Start an inspect session, read JSONL screen snapshots and deltas, then send JSON commands such as wait_visible, tap_text, type_text, screenshot, and exit over stdin.

luotsi inspect --device <serial> Open the agent loop example ->

Can CI run this and leave useful evidence?

Yes. Run scenario playbooks from the host, claim lab devices when needed, and keep JSON reports, JUnit, screenshots, hierarchy captures, logcat, telemetry, and governance signals under one artifact root.

luotsi run --path scenarios --device <serial> --report-junit junit.xml Open CI device lab workflows ->

Can I debug the failure after the device is gone?

Yes. Replay commands read saved artifacts, summarize the run, build capsules, scrub timelines, query semantic graphs, cluster repeated failures, and draft follow-up scenarios.

luotsi replay packet --artifacts ./artifacts/<run-id> Open replay and artifacts ->

Start fast

Get to a real device workflow in five minutes.

Install from releases, run doctor once, then jump into the workflow that matches the job.

Windows

Run the release installer, then let doctor verify the device path before you burn time on setup drift.

iex (irm https://github.com/digablesolutions/luotsi/releases/latest/download/luotsi-install.ps1)
luotsi doctor --device <serial> --fix

macOS / Linux

Use the shell installer, then validate the same first-run path against the attached device.

curl -fsSL https://github.com/digablesolutions/luotsi/releases/latest/download/luotsi-install.sh | sh
luotsi doctor --device <serial> --fix

First useful command

Run the environment check before you spend time on adb, helper, or decoder edge cases.

luotsi doctor --device <serial> --fix

Verifies adb visibility and device readiness.
Checks live-view prerequisites.
Stages helper and decoder assets Luotsi owns when possible.

Open the quickstart ->

Choose a workflow

Pick the route that matches the job.

Once a device is attached, most work falls into one of these three paths.

Use inspect

Give an agent device state Use inspect when an agent needs JSONL snapshots, command results, and screen deltas from a real Android device. luotsi inspect --device <serial>

Use run

Run CI on real devices Use run when the flow belongs in a checked-in scenario with reports, claims, and a durable artifact root. luotsi run --path scenarios --device <serial>

Use replay

Debug after the session Use replay when the device is gone but the artifacts still need to explain what happened. luotsi replay packet --artifacts ./artifacts/<run-id>

Go deeper

Docs organized by intent, not by dump.

Start from the bucket that matches the moment: setup, run, or debug.

Start Here

Get from install to a stable device session before you debug the app.

Run Workflows

Choose the surface that matches the job: operator control, structured exploration, or repeatable runs.

Evaluate And Use Cases

Start from the page that matches the evaluation question or workflow you are trying to standardize.

Debug And Integrate

Use the artifact layer and command surface when the question is no longer just how to start.

For Engineering Leads AI Agent Workflows Agent Loop Example Architecture Subsystems Contribution Guide Releases GitHub