Claude Remote Session Manager
Manage Claude Code --remote-control sessions running in Terminal.app. Designed for remote desktop clients that let users control Claude Code from mobile devices.
State Directory
All session state lives in ~/.claude-remote/. On every skill invocation, always run the cleanup script first to sync state with reality.
Scripts
This skill bundles a session manager script. All paths below are relative to the skill directory:
scripts/session-manager.sh — handles create, list, remove, cleanup, and stop operations
Get the script path:
SKILL_DIR="$(dirname "$(dirname "$(realpath "$0")")")"
# Or just use the known absolute path after reading it from the skill location
Workflow
On Every Invocation
Before doing anything else, run cleanup to remove stale entries:
bash <skill-dir>/scripts/session-manager.sh cleanup
This checks each recorded session's Terminal window still exists and removes dead entries. If any sessions were cleaned up, tell the user (e.g., "2 stale sessions were cleaned up — their Terminal windows were closed outside this tool").
Determine Intent
Parse what the user wants:
| Intent |
Triggers |
| start |
"start", "open", "launch", "new session", "remote control" |
| stop |
"stop", "close", "kill", "shut down", "exit" |
| list |
"list", "status", "show", "which sessions", "what's running" |
If ambiguous, ask.
Start Flow
Try to infer from context first. If the user's message already contains a directory name or path (e.g., "launch claude in ~/Workspace/my-app"), use it directly — skip the directory picker. Also detect any options mentioned naturally (e.g., "with opus model" → --model opus).
Only if the directory is unclear, list directories under ~/Workspace:
bash <skill-dir>/scripts/session-manager.sh list-dirs
Present as a numbered list via AskUserQuestion. Include an option to create a new directory. Note: ~/Workspace is the default root; if it doesn't exist, ask the user for their workspace path.
If creating new:
mkdir -p ~/Workspace/<new-dir-name>
Common options (only ask if not already inferred from context):
| Option |
Flag |
Default |
Example |
| Permission mode |
--permission-mode <mode> |
bypassPermissions |
--permission-mode auto |
| Model |
--model <model> |
(user default) |
--model sonnet or --model opus |
| Session name |
-n <name> |
(auto) |
-n "mobile-debug" |
| Effort level |
--effort <level> |
(user default) |
--effort high |
| Worktree |
-w, --worktree [name] |
— |
Create a git worktree for the session |
| If the user doesn't specify any, use defaults (no extra flags). |
|
|
|
Launch the session:
RESULT=$(bash <skill-dir>/scripts/session-manager.sh create <directory-path> [extra-flags...])
This opens Terminal.app via AppleScript, runs claude --permission-mode bypassPermissions --remote-control [extra-flags] in the chosen directory, and records the session.
Report the session ID, directory, and window ID to the user. Mention they can now connect via their remote control client.
Continue (Resume Last Conversation)
When the user wants to pick up where they left off in a directory (triggers: "continue", "resume", "接着上次", "继续上次的对话"), pass the -c flag to the start flow. It tells claude to continue the most recent conversation in that directory instead of starting a fresh one.
bash <skill-dir>/scripts/session-manager.sh create <directory-path> -c [other-flags...]
Notes:
-c only resumes the most recent conversation in the chosen directory. If the user wants a specific older conversation, they'll need to use claude --resume interactively instead.- Combine freely with other flags (
--model, -n, -w, etc.).
- If no prior conversation exists in that directory,
claude will fall back to a new session.
Stop Flow
Get active sessions:
bash <skill-dir>/scripts/session-manager.sh list
If no sessions: tell the user there's nothing to stop.
If one session: confirm with user, then stop it.
If multiple: present numbered list via AskUserQuestion, let user pick one or "all".
Stop the selected session(s):
bash <skill-dir>/scripts/session-manager.sh stop <session-id>
# or stop all:
bash <skill-dir>/scripts/session-manager.sh stop-all
Report what was stopped.
List Flow
Run:
bash <skill-dir>/scripts/session-manager.sh list
Present a formatted table:
# Session ID Directory Started Window
1 a1b2c3d4 ~/Workspace/my-app 10:30 today 98905
2 e5f6a7b8 ~/Workspace/api-work 09:15 today 98820
If no sessions: "No active remote sessions."
Examples
| User says |
Resolved action |
| "start a remote claude in my-app" |
create ~/Workspace/my-app |
| "launch claude in ~/code/api with opus" |
create ~/code/api --model opus |
| "接着上次的 my-app 继续" |
create ~/Workspace/my-app -c |
| "open a remote session in a worktree of api-work" |
create ~/Workspace/api-work -w |
| "stop the my-app session" |
list → match by directory → stop <id> |
| "kill all remote sessions" |
stop-all |
| "what's running?" |
list → render as table |
Important Notes
- The script uses
osascript (AppleScript) to control Terminal.app — this only works on macOS.
- Each session opens a new Terminal window (not a tab) for isolation.
- Stop uses Terminal's native "terminate process" dialog to shut down Claude Code, then closes the window.
- Session state is stored as individual JSON files in
~/.claude-remote/sessions/ — one file per session for atomicity.
1---2name: claude-remote3description: Manage **remote-control** Claude Code sessions (i.e. `claude --remote-control`, NOT regular local sessions) running in Terminal.app — start, stop, list, or resume them for mobile / remote desktop access. Triggers on "start/open/launch a remote claude", "stop/kill remote session", "list remote sessions", "continue last remote conversation in <dir>".4---56# Claude Remote Session Manager78Manage Claude Code `--remote-control` sessions running in Terminal.app. Designed for remote desktop clients that let users control Claude Code from mobile devices.910## State Directory1112All session state lives in `~/.claude-remote/`. On every skill invocation, always run the cleanup script first to sync state with reality.1314## Scripts1516This skill bundles a session manager script. All paths below are relative to the skill directory:1718- `scripts/session-manager.sh` — handles create, list, remove, cleanup, and stop operations1920Get the script path:21```bash22SKILL_DIR="$(dirname "$(dirname "$(realpath "$0")")")"23# Or just use the known absolute path after reading it from the skill location24```2526## Workflow2728### On Every Invocation2930Before doing anything else, run cleanup to remove stale entries:3132```bash33bash <skill-dir>/scripts/session-manager.sh cleanup34```3536This checks each recorded session's Terminal window still exists and removes dead entries. If any sessions were cleaned up, tell the user (e.g., "2 stale sessions were cleaned up — their Terminal windows were closed outside this tool").3738### Determine Intent3940Parse what the user wants:4142| Intent | Triggers |43|--------|----------|44| **start** | "start", "open", "launch", "new session", "remote control" |45| **stop** | "stop", "close", "kill", "shut down", "exit" |46| **list** | "list", "status", "show", "which sessions", "what's running" |4748If ambiguous, ask.4950### Start Flow51521. **Try to infer from context first.** If the user's message already contains a directory name or path (e.g., "launch claude in ~/Workspace/my-app"), use it directly — skip the directory picker. Also detect any options mentioned naturally (e.g., "with opus model" → `--model opus`).53542. Only if the directory is unclear, list directories under `~/Workspace`:55 ```bash56 bash <skill-dir>/scripts/session-manager.sh list-dirs57 ```58 Present as a numbered list via `AskUserQuestion`. Include an option to create a new directory. Note: `~/Workspace` is the default root; if it doesn't exist, ask the user for their workspace path.59603. If creating new:61 ```bash62 mkdir -p ~/Workspace/<new-dir-name>63 ```64654. Common options (only ask if not already inferred from context):6667 | Option | Flag | Default | Example |68 |--------|------|---------|---------|69 | Permission mode | `--permission-mode <mode>` | `bypassPermissions` | `--permission-mode auto` |70 | Model | `--model <model>` | (user default) | `--model sonnet` or `--model opus` |71 | Session name | `-n <name>` | (auto) | `-n "mobile-debug"` |72 | Effort level | `--effort <level>` | (user default) | `--effort high` |73 | Worktree | `-w, --worktree [name]` | — | Create a git worktree for the session |74 If the user doesn't specify any, use defaults (no extra flags).75765. Launch the session:77 ```bash78 RESULT=$(bash <skill-dir>/scripts/session-manager.sh create <directory-path> [extra-flags...])79 ```80 This opens Terminal.app via AppleScript, runs `claude --permission-mode bypassPermissions --remote-control [extra-flags]` in the chosen directory, and records the session.81826. Report the session ID, directory, and window ID to the user. Mention they can now connect via their remote control client.8384### Continue (Resume Last Conversation)8586When the user wants to pick up where they left off in a directory (triggers: "continue", "resume", "接着上次", "继续上次的对话"), pass the `-c` flag to the start flow. It tells `claude` to continue the most recent conversation in that directory instead of starting a fresh one.8788```bash89bash <skill-dir>/scripts/session-manager.sh create <directory-path> -c [other-flags...]90```9192Notes:93- `-c` only resumes the **most recent** conversation in the chosen directory. If the user wants a specific older conversation, they'll need to use `claude --resume` interactively instead.94- Combine freely with other flags (`--model`, `-n`, `-w`, etc.).95- If no prior conversation exists in that directory, `claude` will fall back to a new session.9697### Stop Flow98991. Get active sessions:100 ```bash101 bash <skill-dir>/scripts/session-manager.sh list102 ```1031042. If no sessions: tell the user there's nothing to stop.1051063. If one session: confirm with user, then stop it.1071084. If multiple: present numbered list via `AskUserQuestion`, let user pick one or "all".1091105. Stop the selected session(s):111 ```bash112 bash <skill-dir>/scripts/session-manager.sh stop <session-id>113 # or stop all:114 bash <skill-dir>/scripts/session-manager.sh stop-all115 ```1161176. Report what was stopped.118119### List Flow1201211. Run:122 ```bash123 bash <skill-dir>/scripts/session-manager.sh list124 ```1251262. Present a formatted table:127 ```128 # Session ID Directory Started Window129 1 a1b2c3d4 ~/Workspace/my-app 10:30 today 98905130 2 e5f6a7b8 ~/Workspace/api-work 09:15 today 98820131 ```1321333. If no sessions: "No active remote sessions."134135## Examples136137| User says | Resolved action |138|-----------|-----------------|139| "start a remote claude in my-app" | `create ~/Workspace/my-app` |140| "launch claude in ~/code/api with opus" | `create ~/code/api --model opus` |141| "接着上次的 my-app 继续" | `create ~/Workspace/my-app -c` |142| "open a remote session in a worktree of api-work" | `create ~/Workspace/api-work -w` |143| "stop the my-app session" | `list` → match by directory → `stop <id>` |144| "kill all remote sessions" | `stop-all` |145| "what's running?" | `list` → render as table |146147## Important Notes148149- The script uses `osascript` (AppleScript) to control Terminal.app — this only works on macOS.150- Each session opens a **new Terminal window** (not a tab) for isolation.151- Stop uses Terminal's native "terminate process" dialog to shut down Claude Code, then closes the window.152- Session state is stored as individual JSON files in `~/.claude-remote/sessions/` — one file per session for atomicity.
ben2pc