ai-launcher-android

An open-source Android home screen made to be changed by an AI agent. Say what you want in plain words, and your agent edits the code, installs it on your phone, checks that it runs, and looks at the result.

"Make this a black minimalist launcher with 5 apps, a big clock and a focus timer."

These are real screenshots of launchers that Claude Code built on a real phone from a short request. The gallery has the prompt behind each one.

Contents: Why this project · Quick start · What to ask for · How it works · What's included · Use it without an agent · Safety · Going back · Troubleshooting · What's been tested · Contributing

Why this project

Your home screen is the part of your phone you see most, but you can usually only change what its settings allow. A launcher app gives you more options, but they're still someone else's options. Building your own has meant learning Android development.

AI coding agents change that, but pointing one at an empty folder is a gamble. It has to set up an Android project from nothing, and it can't easily tell whether the result works on your phone. This repo gives the agent what it needs:

• A launcher that already works, so the agent changes something good instead of starting from nothing.
• A way to check its own work. One command installs the launcher, looks for crashes and takes screenshots for the agent to look at, so it can find and fix problems without asking you.
• Clear instructions and limits. AGENTS.md tells the agent where to make changes and what to ask you first, such as before installing tools or adding permissions.
• A way out. If a change makes the launcher keep crashing, a basic safe mode opens, so you aren't left without a home screen.

It's useful if you want:

• A calmer phone, with fewer apps and fewer distractions.
• A simple phone for a parent or relative, with big buttons and only the apps they use.
• A home screen that looks like nothing else, or a feature no launcher has, such as hiding social apps during work.
• A real Android project to learn from, with an agent to explain and change it as you watch.

Quick start

What you need

• A computer with a terminal. It's been tested on Linux; the tools are bash scripts, so on Windows you'd need Git Bash or WSL.
• An Android phone, version 8.0 or newer, on the same Wi-Fi as your computer or connected by USB.
• A coding agent that can run commands, such as Claude Code.

You don't need to install the Android tools first. The agent checks what's missing and asks before installing anything.

1. Turn on debugging on your phone

This lets your computer install the launcher.

1. Open Settings > About phone and tap Build number 7 times. On some phones, it's under Software information.
2. Go back to Settings > Developer options.
3. Choose how to connect:
   • USB: turn on USB debugging, plug in the phone, and accept the prompt that appears.
   • Wi-Fi: turn on Wireless debugging and choose Pair device with pairing code. Your agent will ask for the code it shows.

Turn debugging off again when you're finished. A launcher that's already installed keeps working without it.

2. Ask your agent

Open your agent in any folder and paste this, changing the last sentence to what you want:

Clone github.com/MedTahiri/ai-launcher-android, read its AGENTS.md and follow it. Build me a launcher with big buttons and only my phone, messages and photos apps.

The agent then:

1. Checks your computer with tools/doctor.sh.
2. Changes the launcher to match your request.
3. Installs it and runs tools/verify.sh.
4. Looks at the screenshots, and fixes anything that's wrong.
5. Tells you what it built, and any way it falls short.

3. Make it your home screen

Installing the launcher doesn't replace your current one. When you're happy with it, open Settings > Apps > Default apps > Home app and choose it. The exact path can differ between phones.

4. Keep changing it

Open your agent in the same folder and ask for more:

Make the clock bigger, and hide my games until 6 pm.

What to ask for

Plain words are enough. Say who it's for and what matters to you, and let the agent make the design choices.

Not sure where to start? Point your agent at a recipe. Each one describes a kind of launcher:

For example: "Build the seniors recipe, with bigger text and my daughter's favorite apps."

How it works

  You describe what you want
             │
             ▼
  Agent reads AGENTS.md and checks the computer (tools/doctor.sh)
             │
             ▼
  Agent makes the change, starting with the safest place:
  launcher.json → theme/ → home/ → widgets/ → core/ (last resort)
             │
             ▼
  tools/verify.sh runs the tests, builds and installs the launcher,
  opens it, looks for crashes, and takes screenshots  ◄──┐
             │                                           │
             ▼                                           │
  Agent looks at the screenshots ── something wrong? ────┘
             │
             ▼
  Agent tells you what it built

Automated checks can't see that text is invisible or a layout looks bad, so looking at the screenshots is a required step. Testing this project showed why: the checks passed on a home screen whose clock was black on a black background, and only a look at the screenshot caught it.

What's included

Two styles

Set with home.style in launcher.json.

One settings file

Many requests only need a change to launcher.json:

{
  "name": "Glass",
  "theme": { "mode": "dark", "background": "wallpaper", "accent": "#FF8A3D" },
  "home": {
    "style": "glass",
    "widgets": [{ "type": "analog_clock" }, { "type": "calendar" }],
    "favorites": ["com.android.chrome", "com.android.settings"]
  }
}

A misspelled setting or invalid value stops the build with a message saying what's wrong. AGENTS.md lists every setting.

Widgets

Digital clock, analog clock, calendar, battery and focus timer. A new widget takes one file and one line to register it.

Tools

Project layout

l