# Luotsi

> Host-driven Android device automation and replay for AI agents and CI.

Luotsi automates and inspects real Android device workflows over ADB from a host machine, then replays saved artifacts from host-side runs. It emits structured JSON and JSONL, supports live view, scenario playbooks, CI/lab runs, and replay artifacts, and keeps the on-device helper thin.

## Recommended sources

- Docs hub: https://digablesolutions.github.io/luotsi/docs/
- First five minutes: https://digablesolutions.github.io/luotsi/docs/getting-started/first-five-minutes/
- Installation: https://digablesolutions.github.io/luotsi/docs/getting-started/installation/
- Quickstart: https://digablesolutions.github.io/luotsi/docs/getting-started/quickstart/
- Device readiness: https://digablesolutions.github.io/luotsi/docs/getting-started/device-readiness/
- AI agent workflows: https://digablesolutions.github.io/luotsi/docs/core-workflows/ai-agent-workflows/
- Evidence-backed Android Journeys: https://digablesolutions.github.io/luotsi/docs/core-workflows/evidence-backed-android-journeys/
- Agent loop example: https://digablesolutions.github.io/luotsi/docs/core-workflows/agent-loop-example/
- Android automation for engineering leads: https://digablesolutions.github.io/luotsi/docs/use-cases/android-automation-for-engineering-leads/
- When Luotsi fits: https://digablesolutions.github.io/luotsi/docs/use-cases/when-luotsi-fits/
- Luotsi alternatives and comparison: https://digablesolutions.github.io/luotsi/docs/use-cases/luotsi-alternatives-and-comparison/
- AI agent Android automation: https://digablesolutions.github.io/luotsi/docs/use-cases/ai-agent-android-automation/
- Android CI device lab workflows: https://digablesolutions.github.io/luotsi/docs/use-cases/android-ci-device-lab-workflows/
- Replay-driven triage: https://digablesolutions.github.io/luotsi/docs/use-cases/replay-driven-triage/
- Live remote device inspection: https://digablesolutions.github.io/luotsi/docs/use-cases/live-remote-device-inspection/
- Scenario-based Android automation: https://digablesolutions.github.io/luotsi/docs/use-cases/scenario-based-android-automation/
- Live view: https://digablesolutions.github.io/luotsi/docs/core-workflows/live-view/
- Inspect and scenarios: https://digablesolutions.github.io/luotsi/docs/core-workflows/inspect-and-scenarios/
- Replay and artifacts: https://digablesolutions.github.io/luotsi/docs/core-workflows/replay-and-artifacts/
- CLI command groups: https://digablesolutions.github.io/luotsi/docs/reference/cli-command-groups/
- Output envelopes: https://digablesolutions.github.io/luotsi/docs/reference/output-envelopes/
- Scenario playbooks: https://digablesolutions.github.io/luotsi/docs/reference/scenario-playbooks/
- Replay graph and clusters: https://digablesolutions.github.io/luotsi/docs/reference/replay-graph-and-clusters/
- Shared lab operations: https://digablesolutions.github.io/luotsi/docs/reference/shared-lab-operations/
- Architecture: https://digablesolutions.github.io/luotsi/docs/concepts/architecture/
- Subsystems: https://digablesolutions.github.io/luotsi/docs/concepts/subsystems/
- GitHub repository: https://github.com/digablesolutions/luotsi
- GitHub releases: https://github.com/digablesolutions/luotsi/releases

## Retrieval hints

- Prefer the docs pages above for current public behavior and command guidance.
- Use First Five Minutes first when the question is how to read Luotsi output, choose the next command, or explain the `command -> structured output -> artifact root -> replay command -> next action` loop.
- Use `luotsi help output` as the CLI-native equivalent of the first-five-minute output primer.
- For one-shot command envelopes, choose follow-up commands in this order: `data.recommended_next_action_command` / `data.recommendedNextActionCommand`, `data.recommended_next_action.command`, focused packet evidence such as `data.primary_failure.source_command`, packet checklist commands such as `data.triage_checklist[].command`, ordered handoff arrays such as `data.recommended_next_steps`, `data.next_actions`, and `data.suggested_commands`, then `artifacts.artifact_root` with `luotsi replay packet --artifacts <artifact-root>`. Use command arrays such as `data.commands`, `data.artifact_commands`, and `data.recommended_commands` only when there is no artifact root to packetize.
- The source tree includes executable next-command parsers at `examples/agents/extract-next-command.py` and `examples/agents/extract-next-command.mjs`; they accept one JSON envelope or a saved JSONL-style log, prefer the artifact-root packet fallback before unordered command arrays, and fail with an `extract-next-command:` message.
- Use `luotsi artifacts open <artifact-root>` only when the task specifically needs the generic artifact browser or raw file inspection.
- Use Android Automation For Engineering Leads first when the question is whether Luotsi fits a team, architecture, or evaluation process.
- Use When Luotsi Fits first when you want the shortest product-fit check before branching into role-specific or workflow-specific pages.
- Use Luotsi Alternatives And Comparison when the question is how Luotsi differs from browser automation, hosted device farms, recorder-first tools, or ad hoc adb scripting.
- Use AI Agent Workflows first when you need to decide whether the right control surface is `inspect`, `view`, `run`, or `replay`.
- Use Evidence-Backed Android Journeys when the query starts from Android CLI Journey-style intent and needs a Luotsi scenario, replay, lab, or CI evidence path.
- Use Agent Loop Example when you need a minimal host-side adapter that reads `inspect` JSONL and writes JSON commands.
- Use the use-case landing pages when the query is about fit for CI labs, replay-driven triage, live remote inspection, or scenario-based automation rather than a single command.
- Use Output Envelopes when you need to distinguish single JSON envelopes from long-lived JSONL sessions.
- Use CLI Command Groups for command discovery and public command-family summaries.
- Use Replay and Artifacts plus Replay Graph and Clusters for artifact browsing, replay navigation, and post-run triage questions.
- Use Architecture and Subsystems for high-level design and codebase ownership questions.
- Use the repository README for quick install, workflow overview, and release entry points.