Skip to main content

​
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

Droidrun includes a sample Gmail app card to demonstrate how app cards work: 
# App cards are enabled by default
droidrun 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: Droidrun 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): 
# App cards enabled (Manager uses them for planning)
droidrun run "Archive all unread emails" --reasoning

# App cards not used (direct execution mode)
droidrun 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

# 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: 
mkdir -p config/app_cards
touch config/app_cards/app_cards.json
touch config/app_cards/chrome.md
Example structure: 
# 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: 
{
  "com.google.android.gm": "gmail.md",
  "com.android.chrome": "chrome.md"
}
Using subdirectories: 
{
  "com.whatsapp": "social/whatsapp.md",
  "com.instagram.android": "social/instagram.md"
}

​
Step 4: Test

droidrun run "Open Chrome and search for droidrun" --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/: 
agent:
  app_cards:
    enabled: true
    app_cards_dir: config/app_cards
To disable: 
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): 
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): 
## 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? 
    adb shell dumpsys window windows | grep -E 'mCurrentFocus'
  2. Is the mapping correct in app_cards.json? 
    {
  "com.your.app": "yourapp.md"
}
  3. Does the markdown file exist? 
    ls config/app_cards/yourapp.md
  4. Are app cards enabled? 
    agent:
  app_cards:
    enabled: true
  5. Are you using reasoning mode? 
    droidrun run "command" --reasoning

​
Debug Mode

Run with --debug to see app card loading: 
droidrun 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
Help your agents become app experts with well-crafted app cards!