DEV Community

Will Gwyn
Will Gwyn

Posted on

how to run long-lived claude code agents from your phone

#ai #opensource #productivity #claudecode

i ran my newsletter business from my phone for 14+ days in september while elk hunting. phone, Starlink Mini, no laptop. the agents ran on my computer at home and i steered them from the Claude app.

this is the how-to version. three pieces: claude code remote control, keeping the host machine awake, and keeping agent sessions healthy for days. disclosure up front: the third piece uses aigent-os, an open-source thing i built (https://github.com/wrg32786/aigent-os).

what is claude code remote control?

remote control connects the Claude mobile app (iOS and Android) or claude.ai/code to a Claude Code session running on your own machine. the session never leaves your computer. your filesystem, MCP servers, tools, and project config all stay local. the phone is a window into that session.

you can send messages from the terminal, browser, and phone interchangeably, and the conversation stays in sync. you can also attach photos and files from your phone and they get passed into the local session.

this is different from cloud sessions, which run on Anthropic's infrastructure and keep going with your laptop closed. remote control is what you want when the work depends on your local setup, which for long-running agents it usually does.

what do you need before you start?

  • a Pro, Max, Team, or Enterprise plan. API keys are not supported. on Team and Enterprise an owner has to enable it in admin settings.
  • be logged in. run claude and use /login to sign in through claude.ai.
  • talk to api.anthropic.com directly. it doesn't work through Bedrock, Google's platform, Microsoft Foundry, or a custom ANTHROPIC_BASE_URL proxy.
  • don't set CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or DISABLE_GROWTHBOOK. those turn it off.

how do you start a remote control session?

two ways.

start a new one in your project directory:

cd ~/my-agent
claude remote-control
Enter fullscreen mode Exit fullscreen mode

or, if you already have a session open, run this inside it:

/remote-control
Enter fullscreen mode Exit fullscreen mode

then connect from your phone. either press space in the terminal to show a QR code and scan it with the Claude app, or open the Claude app, tap Code, and pick the session from the list.

for multiple agents, i run one session per agent, each in its own directory, so each shows up as its own session in the app.

what happens if the computer sleeps or the network drops?

per the docs, if your machine sleeps or the network drops, Claude Code reconnects automatically when the machine comes back online. that's nice, but "comes back online" is doing a lot of work. if the machine is asleep, your agents aren't doing anything. the computer has to stay on and the claude process has to keep running.

so the real job is keeping the host awake.

how do you keep the host computer awake?

macOS:

caffeinate -dimsu
Enter fullscreen mode Exit fullscreen mode

run it in its own terminal (or tmux pane) and leave it. also check System Settings for sleep and power options, and look at "start up automatically after a power failure" if your mac has it.

Linux (systemd):

systemd-inhibit --what=idle:sleep --why="agents running" sleep infinity
Enter fullscreen mode Exit fullscreen mode

or disable sleep targets entirely on a dedicated box:

sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target
Enter fullscreen mode Exit fullscreen mode

Windows:

powercfg /change standby-timeout-ac 0
powercfg /change hibernate-timeout-ac 0
Enter fullscreen mode Exit fullscreen mode

other things worth doing before you leave for real:

  • run sessions inside tmux so a closed terminal window doesn't kill them
  • plug in, and ideally put it on a small UPS
  • turn off automatic OS update restarts for the trip
  • test it. leave the house for an afternoon and drive everything from your phone

why do long-lived claude code sessions degrade?

the context window fills up. a session that's been going for a day is carrying a lot of stale stuff, and quality drops. compaction helps a bit, but you're summarizing a summary of a summary, and things get lost in ways you can't see.

for a session you want running for weeks, you need state that lives outside the context window.

how does aigent-os keep agents running for weeks?

the loop is simple:

  1. the agent saves a context capsule: what it's working on, what's done, what's next, open questions.
  2. it runs /clear, so the context is actually empty.
  3. it resumes from the capsule plus its long-term memory, which is git-backed.

so every agent regularly starts fresh, but it starts fresh knowing what it was doing. because memory is in git, you get history and diffs for free, and you can see exactly what an agent "knows."

this matters even more with remote control. on a phone over satellite, you want short, clear check-ins. a session that's clean and knows its own state answers "what happened today?" way better than one that's 180k tokens deep.

i run four agents this way: an overseer, a newsletter agent, a builder, and a clerical/job assignment agent. separate roles mean when i check in from my phone, i know exactly who to ask.

docs are at https://wrg32786.github.io/aigent-os/.

what does a phone check-in actually look like?

open the Claude app, tap Code, pick the agent. ask what happened since last time, answer whatever it saved up for me, approve or redirect, close the app. most of the work is the agents doing things. my part is steering.

FAQ

do my agents run in the cloud with remote control?
no. they run on your machine. the phone and browser are just interfaces to that local session.

can i use an API key?
no. remote control needs a Pro, Max, Team, or Enterprise plan and a claude.ai login.

what if my computer has to be off?
then remote control won't work. use Claude Code cloud sessions instead, which run on cloud infrastructure.

does it work on a slow connection like Starlink?
it worked for me for two weeks on a Starlink Mini. your mileage will vary with signal.

do i need aigent-os to use remote control?
no. remote control works with any Claude Code session. aigent-os is what keeps sessions from degrading when you want them running for days or weeks.

notes / sources

Top comments (0)