> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# App Instruction Cards

> App cards give your agents app-specific knowledge to operate apps more effectively. They automatically load when agents work with specific apps, improving success rates for navigation and complex tasks.

## What Are App Cards?

App cards are **app-specific instruction guides** that teach agents how to use apps effectively. Think of them as cheat sheets that help your agent understand:

* How to navigate the app's UI
* Where to find buttons and features
* App-specific shortcuts and gestures
* Search syntax and filters (for apps like Gmail)
* Common workflows and best practices

**Example:** When your agent opens Gmail, it automatically loads the Gmail app card and learns that:

* The compose button is at the bottom-right
* Search supports filters like `from:sender@email.com` or `has:attachment`
* Swiping right archives emails, swiping left deletes them

This knowledge helps agents complete tasks faster and more reliably.

***

## Why Use App Cards?

**Without app cards:**

* Agents guess how to navigate unfamiliar apps
* Trial-and-error wastes time and tokens
* Success rates drop for complex workflows

**With app cards:**

* ✅ Agents know exactly where to find features
* ✅ First-attempt success for common tasks
* ✅ Reduced token usage (less exploration needed)
* ✅ Better handling of app-specific quirks

***

## Quick Start

Mobilerun includes a sample Gmail app card to demonstrate how app cards work:

```bash theme={null}
# App cards are enabled by default
mobilerun run "Send an email to john@example.com" --reasoning
```

When the agent opens Gmail, the Gmail app card automatically loads and guides the workflow.

**Sample app card included:**

* **Gmail** (`com.google.android.gm`) - Email navigation, search, composition

You can use this as a template to create cards for other apps (see "Creating Custom App Cards" below).

***

## How App Cards Work

### Automatic Loading

1. **Detection:** Agent detects the current foreground app (e.g., Gmail)
2. **Loading:** Mobilerun loads the app card for that package name
3. **Injection:** App card content is added to the agent's prompt
4. **Guidance:** Agent uses the instructions to make better decisions

**Technical note:** App cards are loaded asynchronously and cached in memory. Loading happens in the background and doesn't block agent execution.

### When Are They Used?

App cards are used by the **Manager Agent** when running in reasoning mode (`--reasoning` flag or `reasoning: true` in config):

```bash theme={null}
# App cards enabled (Manager uses them for planning)
mobilerun run "Archive all unread emails" --reasoning

# App cards not used (direct execution mode)
mobilerun run "Tap the button"
```

***

## Creating Custom App Cards

Want to add an app card for your favorite app? Here's how:

### Step 1: Find the Package Name

```bash theme={null}
# Get all apps
adb shell pm list packages

# Or search for a specific app
adb shell pm list packages | grep keyword
```

**Common package names:**

* Chrome: `com.android.chrome`
* WhatsApp: `com.whatsapp`
* Instagram: `com.instagram.android`
* YouTube: `com.google.android.youtube`

### Step 2: Create the Files

Create the app cards directory and files:

```bash theme={null}
mkdir -p config/app_cards
touch config/app_cards/app_cards.json
touch config/app_cards/chrome.md
```

**Example structure:**

```markdown theme={null}
# Chrome App Guide

## Navigation
- Address bar at the top for entering URLs
- Three-dot menu (top-right) for settings and history
- Tabs button (top-right) to switch between tabs

## Search
- Type queries directly in the address bar
- Use voice search via the microphone icon

## Common Actions
- **New Tab**: Tap the tabs button → Plus icon
- **Close Tab**: Swipe tab away in tab switcher
- **Refresh**: Pull down from the top of the page
- **Bookmarks**: Three-dot menu → Bookmarks

## Tips
- Incognito mode available via three-dot menu
- Downloads accessible via three-dot menu → Downloads
```

### Step 3: Register the App Card

Add your app mapping to `config/app_cards/app_cards.json`:

```json theme={null}
{
  "com.google.android.gm": "gmail.md",
  "com.android.chrome": "chrome.md"
}
```

**Using subdirectories:**

```json theme={null}
{
  "com.whatsapp": "social/whatsapp.md",
  "com.instagram.android": "social/instagram.md"
}
```

### Step 4: Test

```bash theme={null}
mobilerun run "Open Chrome and search for mobilerun" --reasoning --debug
```

Look for this log message:

```
Loaded app card for com.android.chrome from config/app_cards/chrome.md
```

***

## Configuration

App cards are enabled by default and load from `config/app_cards/`:

```yaml theme={null}
agent:
  app_cards:
    enabled: true
    app_cards_dir: config/app_cards
```

**To disable:**

```yaml theme={null}
agent:
  app_cards:
    enabled: false
```

***

## App Card Best Practices

### Content Guidelines

**Do:**

* Be concise and actionable
* Focus on UI patterns and workflows
* Include search syntax and special features
* Mention common pitfalls or quirks
* Use bullet points and clear headings

**Don't:**

* Write essays or lengthy explanations
* Describe every single feature
* Include information that changes frequently (version-specific details)
* Duplicate general Android knowledge (agents already know how to tap, swipe, etc.)

### Example: Good vs Bad

**❌ Bad (too verbose):**

```markdown theme={null}
Gmail is an email application developed by Google. It has many features
including the ability to send and receive emails. To compose an email,
you need to first understand that Gmail uses a material design interface
with a floating action button, which is a circular button...
```

**✅ Good (concise and actionable):**

```markdown theme={null}
## Composing Emails
- Tap the floating compose button (bottom-right)
- Fill recipient, subject, and body
- Send via paper plane icon (top-right)
```

***

## Troubleshooting

### App Card Not Loading

**Check these:**

1. **Is the package name correct?**
   ```bash theme={null}
   adb shell dumpsys window windows | grep -E 'mCurrentFocus'
   ```

2. **Is the mapping correct in app\_cards.json?**
   ```json theme={null}
   {
     "com.your.app": "yourapp.md"
   }
   ```

3. **Does the markdown file exist?**
   ```bash theme={null}
   ls config/app_cards/yourapp.md
   ```

4. **Are app cards enabled?**
   ```yaml theme={null}
   agent:
     app_cards:
       enabled: true
   ```

5. **Are you using reasoning mode?**
   ```bash theme={null}
   mobilerun run "command" --reasoning
   ```

### Debug Mode

Run with `--debug` to see app card loading:

```bash theme={null}
mobilerun run "Open Gmail" --reasoning --debug
```

Look for these log messages:

```
Loaded app_cards.json with 2 entries
Loaded app card for com.google.android.gm from config/app_cards/gmail.md
```

***

## Related Documentation

* [CLI Usage](/framework/guides/cli) - Mobilerun CLI command reference
* [Configuration](/framework/sdk/configuration) - Configuration system details
* [Agent Architecture](/framework/concepts/architecture) - How agents work
* [Manager Agent](/framework/concepts/architecture#manageragent-planner) - Agent that uses app cards

***

**Help your agents become app experts with well-crafted app cards!**