anthropics / anthropics/claude-code
[FEATURE] Start new Remote Control sessions in any git subdirectory of a published root, instead of one server per pre-registered directory
- Dominant language
- Python
- Stars
- 145k
- Forks
- 23.1k
- PR merge metrics
- PR metrics pending
Description
### Preflight
- [x] I searched existing requests — no issue covers this. The nearest, #65972, asks for the mobile Code tab to list and steer background sessions that are *already running*; this asks for the complement — **starting new ones remotely**, in a repo the host hasn't pre-registered. #61160 and #57543 are closed/stale and concern the mobile UI and SSH transport respectively.
- [x] This is a single feature request.
### Problem Statement
Remote Control can already originate sessions — that part is not the gap. The gap is **where** it can originate them.
`claude remote-control` is single-directory by design. Its own help text: *"a persistent server that accepts multiple concurrent sessions in the current directory."* Serving N repositories means N processes in N terminals, each started by hand at the desk.
There is a multi-directory mechanism — `~/.claude/daemon.json` takes a `remoteControl` array of `{dir, name, spawnMode}` entries, with a "New Remote Control server" flow for adding them — but it requires **pre-registering every directory in advance**, and on v2.1.220 those workers never actually start (filed separately as #81456).
Both paths share the same limitation even when working: the set of remotely-reachable directories is a static list I have to curate from the machine I'm trying to get away from. On a machine with a dozen repositories, the common case — *"start a session in a repo I already have cloned"* — requires desk access first, which defeats the purpose of remote origination.
### Proposed Solution
Let a host publish a **root**, and let the remote client pick any git repository or worktree underneath it.
Concretely:
- The host publishes one root — the `claude agents` working directory, plus any `--add-dir` paths — instead of N individually registered directories.
- From claude.ai/code or the mobile Code tab, "New session" offers a picker scoped to git repos and worktrees discovered under that root. Same selection semantics as `@`-mentioning a directory in the agent view, so there's one mental model rather than two.
- The new session inherits the host's dispatch defaults exactly as a locally-started one does: `--model`, `--agent`, `--effort`, `--permission-mode`, `--settings`, `--mcp-config`.
- The existing per-entry `spawnMode` composes directly: a discovered repo with `worktree` mode yields *"each session gets its own git worktree"* with nothing registered in advance.
The transport for this largely exists — this is discovery and scoping on top of it, not a new session model.
### Alternative Solutions
- **One `claude remote-control` per repo.** What works today. Manual, one process and terminal per directory, curated in advance from the desk.
- **One server over a parent directory.** Running `claude remote-control` from a directory containing many repos gives breadth from a single process, but the parent isn't itself a git repo, so `spawnMode: worktree` is unavailable and every session shares one working tree — concurrent sessions can conflict with each other and with my own uncommitted work.
- **Pre-registering each repo in `daemon.json`.** The intended multi-directory path, but still a static hand-curated list, and currently inert (see #81456).
- **Cloud / web sessions.** A different machine — no local worktrees, no uncommitted state, no local MCP servers. Not a substitute for driving my own box.
### Use Case Example
1. My always-on desktop has ~10 repositories checked out under one workspace directory. I publish that root once.
2. On my phone, away from the desk, I decide to kick off a dependency bump in a repo I have *not* pre-registered.
3. "New session" shows the repos under that root. I pick one, and because it's set to worktree mode the session gets its own isolated worktree — no interference with whatever I left in that checkout.
4. I send the prompt and walk away. Back at the desk, the session is there in the agent view.
Today step 2 is impossible without first walking to the desk to register that directory.
### Additional Context
- **Directory scope should stay a hard boundary.** Static registration has one real virtue: a remote client can only reach directories explicitly published. Dynamic discovery relaxes that, so the picker should be bounded to git repos at or under the published root plus `--add-dir` — never free filesystem traversal. A remote client should not be able to open a session in `~/.ssh`.
- **Daemon lifetime is a prerequisite.** With service install disabled, the daemon is transient: `daemon status` reports it as *"started on-demand by `claude agents`"*, and it exits when the last client disconnects. Published roots that vanish when an unrelated agent view is closed would be worse than not having them. This affects #65972 equally.
- **Permission prompts.** A remotely-spawned session that hits a permission prompt with nobody at the terminal should route the prompt to the remote client.
- **Multi-host.** Publishing a root from both a desktop and a laptop means the client must disambiguate hosts, not just sessions. The hostname-derived name prefix is a start.
- **Relationship to #65972:** that issue makes already-running background agents visible and steerable from mobile; this one lets me create work that isn't running yet. Together they'd close the loop; either is useful alone.
---
**Priority:** Medium
**Feature Category:** Other — Remote Control / agent view
*Observed on Claude Code v2.1.220, Linux (WSL2).*
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the `claude remote-control` and `claude agents` entry points, then read the existing `~/.claude/daemon.json` remoteControl configuration and the related daemon lifetime behavior. Done means a published root and `--add-dir` paths scope repository and worktree discovery, preserve dispatch defaults and `spawnMode`, and prevent traversal outside those boundaries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, python
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100