Appearance

Language

Mastering AI agents

How to Ship Code from Your Phone with Claude Code in 2026: Remote Control, Pull Requests and GitHub Mobile

Connect the Claude app to Claude Code running on an always-on server, have it branch, change the code, run the tests, push and open a PR with gh, then read the diff, comment and merge in GitHub Mobile. Covers the CLAUDE.md rules, permission modes, rulesets and worktree cleanup.

Kelvin Wang · · 13 min read

Key points

  1. Start Remote Control with --spawn=worktree and every new session you open from your phone gets its own git worktree, so sessions don't overwrite each other's files.
  2. Put branch, test and PR rules in CLAUDE.md as instructions. Use a GitHub ruleset to block updates to main that aren't associated with a PR.
  3. You can't approve a PR opened with your own token. With required approvals set to 0, that token can also merge it; leaving the final merge to a person is still a workflow agreement.
  4. Server mode exits after about 10 minutes without network; systemd's Restart=always brings it back.

I have an Oracle Cloud A1 instance in Tokyo. It runs Claude Code Remote Control through systemd and uses a fine-grained token for GitHub. With the server in place, the next step is to work out how to request a change from my phone, review the diff and merge it on GitHub.

The workflow below is based on the official documentation. I haven’t tested these steps on that server yet. The startup flags, permission mode and PR rules are configuration examples; the phone controls, reconnection behavior and cleanup still need to be verified on the host.

What does the whole loop look like?

  1. Connect from your phone. In the Claude app or claude.ai/code, find the Remote Control server on your machine and open a new session 1.
  2. Hand over the task. Say what to change, and tell it to create a new branch, run the tests, push and open a PR.
  3. Answer permission prompts on your phone. When Claude wants to run something that needs approval, the prompt shows up on your phone; allow or deny it.
  4. Claude opens the PR. It runs gh pr create on the server and sends you the link 5.
  5. Review in GitHub Mobile. Read Files changed and leave comments; for anything that needs fixing, go back to the Claude session and ask it to address the comments.
  6. Wait for CI, then merge. Once the checks pass, merge right in the GitHub app 10.
  7. Clean up. Delete the remote branch and remove the finished worktree on the server.

How should Remote Control be set up on the server?

claude remote-control runs in server mode: one process serves several sessions at once. With --spawn=worktree, each new session opened from your phone or browser gets its own git worktree. The session created at startup stays in the project folder. --capacity limits concurrent sessions and defaults to 32 1. This example sets the limit to 4 and starts sessions in acceptEdits mode:

claude remote-control --name "Phone PR" --spawn=worktree --capacity 4 --permission-mode acceptEdits

With the default worktree.baseRef=fresh, Claude Code branches from the remote default branch, usually main, keeping each session’s file edits separate. That does not guarantee the latest commit: it may use a cached remote ref, including when a fetch fails. To pick up recently merged code or rules, run git fetch origin in the main checkout first and check the new worktree’s starting commit. Setting worktree.baseRef=head, or having no usable remote ref, can also make the worktree start from local HEAD 3.

A new worktree also needs its dependencies and runtime configuration. It doesn’t automatically inherit node_modules or .env from the main checkout. Install dependencies as the project requires; .worktreeinclude can copy needed gitignored configuration files into new worktrees 3.

Two more things to set up on the server first:

  • GitHub sign-in. Sessions use the server’s gh login, so gh auth status should show your account. Scope the token to the repos and permissions you need (Contents and Pull requests, read and write).
  • Push notifications. Run claude on the server, type /config, and turn on Push when actions required so permission prompts and questions reach your phone. The Claude app on your phone must be signed in to the same account with notifications allowed 1.

Which permission mode should phone sessions use?

--permission-mode sets the starting mode for new sessions. The docs describe six modes; run claude remote-control --help on the host to check what its installed version accepts 12:

ModeWhat it doesIn a phone workflow
default (also accepted as manual)Reads usually run without asking; most edits, shell commands and network access prompt firstMore manual approvals; useful for an unfamiliar repo
acceptEditsOrdinary edits and common file commands within the working scope are approved automatically; protected paths and other exceptions still promptTests and git push usually prompt, but an existing allow rule may approve them
autoApplies permission rules and built-in checks, sending actions to a separate classifier model when neededReduces prompts without guaranteeing safety; not every action reaches the classifier
planResearches and writes a plan; no code edits until you approve the planSee the approach before letting it work
dontAskDenies actions that would need a permission prompt by default; permitted reads and tools can runUseful for scripts with permissions set in advance; an unapproved git push is denied
bypassPermissionsSkips ordinary permission prompts; explicit deny and ask rules and some safeguards still applyNot recommended for this kind of server holding a token; see below

Start with acceptEdits if you want fewer prompts for ordinary edits. A permission mode sets the baseline; allow, ask and deny rules and other settings also affect what runs. The mode alone does not guarantee that every push waits for you 2. Permission prompts and AskUserQuestion questions stay open until you answer, so checking your phone later won’t silently approve them. Other forwarded dialogs can expire 1.

What should CLAUDE.md say so every session follows the rules?

A CLAUDE.md (or .claude/CLAUDE.md) at the project root is loaded at the start of every session and shared through version control 4. Put the workflow rules there and you don’t have to type them on your phone every time.

The example uses this website’s test command, npx vitest run. Replace it with the actual test command for your repository. Before adopting this PR workflow, replace any conflicting instruction to work directly on main; don’t leave both rules in place.

## Git and PR rules
- One new branch per task (feat/…, fix/…). Never commit on main.
- Never push to main and never force push.
- Run `npx vitest run` before pushing. If it fails, don't push; paste the error to me.
- Open PRs with `gh pr create --base main --title "…" --body "…"`. Don't use --fill.
- PR description has four sections: ## Why, ## What changed, ## How it was verified, ## Risks.
- After opening the PR, send me the link, then run `gh pr checks --watch` and tell me the CI result.
- Do not merge the PR. After reporting the checks, stop and leave the GitHub merge to me.

gh pr checks --watch waits until CI finishes 6, so you see “CI passed” or which check failed right on your phone.

A few limits to know:

  • CLAUDE.md is guidance, not a lock. The docs say Claude treats it as context, not enforced configuration; to block an action regardless of what Claude decides you need a hook or an outside rule 4. The GitHub ruleset below blocks updates to main that aren’t associated with a PR.
  • Merge the rules, then update the local ref. With the default fresh mode, merge CLAUDE.md into the default branch and fetch before creating a worktree, so its starting commit includes the rules 3.
  • Keep it short. The docs suggest staying under 200 lines per CLAUDE.md; longer files use more context and are followed less reliably 4.

How do you word the request so it branches and opens a PR?

Open the Claude app and tap Code to reach the session list; Remote Control sessions show a computer icon with a green dot when online 1. Start a new session and cover scope, acceptance and delivery in one message:

Fix the typo "recieve" on the about page.
Work on a new branch fix/about-typo, run npx vitest run,
and if it passes, push the branch and open a PR to main with gh pr create,
using the four sections from CLAUDE.md. Don't touch main or merge the PR.
Send me the PR link.
  • Name the branch yourself. With a name you chose, the PR and the cleanup later are easy to find.
  • One task per session. Worktrees are per session, so two unrelated changes in two sessions become two branches and two PRs.
  • Make acceptance concrete. “npx vitest run passes” is easier to check than “make sure nothing broke”.

How do you review in GitHub Mobile and get Claude to address comments?

GitHub Mobile shows a PR’s Files changed, and its merge box shows the state of reviews, checks and overall mergeability; when those pass, you can merge directly from the app 10. Commenting, approving and merging all work in the app 9.

  1. Open Claude’s PR from the notification or the PR list, and read the Why and How it was verified sections first.
  2. Go through Files changed one file at a time.
  3. Leave comments that say which line and what you want instead.
  4. Go back to the Claude session and ask it to handle them, for example: “Read the comments on PR #12, make the changes, run the tests, push to the same branch, and list what you changed for each comment.”
  5. Merge once the checks are green.

To read the comments, Claude can run gh pr view 12 --comments, which prints the PR’s comments and reviews 7; review comments attached to specific lines of the diff come from gh api repos/{owner}/{repo}/pulls/12/comments 8. Pushing to the same branch updates the PR, so there’s nothing to reopen.

You can’t approve your own PR. GitHub doesn’t let pull request authors approve their own pull requests 13. Claude uses your token, so you are the PR’s author: reviewing it in the app, you can comment but not Approve. Collaborators, if you have any, can approve from the app; on a solo repo, merge once the diff looks right and the checks pass.

How do you set up a ruleset that blocks pushes to main and merges without CI?

A ruleset lives on GitHub’s side, so it applies whether or not Claude follows CLAUDE.md. This setup requires updates to main to be associated with a PR; it doesn’t prohibit every form of git push main. A qualifying PR merge commit may still be pushed directly 12. Public repos can use rulesets on the free plan; private repos need GitHub Pro, Team or Enterprise Cloud 11.

  1. Go to the repo’s Settings → Rules → Rulesets, click New ruleset, then New branch ruleset 19.
  2. Set Enforcement status to Active. The default is Disabled, and a disabled ruleset does nothing.
  3. Under Target branches, add the default branch (main).
  4. Check Require a pull request before merging. Every change to main has to go through a PR 12. On a solo repo, leave required approvals at 0, since you can’t approve your own PR.
  5. Check Require status checks to pass and add the CI checks you require. Those required checks must be satisfied before merging 12.
  6. Keep Block force pushes and Restrict deletions, which are on by default 12.
  7. Don’t add yourself to the bypass list. The token on the server acts as your account, so if you can bypass, so can Claude.

These rules block updates without a PR and merges that fail their conditions. They don’t reserve the final merge for you. GitHub’s merge API accepts a fine-grained token with Contents: write 16. Under this setup, with required approvals at 0 and CI requirements met, the server’s token can merge too. Leaving that step to a person is a workflow agreement; the CLAUDE.md instruction is not an enforced restriction. Requiring another person’s approval takes an independent reviewer identity and a required-review rule. A token for your own account cannot distinguish you from Claude.

If you don’t have CI yet

Require status checks needs a check that runs on PRs, such as a GitHub Actions test workflow. Until you have one, turn on Require a pull request from step 4 to block updates to main without a PR, and rely on CLAUDE.md to request tests before pushing.

How do you clean up the branch and worktree after merging?

Let GitHub handle the remote branch: in the repo’s Settings → General → Pull Requests, check Automatically delete head branches, and the head branch is deleted after the PR merges 14.

Before cleaning up manually, end the session using that worktree. Run the following from a separate session or SSH shell in the main checkout, not from the session whose directory you are removing. Replace the example path, branch and PR number with the real values.

  1. Confirm that the PR merged, then locate its worktree. Check that state is MERGED and verify headRefName. A closed PR is not necessarily merged 7.

    gh pr view 12 --json state,headRefName,mergedAt
    git fetch origin --prune
    git worktree list
  2. Check for remaining work before removing the worktree. Look for uncommitted changes and untracked files. Git refuses to remove a dirty worktree; save anything you need elsewhere, and use --force only for content you have decided to discard 315.

    git -C /path/to/worktree status --short
    git worktree remove /path/to/worktree
  3. Delete the local branch:

    git branch -d fix/about-typo

git branch -d checks whether commits are merged into the upstream branch or HEAD; it doesn’t check the GitHub PR state 17. Squash and rebase merges change commit ancestry, so -d can refuse even after a PR has merged 18. Use git branch -D fix/about-typo only after confirming MERGED and checking that the branch has no later or unsaved work you need. Don’t use -D as an automatic retry.

If the worktree is locked, first check that no session or other process is still using it. Once you have confirmed the lock is stale, run git worktree unlock /path/to/worktree and remove it 3.

What happens when the network drops or the server stops?

If the machine is awake but can’t reach the network, server mode gives up after roughly 10 minutes and the claude remote-control process exits. The documented fix is to run it again 1. A systemd service can use Restart=always to restart the process after it exits. That is the purpose of the setting, not evidence that this host has passed a reconnection test.

After stopping a server with Ctrl+C, running claude remote-control again in the same folder can bring its sessions back for about four hours. This requires that no other Remote Control server was running in that directory and that the stopped server wasn’t started with --no-create-session-in-dir 1. If recovery fails, check that the original worktree, branch and commits are still there, then continue in that worktree rather than creating another branch with the same name.

What is the phone good for, and what isn’t it?

  • Small changes are a good fit. Typos, copy, config values, a bug across one or two files: the diff fits on one screen.
  • Review back-and-forth is a good fit. Comment, ask Claude to fix, read the new diff; each round is short.
  • Big refactors are not. A diff across dozens of files can’t be read properly on a phone, and structural problems won’t show. Review those at a computer; from the phone, at most ask Claude to open a draft PR.
  • Visual changes need another check. On the phone you’re reading code, not the result. Confirm front-end changes in a preview environment or back at your computer.

FAQ

Do I need an Oracle server?

No. A machine that meets Claude Code’s system requirements and stays on and connected can host it; the Remote Control process needs to keep running 1. Oracle is the host used here, not a requirement.

Which Claude plan do I need?

Remote Control is available on Pro, Max, Ultra, Team and Enterprise plans, and API keys are not supported. On Team and Enterprise, an Owner has to turn it on in the admin settings first 1.

Can several sessions work on the same repo at once?

Yes. With --spawn=worktree, each new session has its own worktree and branch, keeping file edits separate 13. --capacity sets the limit. If two PRs touch the same code, the one merged second may hit a conflict. Since the example rules prohibit force pushes, merge the latest main into an already-pushed branch, resolve conflicts and rerun the tests.

Go deeper How to Get an Oracle Cloud Free ARM Instance in 2026: Claude Code 24/7 and a Git Repo Workflow Getting the A1 instance, running Remote Control under systemd and connecting it to GitHub, step by step.

Sources

  1. 1. Remote Control · Claude Code Docs · checked 2026-11-13
  2. 2. Permission modes · Claude Code Docs · checked 2026-11-13
  3. 3. Run parallel sessions with worktrees · Claude Code Docs · checked 2026-11-13
  4. 4. How Claude remembers your project · Claude Code Docs · checked 2026-11-13
  5. 5. gh pr create · GitHub CLI Manual · checked 2026-11-13
  6. 6. gh pr checks · GitHub CLI Manual · checked 2026-11-13
  7. 7. gh pr view · GitHub CLI Manual · checked 2026-11-13
  8. 8. REST API endpoints for pull request review comments · GitHub Docs · checked 2026-11-13
  9. 9. GitHub Mobile · GitHub · checked 2026-11-13
  10. 10. Working with pull requests on GitHub Mobile is now much easier · GitHub Changelog · 2021-05-12
  11. 11. About rulesets · GitHub Docs · checked 2026-11-13
  12. 12. Available rules for rulesets · GitHub Docs · checked 2026-11-13
  13. 13. Approving a pull request with required reviews · GitHub Docs · checked 2026-11-13
  14. 14. Managing the automatic deletion of branches · GitHub Docs · checked 2026-11-13
  15. 15. git-worktree · Git Documentation · checked 2026-11-13
  16. 16. Merge a pull request · GitHub Docs · checked 2026-11-13
  17. 17. git-branch · Git Documentation · checked 2026-11-13
  18. 18. Pull request merges · GitHub Docs · checked 2026-11-13
  19. 19. Creating rulesets for a repository · GitHub Docs · checked 2026-11-13

About the author

Kelvin Wang

Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.

More about me