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

Merged
HarveySang merged 2 commits into from
Sep 7, 2026
Merged

docs: clarify Claude bootstrap flow #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6e98e56
docs: clarify Claude bootstrap flow
HarveySang Jul 5, 2026
38788a7
Merge main and preserve updated bootstrap documentation
HarveySang Sep 7, 2026
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 @@ -82,10 +82,14 @@ Model availability, pricing, and policy behavior vary by version and region. Whi

To run the full OpenGUI backend and Android client, let Claude Code, Codex, or OpenCode bootstrap it for you.

Open Claude Code, Codex, or OpenCode 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.
```

In this bootstrap flow, the coding agent reads the 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.

This explicit prompt also works in OpenCode. The repository keeps the Skill in
`skills/`, so OpenCode users should include the path as shown instead of relying
on automatic Skill discovery. See the [OpenCode Agent Skills documentation](https://opencode.ai/docs/skills/)
Expand All @@ -108,7 +112,7 @@ Permission names and menu locations vary across Android vendors. Complete the
[Android permission setup guide](./docs/android-permissions.md) before running
the first task.

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 @@ -235,11 +239,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 Code, Codex, or OpenCode 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, Codex, or OpenCode 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 @@ -249,6 +254,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 Claude Code, Codex, or OpenCode control the phone through the local CLI:

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

## Option 1: Bootstrap with Claude Code, Codex, or OpenCode

Open Claude Code, Codex, or OpenCode 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 @@ -18,6 +21,9 @@ Recommended prompt:
Read ./skills/open-gui-bootstrap/SKILL.md and help me run OpenGUI. Only ask me for phone-side actions.
```

The bootstrap skill guides the local backend and Android client setup: it starts the backend, builds or installs the Android client,
runs adb setup, and checks whether the phone is visible to OpenGUI.

The same prompt works in OpenCode. Because this repository keeps the Skill in
the top-level `skills/` directory, specify the path explicitly as shown above.
OpenCode's automatic discovery instead searches locations such as
Expand All @@ -29,6 +35,22 @@ 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
Loading