afk.watch / advanced setup
Advanced setup.
The desktop app handles normal setup. This page keeps manual, headless, hosted, and generic integrations available.
Use the same GitHub account.
It maps this computer to the account already signed in on your phone. No new password, no extra identity.
Access
Your API key
This secret lets an agent report runs to your account. Keep it in an env var, never in committed code.
…
Claude Code and Codex
Install manually
This is the fallback for a machine that cannot run the desktop companion, or when you prefer a terminal. The one-command install stores your key, wires the Claude Code lifecycle hooks, and installs the pickup skill for both clients. Re-running it is safe, and afk uninstall removes both copies cleanly.
One key is active per account. Issuing a new one replaces the current key immediately. An AFK_KEY exported in your shell profile wins over the installed config file, so remove or update that export after rotation.
/afk-watch #33 in Claude Code or $afk-watch #33 in Codex takes that issue - the same monitored pickup workflow. Bare /afk-watch takes the oldest open ready-for-agent issue.
Or with curl:
Confirm
Light up your phone
Send one synthetic run through the real pipeline. It proves the key, network, and push delivery before you wire real work.
Waiting for your first run…
Optional pickup modes and generic integration.
Automatic local pickupMachine awake
The installer adds the skill, but an external CLI cannot create a Claude Desktop scheduled task. Open the repository you want watched in Claude Desktop and say exactly:
Create a scheduled task named afk.watch pickup that runs /afk-watch every 5 minutes in this folder using auto permission mode.
Auto is the safest unattended mode that can edit files, run commands, commit, and open PRs while still blocking actions it judges risky. Pickup works only while Claude Desktop is open and the machine is awake. Closing the lid stops it. /loop is not the unattended mechanism.
Automatic hosted pickupOptional / machine off
This optional path runs while your machine is off. Generate the hosted GitHub Actions workflow from inside the repository:
npx @afk-watch/cli@latest init --pickup
Add two repository Actions secrets: AFK_KEY and ANTHROPIC_API_KEY. Hosted pickup uses Actions minutes plus per-token Anthropic API billing; a Claude subscription does not authenticate hosted CI. Commit and merge the generated workflow to the default branch before it can react to ready-for-agent.
The runner is deleted when the job ends, so a run is reported done only once its work is committed, pushed, and preserved in a pull request; anything left behind fails the run instead of reporting changes nobody can find. Turn on Settings › Actions › General › Allow GitHub Actions to create and approve pull requests so the agent can open it.
The issue text becomes the agent's instructions, so the workflow picks up an issue only when GitHub reports its author's author_association as OWNER, MEMBER, or COLLABORATOR. That is the relationship GitHub declares in the payload, not a check that the author has write access: MEMBER covers any member of the owning organization, including one with read-only access to this repository. Every other association keeps the label and is yours to work by hand — including issues opened by a GitHub App or bot, which report NONE. Anyone the gate admits can still steer the agent through issue text. Only that issue's title and body reach the agent: it is told not to read or obey issue comments, which anyone can post and no gate covers.
The pull request it opens does not run your CI. GitHub fires no pull_request workflow runs for anything created with the built-in GITHUB_TOKEN, and this path stays at two secrets — no PAT, no GitHub App — so the pull request arrives with no checks on it. The agent must run your project's own validation inside the job and report the commands and results, but that is its word, not a check run: trigger your repository's checks yourself and confirm they pass before merging.
Any agent: copy-paste HTTPGeneric
A generic shell wrapper, pre-filled with your key. Start a run, report progress, finish.