Skip to content

docs: clarify Claude bootstrap flow #35

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

Open
HarveySang wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify Claude bootstrap flow #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
17 changes: 12 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,18 +35,22 @@ OpenGUI reads a real Android app UI, plans the next step, takes mobile actions,

The fastest way to try OpenGUI is to let Claude Code or Codex bootstrap it for you.

Open Claude Code or Codex from the OpenGUI repository root and paste:

```text
Read ./skills/open-gui-bootstrap/SKILL.md and help me run OpenGUI. Only ask me for phone-side actions.
```

Claude Code or Codex does not connect to the phone directly. It reads the bootstrap skill, starts the local backend, builds or installs the Android client, runs the required adb setup, and checks whether the phone is visible to OpenGUI.

You will need:

- an Android phone or emulator
- USB debugging enabled
- AccessibilityService enabled
- model API keys for real task execution

OpenGUI will use the repository scripts to start the backend and install the Android client:
The bootstrap flow uses the repository scripts to start the backend and install the Android client:

```bash
cd server
Expand Down Expand Up @@ -150,11 +154,12 @@ The source code currently exposes these pieces:

Start with [`skills/open-gui-bootstrap/SKILL.md`](./skills/open-gui-bootstrap/SKILL.md).

The intended flow is simple:
The intended flow is:

1. point Claude or Codex at the skill
2. describe the task in plain language
3. let the model handle backend bootstrap, APK build, install, and local debugging
1. clone OpenGUI locally
2. open Claude Code or Codex from the OpenGUI repo root
3. ask it to read the bootstrap skill
4. let it handle backend bootstrap, APK build, install, adb setup, and local debugging

It should only stop for:

Expand All @@ -164,6 +169,8 @@ It should only stop for:
- granting overlay or battery permissions
- providing API keys or bot credentials

Under the hood, OpenGUI still needs both the local backend and Android client running. The bootstrap skill is the guided path for getting those pieces running without manually following every setup step.

After the backend and Android client are running, use [`skills/open-gui-remote-control/SKILL.md`](./skills/open-gui-remote-control/SKILL.md) to let Codex or Claude Code control the phone through the local CLI:

```bash
Expand Down
23 changes: 23 additions & 0 deletions docs/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ This repository already contains the runnable backend and Android client.

## Option 1: Bootstrap with Claude or Codex

Open Claude Code or Codex from the OpenGUI repository root, then ask it to read
the bootstrap skill.

Start with the bootstrap skill:

- [`skills/open-gui-bootstrap/SKILL.md`](../skills/open-gui-bootstrap/SKILL.md)
Expand All @@ -14,11 +17,31 @@ Recommended prompt:
Read ./skills/open-gui-bootstrap/SKILL.md and help me run OpenGUI. Only ask me for phone-side actions.
```

Claude Code or Codex does not connect to the phone directly. The skill guides
the local setup: it starts the backend, builds or installs the Android client,
runs adb setup, and checks whether the phone is visible to OpenGUI.

The skill should use the repository scripts directly:

- `server/start.sh`
- `client/start.sh`

It should only stop for phone-side actions or credentials:

- connecting an Android device or starting an emulator
- approving USB debugging
- enabling Accessibility Service
- granting overlay or screen-related permissions
- providing model API credentials

After setup, run a basic smoke test:

```bash
cd server
pnpm opengui -- devices --json
pnpm opengui -- do "Observe the current Android screen and summarize what you see" --json
```

## Option 2: Manual setup

### 1. Start the backend
Expand Down