Skip to main content

Overview

App cards are markdown documents that contain:
  • Navigation tips: How to navigate through the app’s UI
  • Common actions: Step-by-step guides for frequent tasks
  • UI patterns: App-specific interaction patterns and conventions
  • Known gotchas: Quirks, issues, or important notes about the app
  • Search syntax: Special search operators or filters (for apps like Gmail, file managers, etc.)
When a Droidrun agent detects it’s operating within a specific app (by package name), it automatically loads the corresponding app card and uses that knowledge to make better decisions.

How App Cards Work

Automatic Detection and Loading

  1. Package Detection: Droidrun monitors the current foreground app package name (e.g., “com.google.android.gm” for Gmail)
  2. Async Loading: When the package or instruction changes, Droidrun starts loading the app card in the background
  3. Caching: All providers use in-memory caching with (package_name, instruction) as cache keys
  4. Prompt Injection: The app card content is injected into the Manager’s system prompt within <app_card> tags
  5. Context-Aware Actions: The agent uses the app-specific guidance to perform actions more effectively
Loading Strategy:
  • App cards are loaded asynchronously to avoid blocking agent execution
  • Loading starts when package/instruction changes are detected
  • The Manager waits briefly (0.1s) for the background task to complete
  • If loading isn’t ready, the Manager proceeds without the app card
  • Subsequent requests will use the cached result

When App Cards Are Used

App cards are used by the Manager Agent in reasoning mode (--reasoning flag or reasoning=True in config). The Manager uses app cards to:
  • Plan multi-step workflows that align with the app’s UI structure
  • Make informed decisions about navigation and action sequences
  • Understand app-specific features and capabilities
  • Avoid common pitfalls and known issues
Note: App cards are loaded asynchronously when the current app package changes. The card is injected into the Manager’s system prompt within <app_card> tags.

Built-in App Cards

Droidrun ships with app cards for popular apps. Currently included:
AppPackage NameFeatures Covered
Gmailcom.google.android.gmNavigation, search filters, composing emails, organizing messages, folder management
More app cards are continuously added. Check droidrun/config/app_cards/ in the package directory for the latest list.

App Card Format

App cards are stored as markdown files and mapped to package names via app_cards.json.

Directory Structure

config/app_cards/
├── app_cards.json       # Package name → file mapping
├── gmail.md             # Gmail app card
├── chrome.md            # Chrome app card (example)
└── social/              # Organize in subdirectories
    ├── whatsapp.md
    └── instagram.md

Mapping File (app_cards.json)

The app_cards.json file maps Android package names to markdown files:
{
  "com.google.android.gm": "gmail.md",
  "com.android.chrome": "chrome.md",
  "com.whatsapp": "social/whatsapp.md",
  "com.instagram.android": "social/instagram.md"
}

Markdown File Structure

App card markdown files should follow this structure:
# App Name Guide

## Navigation
- How to navigate the app
- Key screens and menus
- Drawer/hamburger menu contents

## Search
- How to use search functionality
- Special search operators or filters
- Tips for finding specific content

## Common Actions
- **Action Name**: Step-by-step guide
- **Another Action**: How to perform it
- Use bullet points for clarity

## Composing/Creating Content
- How to create new items (emails, posts, documents, etc.)
- Where to find creation buttons
- Required vs. optional fields

## Tips
- App-specific tips
- Known issues or quirks
- Performance considerations
- Best practices

Example: Gmail App Card

Here’s the complete Gmail app card (gmail.md):
# Gmail App Guide

## Navigation
- Use the hamburger menu (top-left) to access folders (Inbox, Sent, Drafts, Trash, etc.)
- Tap the compose button (bottom-right floating action button) to write new emails
- Swipe left or right on emails to quickly archive or delete

## Search
- Use the search bar at the top to find emails
- Search supports filters like:
  - `from:sender@email.com` - Find emails from specific sender
  - `to:recipient@email.com` - Find emails to specific recipient
  - `subject:keyword` - Search in subject line
  - `has:attachment` - Find emails with attachments
  - `is:unread` - Find unread emails

## Common Actions
- **Archive**: Swipe right on an email in the list
- **Delete**: Swipe left on an email in the list
- **Select Multiple**: Long press on an email to enter selection mode
- **Star/Unstar**: Tap the star icon next to an email
- **Mark as Read/Unread**: Long press → Select → Tap the mark read/unread icon
- **Move to Folder**: Long press → Select → Tap the folder icon

## Composing Emails
- Tap the floating compose button (bottom-right)
- Fill in recipient, subject, and body
- Attach files by tapping the paperclip icon
- Send by tapping the send button (paper plane icon) in the top-right

## Tips
- Primary inbox shows important emails automatically
- Social and Promotions tabs filter promotional and social emails
- Enable notifications for important emails only
- Use labels to organize emails

Creating Custom App Cards

Step 1: Find the Package Name

To create an app card, you first need the app’s package name. Using ADB:
# List all packages
adb shell pm list packages

# Search for specific app
adb shell pm list packages | grep keyword

# Get the current foreground app
adb shell dumpsys window windows | grep -E 'mCurrentFocus'
Using Droidrun Debug Mode:
# Run Droidrun with debug logging
droidrun run "Open the app" --debug

# The package name will appear in logs when the app is opened
Common Package Names:
  • Gmail: com.google.android.gm
  • Chrome: com.android.chrome
  • WhatsApp: com.whatsapp
  • Instagram: com.instagram.android
  • Facebook: com.facebook.katana
  • YouTube: com.google.android.youtube
  • Google Maps: com.google.android.apps.maps

Step 2: Create the Markdown File

Create a markdown file in your app cards directory:
# In your working directory
mkdir -p config/app_cards
touch config/app_cards/myapp.md
Fill the file with app-specific guidance following the structure shown above.

Step 3: Update app_cards.json

Add an entry to app_cards.json:
{
  "com.google.android.gm": "gmail.md",
  "com.myapp.package": "myapp.md"
}

Step 4: Test the App Card

Run Droidrun with the app and verify the app card is loaded:
droidrun run "Open myapp and do something" --reasoning --debug
Look for log messages like:
Loaded app_cards.json with 2 entries
Loaded app card for com.myapp.package from config/app_cards/myapp.md

Configuration

App cards are configured in config.yaml under the agent.app_cards section:
agent:
  app_cards:
    enabled: true
    mode: local  # local, server, or composite
    app_cards_dir: config/app_cards
Disable with enabled: false. For server/composite modes, add server_url configuration.

Providers

LocalProvider (default): Loads from local filesystem. Set mode: local. ServerProvider: Fetches from remote HTTP via POST {server_url}/app-cards. Set mode: server. CompositeProvider: Tries server first, falls back to local. Set mode: composite.

Improve your agent’s performance with well-crafted app cards!
I