README.md (3342 bytes)
1 # deploy-handoff 2 3 A Claude Code plugin for the steps that an AI agent must not do alone. 4 5 An agent can build, test, and upload a release. Some steps must come from a person: publish the release, turn on live payments, accept an OAuth consent, or create a pull request. The agent drives the browser as far as it can. Then deploy-handoff shows a small dialog on top of the browser. The dialog tells you what to do, in short steps in [Simplified Technical English](https://asd-ste100.org). You do the final click. Then you click **Done** or **Not done**, and the agent continues. 6 7 deploy-handoff never clicks for you. It never asks for a password or a key. 8 9 ## Install 10 11 In Claude Code: 12 13 ``` 14 /plugin marketplace add equwal/deploy-handoff 15 /plugin install deploy-handoff@deploy-handoff 16 ``` 17 18 Requirements: 19 20 - Python 3.11 or later, with Tk. The python.org installers for Windows and macOS include Tk. On Debian and Ubuntu, install `python3-tk`. 21 - `git` for the `pr` command. `gh` is optional. If `gh` is available, the `pr` command gives the URL of the new pull request. 22 23 ## How it works 24 25 The plugin adds the skill `deploy-handoff`. Claude uses the skill when a task reaches a human step, and when it opens a GitHub pull request. The skill runs `skills/deploy-handoff/handoff.py`. Other tools can run the script in the same way. 26 27 Open a page and show the steps: 28 29 ```bash 30 python3 skills/deploy-handoff/handoff.py open \ 31 --url https://play.google.com/console \ 32 --title "Send version 1.4.0 for review" \ 33 --step 'Open "Publishing overview".' \ 34 --step 'Click "Send changes for review".' 35 ``` 36 37 If the agent already drove a browser to the page, it adds `--no-open`. Then the script shows only the dialog. The script refuses a title or a step with more than 20 words or with a semicolon. 38 39 Open the pull request form for the current branch: 40 41 ```bash 42 python3 skills/deploy-handoff/handoff.py pr --title "Add CSV export" --body-file body.md 43 ``` 44 45 The script prints one JSON object, for example `{"status": "done", "note": ""}`. [SKILL.md](skills/deploy-handoff/SKILL.md) lists all statuses and exit codes. 46 47 ## Browser 48 49 The script opens pages in a new tab of your default browser. To use a different browser, set the `BROWSER` environment variable. The Python `webbrowser` module reads it. 50 51 ## Allowed hosts 52 53 The script opens only `https` pages on allowed hosts. This stops an agent that follows bad instructions from sending you to a fake sign-in page. The dialog also shows the host of the page. 54 55 [config.toml](skills/deploy-handoff/config.toml) has the default list: GitHub, GitLab, Stripe, Google Play, F-Droid, App Store Connect, and some cloud and hosting consoles. An entry also allows its subdomains. 56 57 To add hosts, make the file `~/.config/deploy-handoff/config.toml`. If `XDG_CONFIG_HOME` is set, the file is `$XDG_CONFIG_HOME/deploy-handoff/config.toml`. 58 59 ```toml 60 allowed_hosts = ["dashboard.example.com"] 61 ``` 62 63 ## Development 64 65 ```bash 66 python3 -m venv .venv 67 .venv/bin/python -m pip install --group dev 68 .venv/bin/python -m ruff format --check 69 .venv/bin/python -m ruff check 70 .venv/bin/python -m mypy skills/deploy-handoff 71 .venv/bin/python -m unittest discover -s skills/deploy-handoff 72 ``` 73 74 On Windows, use `.venv\Scripts\python`. `pip install --group` needs pip 25.1 or later. The dialog tests show small windows for a short time. 75 76 ## License 77 78 MIT