Overview & Architecture
A VS Code extension to start, monitor, and resume autonomous AI coding agents (Claude Code, OpenAI Codex, Antigravity CLI) on a remote devbox over VS Code Remote - SSH. Every agent runs in its own dedicated git worktree and tmux session, continuing execution uninterrupted even when your laptop sleeps or disconnects.
Managing AI Agents on a Remote Devbox
Read about the design decisions, trade-offs, and daily workflow that inspired this extension.
What it does
One-Click Agent Worktree Provisioning
Start Claude Code, Codex, or Antigravity (agy) in an isolated git worktree (<worktreesRoot>/<repo>/<name>) on a dedicated branch (agent/<name>), inside an independent tmux session.
Uninterrupted Remote Execution
Agents execute on the remote Linux host inside tmux. They never terminate when your laptop closes, Wi-Fi drops, or the SSH connection is interrupted.
Active Session Control Plane & Explorer
Focusing a session immediately aligns your workspace: the worktree folder appears in VS Code, diffs render in the editor, and the terminal connects directly to the tmux session.
Process Inspection & Orphan Detection
Inspects running agent PIDs across the server via /proc, detecting whether they are active in tmux, running via SSH, or orphaned, with safe kill controls.
Safe Worktree Cleanup
Clean up stops tmux sessions and tears down worktrees only when there are no uncommitted or untracked changes, keeping git branches safe.
Smart Notifications & Status Hooks
Lightweight status hooks notify you immediately when an agent finishes its turn or pauses waiting for user permission or input.
Chat History & Resume
Browse past agent chat sessions by repository and worktree, and resume previous discussions directly in their original directory.
Prerequisites & Environment
On your laptop
- ✔VS Code
- ✔Remote - SSH (or WSL / Dev Containers / Codespaces)
On the remote server
- ✔Linux
- ✔tmux >= 3.2
- ✔git >= 2.38
- ✔bash
- ✔claude / codex / agy CLI
Quick start
Give this to Claude / Codex / your agent
Let your coding agent set everything up. Paste this into Claude Code, Codex or another agent that can run commands on your laptop:
Set up the VS Code extension "Devbox Agents" (royberris.devbox-agents) for me.
Follow the README: https://github.com/royberris/devbox-vscode-extension#readme
Ask me first for the SSH host of my remote dev box if you don't know it.
1. Laptop: make sure VS Code and the "Remote - SSH" extension
(ms-vscode-remote.remote-ssh) are installed, and that `ssh <host>` works.
2. Server: install the requirements from the README section "What you install
yourself": Linux, tmux >= 3.2, git >= 2.38, bash, and at least one agent CLI
(Claude Code, Codex or Antigravity `agy`; ask me which). Verify the versions
in a login shell (`ssh <host> bash -lc ...`). Use sudo only where needed and
ask before changing system packages. Do not log in to the agents for me; tell
me to run `claude` / `codex login` / `agy` on the server myself if needed.
3. Extension: it must be installed on the remote side ("Getting started",
step 2). Try `code --remote ssh-remote+<host> --install-extension
royberris.devbox-agents`; if that doesn't work, ask me to install it from the
Extensions view in a VS Code window connected to the server.
4. Settings: follow "Getting started". Find where my repositories live on the
server and set devboxAgents.repoRoots and devboxAgents.worktreesRoot in the
remote machine settings (keep worktrees outside the repositories, see
"Where to put worktrees").
5. Notifications: explain "Status hooks", then ask me whether to install them.
If my agent config is generated by dotfiles or provisioning, add the hooks
there instead, as described in the README.
Finish with a short summary: what you installed, the versions, the settings you
set, and anything I still have to do by hand.// manual setup (5 steps)
- 1Connect VS Code to the server (e.g. Remote-SSH: Connect to Host…).
- 2In that window, install Devbox Agents from the Extensions view (or VS Code Marketplace).
- 3Run 'Devbox Agents: Open Settings' and verify repoRoots (default ~/repos) and worktreesRoot (default ~/worktrees).
- 4Run 'Devbox Agents: Install Status Hooks...' once to get notifications when agents wait for input or finish.
- 5Click '+' in the Sessions view and select Claude Code, Codex, or Antigravity.
// server CLI installation snippet
# Install tmux and git
sudo apt update && sudo apt install -y tmux git
# Claude Code
curl -fsSL https://claude.ai/install.sh | bash
claude # log in once
# Codex
npm install -g @openai/codex
codex login
# Antigravity CLI
curl -fsSL https://antigravity.google/cli/install.sh | bash
agy # log in onceConfiguration settings
All settings use machine scope (saved per remote connection in VS Code Remote Settings):
| Setting | Default | Description |
|---|---|---|
| devboxAgents.repoRoots | ["~/repos"] | Directories containing your source repositories on the remote server. |
| devboxAgents.worktreesRoot | "~/worktrees" | Base directory where isolated git worktrees are created. |
| devboxAgents.branchPrefix | "agent/" | Prefix for branches created per session. |
| devboxAgents.focusMode | "activeSessions" | Workspace behavior on focus (activeSessions, swapFolder, addFolder, terminalOnly). |
| devboxAgents.notify | ["waiting", "idle"] | Status events that trigger notifications. |