Files
DroidDeck/tools/agent/AGENTS.md
T

4.8 KiB

DroidDeck on-device agent

You run in DroidDeck's Agent tab, on the user's handheld, in DroidDeck's Linux userland (Ubuntu under proot, aarch64). The user is often on a small screen: keep replies short. These notes come from what tripped agents up on real devices.

Where you run

  • Steam, the desktop and games run in DroidDeck's session, a separate guest from yours: a program you start here is not in it and has no screen. Reach it with droiddeckctl (guide: /root/.local/share/droiddeck/ctl/agent-control.md): state, start steam, stop, launch, quit, focus, screenshot, logs, pacing, thermal, and guest to run a command in it.
  • droiddeckctl stop, start steam and resume end or restart only the session. You keep running, so restart it yourself when a change needs a new session.
  • The session shares your filesystem. Steam is in /root/.local/share/Steam (its logs in logs/), and the session's live logs are in the folder state gives as session.logDir. logs latest makes a redacted, partial copy: read the live folder yourself. X properties, gamescope and the session's processes are only reachable through guest.

Commands

  • guest runs one program, not a shell line: droiddeckctl guest -- sh -c '...' for pipes, $(...) or DISPLAY=:0 xprop .... Its answer is JSON; the output is in stdout.text.
  • screenshot takes the path as an argument (screenshot /tmp/top.png --display 0); on a dual-screen device see droiddeckctl displays. prefs get takes a file (prefs get session).
  • input drives a game session that has drawn a frame. For the launcher's own screens use adb -s $ADB_SERIAL shell input keyevent KEYCODE_BACK and similar.
  • droiddeck-scenario replays a scripted test through droiddeckctl (--help for the format).
  • Never kill by a command-line pattern (pkill -f, pgrep -f piped to kill): your own command line holds the user's message, so the pattern matches you. End a game with droiddeckctl quit, the session with droiddeckctl stop, anything else by its pid after checking what it is (ps -o pid,args -p <pid>): a pid near a game can be the Steam client.
  • DEVICE_RESOLUTION_FAILED: run adb devices and use the serial it lists.
  • Do not chain sleep before a check. Start long work in the background. In Claude Code, its end starts you again; other harnesses are not woken, so check it before ending your turn or tell the user it is still running.

What applies when

  • Many session settings (black frame insertion, environment, Proton) are read when a session or game starts. After changing one, restart the game or the session before judging it.
  • With "Return after game" on (the default), quitting a game DroidDeck launched ends the whole session; start steam --wait --reuse before the next launch. Launching a game that is already running makes Steam show "Game already running" and launch time out.
  • Session scripts are APK assets, copied into the rootfs at every session start over any local edit. A Lab build (dd-lab-build, see docs/lab-builds.md) carries app code and resources only: session scripts, native code and assets need a new APK, such as the pull request's CI test build (DroidDeck > Updates > Test builds).

Changing DroidDeck

The source is checked out at /root/DroidDeck once the Agent tab's build tools are set up.

  • It often holds the user's uncommitted work and a stale local main. Branch from origin/main in a worktree (git worktree add -b <branch> ../<dir> origin/main).
  • dd-lab-build builds the checkout as a Lab build and restarts DroidDeck on it. DroidDeck runs the build in a process of its own and shows its progress; dd-lab-build follows its log. Run it in the background and keep checking, so the user can talk to you meanwhile. The restart ends your process, and the conversation continues on the new build.
  • Python tests run from the repository root: python3 -m unittest tools.tests.test_x. Some fail on the device on origin/main too; run them on a worktree of origin/main before blaming a change.
  • Gradle unit tests rarely run on the device. Leave them to CI and say so rather than retrying.
  • If git push asks for credentials, run gh auth setup-git once.
  • Commits and pull requests you make are the user's own: no co-author line, AI credit or generated-by note.

This file

DroidDeck writes this block into your global instructions (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md) before every turn, and its skills into ~/.claude/skills and ~/.codex/skills. It replaces only its own block and its own skills (folders holding a .droiddeck file): the user's rules go outside the block, and their skills stay, even one with the same name. Deleting a skill's .droiddeck file keeps local edits to it. To change DroidDeck's, edit tools/agent/AGENTS.md and tools/agent/skills in the source.