Skip to content

feat: AppGuide support #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
saikrishna321 wants to merge 4 commits into from
Closed

feat: AppGuide support #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dd52585
intial support for appguide
saikrishna321 Apr 20, 2026
ca82e23
feat: polish CLI output — fun spinner verbs, step counter, cleaner logs
saikrishna321 Apr 22, 2026
6d39a03
feat: AppGuide planner integration, long press support, vision and fl…
saikrishna321 Apr 22, 2026
5de29a3
fix: flows taps
saikrishna321 Apr 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,24 @@

### Features

* add action.yml at repo root for GitHub Marketplace publishing ([#20](https://github.com/AppiumTestDistribution/AppClaw/issues/20)) ([c007399](https://github.com/AppiumTestDistribution/AppClaw/commit/c007399fa670273058cd51e65f0fd68323ccb3be))
- add action.yml at repo root for GitHub Marketplace publishing ([#20](https://github.com/AppiumTestDistribution/AppClaw/issues/20)) ([c007399](https://github.com/AppiumTestDistribution/AppClaw/commit/c007399fa670273058cd51e65f0fd68323ccb3be))

## 1.0.0 (2026-04-16)

### Features

* integrate ai-sdk-ollama for LLM support and update configuration ([#9](https://github.com/AppiumTestDistribution/AppClaw/issues/9)) ([c6794d7](https://github.com/AppiumTestDistribution/AppClaw/commit/c6794d718a37ef690c09f5fb006c8994c78e361b))
* parallel testing support and screen recording for SDK ([#16](https://github.com/AppiumTestDistribution/AppClaw/issues/16)) ([7d14e7b](https://github.com/AppiumTestDistribution/AppClaw/commit/7d14e7b760c41783c61f1227c037e1b28d184a5c))
* strict playground tap matching, waitUntil pre-check, faster vision assert ([59b8c29](https://github.com/AppiumTestDistribution/AppClaw/commit/59b8c299bf20c9232d89bbbb4d93a9ef600cca2b))
* vision improvements — drag support, screenshot optimization, an… ([#7](https://github.com/AppiumTestDistribution/AppClaw/issues/7)) ([8cfbcb4](https://github.com/AppiumTestDistribution/AppClaw/commit/8cfbcb483fce0dec531ad8c21c8cd93d5743d62f))
- integrate ai-sdk-ollama for LLM support and update configuration ([#9](https://github.com/AppiumTestDistribution/AppClaw/issues/9)) ([c6794d7](https://github.com/AppiumTestDistribution/AppClaw/commit/c6794d718a37ef690c09f5fb006c8994c78e361b))
- parallel testing support and screen recording for SDK ([#16](https://github.com/AppiumTestDistribution/AppClaw/issues/16)) ([7d14e7b](https://github.com/AppiumTestDistribution/AppClaw/commit/7d14e7b760c41783c61f1227c037e1b28d184a5c))
- strict playground tap matching, waitUntil pre-check, faster vision assert ([59b8c29](https://github.com/AppiumTestDistribution/AppClaw/commit/59b8c299bf20c9232d89bbbb4d93a9ef600cca2b))
- vision improvements — drag support, screenshot optimization, an… ([#7](https://github.com/AppiumTestDistribution/AppClaw/issues/7)) ([8cfbcb4](https://github.com/AppiumTestDistribution/AppClaw/commit/8cfbcb483fce0dec531ad8c21c8cd93d5743d62f))

### Bug Fixes

* add semantic-release for automated versioning and npm publishing ([#19](https://github.com/AppiumTestDistribution/AppClaw/issues/19)) ([66c73a6](https://github.com/AppiumTestDistribution/AppClaw/commit/66c73a677e763112c4fab80dd29301f3d2071532))
* ci ([#10](https://github.com/AppiumTestDistribution/AppClaw/issues/10)) ([dfcd62f](https://github.com/AppiumTestDistribution/AppClaw/commit/dfcd62fa083d673c98fc0c381820c7dd58d36818))
* DOM locator resolution, vision assert parsing, and appium-mcp coordinate scaling ([9272c36](https://github.com/AppiumTestDistribution/AppClaw/commit/9272c36b65e7bd996b730bb6d67d0fa6fee9518a))
* read CLI version from package.json instead of hardcoded string ([#14](https://github.com/AppiumTestDistribution/AppClaw/issues/14)) ([fcb3a64](https://github.com/AppiumTestDistribution/AppClaw/commit/fcb3a6417ddc48d72d246bc9fd5dd1438020635d))
* screenshot parsing ([e449a23](https://github.com/AppiumTestDistribution/AppClaw/commit/e449a2341fc67e193f1519bae16d4cace878bcfc))
* scroll-aware stuck detection, press_enter tool, and post-done verification ([c03bbe4](https://github.com/AppiumTestDistribution/AppClaw/commit/c03bbe4222ce7fd7bba6867f7d1e59ac5ef3c8ee))
* terminal UI ([294a780](https://github.com/AppiumTestDistribution/AppClaw/commit/294a780113d8afdb99b80cf57b47db5b3fe12dc2))
* terminal view ([42c0e75](https://github.com/AppiumTestDistribution/AppClaw/commit/42c0e75e2d8a28c569b6511891628c1b98380cc3))
- add semantic-release for automated versioning and npm publishing ([#19](https://github.com/AppiumTestDistribution/AppClaw/issues/19)) ([66c73a6](https://github.com/AppiumTestDistribution/AppClaw/commit/66c73a677e763112c4fab80dd29301f3d2071532))
- ci ([#10](https://github.com/AppiumTestDistribution/AppClaw/issues/10)) ([dfcd62f](https://github.com/AppiumTestDistribution/AppClaw/commit/dfcd62fa083d673c98fc0c381820c7dd58d36818))
- DOM locator resolution, vision assert parsing, and appium-mcp coordinate scaling ([9272c36](https://github.com/AppiumTestDistribution/AppClaw/commit/9272c36b65e7bd996b730bb6d67d0fa6fee9518a))
- read CLI version from package.json instead of hardcoded string ([#14](https://github.com/AppiumTestDistribution/AppClaw/issues/14)) ([fcb3a64](https://github.com/AppiumTestDistribution/AppClaw/commit/fcb3a6417ddc48d72d246bc9fd5dd1438020635d))
- screenshot parsing ([e449a23](https://github.com/AppiumTestDistribution/AppClaw/commit/e449a2341fc67e193f1519bae16d4cace878bcfc))
- scroll-aware stuck detection, press_enter tool, and post-done verification ([c03bbe4](https://github.com/AppiumTestDistribution/AppClaw/commit/c03bbe4222ce7fd7bba6867f7d1e59ac5ef3c8ee))
- terminal UI ([294a780](https://github.com/AppiumTestDistribution/AppClaw/commit/294a780113d8afdb99b80cf57b47db5b3fe12dc2))
- terminal view ([42c0e75](https://github.com/AppiumTestDistribution/AppClaw/commit/42c0e75e2d8a28c569b6511891628c1b98380cc3))
199 changes: 167 additions & 32 deletions landing/usage.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2964,7 +2964,9 @@ <h2>GitHub Actions</h2>
</p>
<p>
Available on the
<a href="https://github.com/marketplace/actions/appclaw-mobile-tests" target="_blank">GitHub Marketplace</a>
<a href="https://github.com/marketplace/actions/appclaw-mobile-tests" target="_blank"
>GitHub Marketplace</a
>
as <strong>AppClaw Mobile Tests</strong>.
</p>

Expand Down Expand Up @@ -3053,27 +3055,135 @@ <h2>Inputs</h2>
</tr>
</thead>
<tbody>
<tr><td><code>flow</code></td><td>one of*</td><td>—</td><td>Path to a YAML flow file relative to repo root</td></tr>
<tr><td><code>goal</code></td><td>one of*</td><td>—</td><td>Natural language goal executed by the LLM agent</td></tr>
<tr><td><code>platform</code></td><td>no</td><td><code>android</code></td><td>Target platform: <code>android</code> or <code>ios</code></td></tr>
<tr><td><code>provider</code></td><td>no</td><td><code>gemini</code></td><td>LLM provider: <code>gemini</code>, <code>anthropic</code>, <code>openai</code>, <code>groq</code></td></tr>
<tr><td><code>api-key</code></td><td><strong>yes</strong></td><td>—</td><td>LLM API key — stored as <code>LLM_API_KEY</code></td></tr>
<tr><td><code>model</code></td><td>no</td><td><em>provider default</em></td><td>LLM model ID to pin (e.g. <code>gemini-2.0-flash</code>)</td></tr>
<tr><td><code>agent-mode</code></td><td>no</td><td><code>dom</code></td><td><code>dom</code> (element locators) or <code>vision</code> (screenshot AI)</td></tr>
<tr><td><code>max-steps</code></td><td>no</td><td><code>30</code></td><td>Maximum agent steps before the run fails</td></tr>
<tr><td><code>step-delay</code></td><td>no</td><td><code>500</code></td><td>Milliseconds between steps</td></tr>
<tr><td><code>android-api-level</code></td><td>no</td><td><code>33</code></td><td>Android emulator API level (33 = Android 13)</td></tr>
<tr><td><code>android-profile</code></td><td>no</td><td><code>pixel_6</code></td><td>Android AVD hardware profile</td></tr>
<tr><td><code>android-target</code></td><td>no</td><td><code>default</code></td><td>Emulator target: <code>default</code> or <code>google_apis</code></td></tr>
<tr><td><code>cloud-provider</code></td><td>no</td><td><em>local</em></td><td>Cloud provider: <code>lambdatest</code>. Leave empty for local.</td></tr>
<tr><td><code>lambdatest-username</code></td><td>no**</td><td>—</td><td>LambdaTest account username</td></tr>
<tr><td><code>lambdatest-access-key</code></td><td>no**</td><td>—</td><td>LambdaTest access key</td></tr>
<tr><td><code>lambdatest-device-name</code></td><td>no**</td><td>—</td><td>Cloud device name (e.g. <code>Pixel 7</code>)</td></tr>
<tr><td><code>lambdatest-os-version</code></td><td>no**</td><td>—</td><td>Cloud OS version (e.g. <code>13</code>, <code>16</code>)</td></tr>
<tr><td><code>lambdatest-app</code></td><td>no</td><td>—</td><td>LambdaTest app ID (<code>lt://APP...</code>)</td></tr>
<tr><td><code>report</code></td><td>no</td><td><code>true</code></td><td>Upload HTML report as workflow artifact</td></tr>
<tr><td><code>report-name</code></td><td>no</td><td><code>appclaw-report</code></td><td>Name of the uploaded artifact</td></tr>
<tr><td><code>appclaw-version</code></td><td>no</td><td><code>latest</code></td><td>npm package version to pin</td></tr>
<tr>
<td><code>flow</code></td>
<td>one of*</td>
<td>—</td>
<td>Path to a YAML flow file relative to repo root</td>
</tr>
<tr>
<td><code>goal</code></td>
<td>one of*</td>
<td>—</td>
<td>Natural language goal executed by the LLM agent</td>
</tr>
<tr>
<td><code>platform</code></td>
<td>no</td>
<td><code>android</code></td>
<td>Target platform: <code>android</code> or <code>ios</code></td>
</tr>
<tr>
<td><code>provider</code></td>
<td>no</td>
<td><code>gemini</code></td>
<td>
LLM provider: <code>gemini</code>, <code>anthropic</code>, <code>openai</code>,
<code>groq</code>
</td>
</tr>
<tr>
<td><code>api-key</code></td>
<td><strong>yes</strong></td>
<td>—</td>
<td>LLM API key — stored as <code>LLM_API_KEY</code></td>
</tr>
<tr>
<td><code>model</code></td>
<td>no</td>
<td><em>provider default</em></td>
<td>LLM model ID to pin (e.g. <code>gemini-2.0-flash</code>)</td>
</tr>
<tr>
<td><code>agent-mode</code></td>
<td>no</td>
<td><code>dom</code></td>
<td><code>dom</code> (element locators) or <code>vision</code> (screenshot AI)</td>
</tr>
<tr>
<td><code>max-steps</code></td>
<td>no</td>
<td><code>30</code></td>
<td>Maximum agent steps before the run fails</td>
</tr>
<tr>
<td><code>step-delay</code></td>
<td>no</td>
<td><code>500</code></td>
<td>Milliseconds between steps</td>
</tr>
<tr>
<td><code>android-api-level</code></td>
<td>no</td>
<td><code>33</code></td>
<td>Android emulator API level (33 = Android 13)</td>
</tr>
<tr>
<td><code>android-profile</code></td>
<td>no</td>
<td><code>pixel_6</code></td>
<td>Android AVD hardware profile</td>
</tr>
<tr>
<td><code>android-target</code></td>
<td>no</td>
<td><code>default</code></td>
<td>Emulator target: <code>default</code> or <code>google_apis</code></td>
</tr>
<tr>
<td><code>cloud-provider</code></td>
<td>no</td>
<td><em>local</em></td>
<td>Cloud provider: <code>lambdatest</code>. Leave empty for local.</td>
</tr>
<tr>
<td><code>lambdatest-username</code></td>
<td>no**</td>
<td>—</td>
<td>LambdaTest account username</td>
</tr>
<tr>
<td><code>lambdatest-access-key</code></td>
<td>no**</td>
<td>—</td>
<td>LambdaTest access key</td>
</tr>
<tr>
<td><code>lambdatest-device-name</code></td>
<td>no**</td>
<td>—</td>
<td>Cloud device name (e.g. <code>Pixel 7</code>)</td>
</tr>
<tr>
<td><code>lambdatest-os-version</code></td>
<td>no**</td>
<td>—</td>
<td>Cloud OS version (e.g. <code>13</code>, <code>16</code>)</td>
</tr>
<tr>
<td><code>lambdatest-app</code></td>
<td>no</td>
<td>—</td>
<td>LambdaTest app ID (<code>lt://APP...</code>)</td>
</tr>
<tr>
<td><code>report</code></td>
<td>no</td>
<td><code>true</code></td>
<td>Upload HTML report as workflow artifact</td>
</tr>
<tr>
<td><code>report-name</code></td>
<td>no</td>
<td><code>appclaw-report</code></td>
<td>Name of the uploaded artifact</td>
</tr>
<tr>
<td><code>appclaw-version</code></td>
<td>no</td>
<td><code>latest</code></td>
<td>npm package version to pin</td>
</tr>
</tbody>
</table>
<p>* Provide either <code>flow</code> <strong>or</strong> <code>goal</code>, not both.</p>
Expand All @@ -3083,17 +3193,36 @@ <h2>Inputs</h2>
<section id="gha-secrets" class="reveal">
<h2>Secrets Setup</h2>
<p>
Go to your repo &rarr; <strong>Settings &rarr; Secrets and variables &rarr; Actions &rarr; New repository secret</strong>:
Go to your repo &rarr;
<strong
>Settings &rarr; Secrets and variables &rarr; Actions &rarr; New repository
secret</strong
>:
</p>
<table>
<thead>
<tr><th>Secret name</th><th>Description</th></tr>
<tr>
<th>Secret name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr><td><code>LLM_API_KEY</code></td><td>Your API key — works for any provider (Gemini, Anthropic, OpenAI, Groq)</td></tr>
<tr><td><code>LT_USERNAME</code></td><td>LambdaTest username (only if using cloud devices)</td></tr>
<tr><td><code>LT_ACCESS_KEY</code></td><td>LambdaTest access key (only if using cloud devices)</td></tr>
<tr><td><code>LT_APP_ID</code></td><td>LambdaTest app ID (only if using cloud devices)</td></tr>
<tr>
<td><code>LLM_API_KEY</code></td>
<td>Your API key — works for any provider (Gemini, Anthropic, OpenAI, Groq)</td>
</tr>
<tr>
<td><code>LT_USERNAME</code></td>
<td>LambdaTest username (only if using cloud devices)</td>
</tr>
<tr>
<td><code>LT_ACCESS_KEY</code></td>
<td>LambdaTest access key (only if using cloud devices)</td>
</tr>
<tr>
<td><code>LT_APP_ID</code></td>
<td>LambdaTest app ID (only if using cloud devices)</td>
</tr>
</tbody>
</table>
</section>
Expand Down Expand Up @@ -3209,8 +3338,9 @@ <h3>Nightly regression on a schedule</h3>
<section id="gha-reports" class="reveal">
<h2>Reports</h2>
<p>
When <code>report: true</code> (default), an HTML report is uploaded as a workflow artifact after each run.
Download it from the <strong>Actions run summary &rarr; Artifacts</strong>. The report includes:
When <code>report: true</code> (default), an HTML report is uploaded as a workflow
artifact after each run. Download it from the
<strong>Actions run summary &rarr; Artifacts</strong>. The report includes:
</p>
<ul>
<li>Step-by-step screenshots with tap overlays</li>
Expand Down Expand Up @@ -3241,7 +3371,11 @@ <h3>Use report path in a downstream step</h3>
<h2>Runner Requirements</h2>
<table>
<thead>
<tr><th>Platform</th><th>Runner</th><th>Notes</th></tr>
<tr>
<th>Platform</th>
<th>Runner</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
Expand All @@ -3257,7 +3391,8 @@ <h2>Runner Requirements</h2>
</tbody>
</table>
<p>
<strong>iOS tip:</strong> For faster iOS CI, use LambdaTest cloud devices on <code>ubuntu-latest</code>
<strong>iOS tip:</strong> For faster iOS CI, use LambdaTest cloud devices on
<code>ubuntu-latest</code>
instead of a macOS runner.
</p>
</section>
Expand Down
2 changes: 1 addition & 1 deletion src/agent/app-resolver.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ export class AppResolver {
}

try {
const result = await mcp.callTool('appium_list_apps', {});
const result = await mcp.callTool('appium_app_lifecycle', { action: 'list' });
const text = result.content?.map((c: any) => c.text ?? '').join('\n') ?? '';

this.apps = parseAppList(text);
Expand Down
Loading
Loading