CLI tool for managing workspace agents across VS Code
npm install subagent> Deprecation Notice: This repository is no longer maintained. It has been integrated as a VS Code provider in agentv.
bash
Install from npm
npm install -g subagent
Or for development (install from source)
git clone
cd subagent
pnpm install
pnpm build
pnpm link --global
`
$3
1. Provision and optionally warm up subagent workspaces:
`bash
subagent code provision --subagents 5 [--warmup]
`
This creates 5 isolated workspace directories in ~/.subagent/vscode-agents/ (or ~/.subagent/vscode-insiders-agents/ for code-insiders). Add --warmup to open the newly provisioned workspaces immediately.
2. Start a chat with an agent (async mode - default):
`bash
subagent code chat -q "Your query here" [--prompt ]
`
This claims an unlocked subagent, copies your prompt file (if provided) and any attachments, opens VS Code with a wakeup chatmode, and returns immediately.
The agent writes its response to a file that you can monitor or read later.
3. Start a chat with an agent (sync mode - wait for response):
`bash
subagent code chat -q "Your query here" [--prompt ] --wait
`
This blocks until the agent completes and prints the response to stdout.
4. Send multiple queries to the same agent:
`bash
subagent code chat -q "summarize the repo" -q "list TODOs" -q "suggest tests" --wait
`
This sends all queries to the same subagent workspace, with each query running in its own isolated context.
5. Use a custom workspace template:
`bash
subagent code chat -q "Your query here" --workspace-template ./my-workspace.code-workspace
`
This uses a custom .code-workspace file with your preferred settings, extensions, and folder configurations.
Workspace Path Resolution: When using a custom template, the system automatically:
- Resolves all relative paths (including ".") in the template to absolute paths based on the template file's directory
- Inserts { "path": "." } as the first folder entry (which will resolve to the subagent directory when the workspace is opened)
- Preserves absolute paths unchanged
For example, if your template at /home/user/templates/my-template.code-workspace contains:
`json
{
"folders": [
{ "path": "./lib" },
{ "path": "/absolute/path" }
]
}
`
The resulting workspace file in the subagent directory will become:
`json
{
"folders": [
{ "path": "." },
{ "path": "/home/user/templates/lib" },
{ "path": "/absolute/path" }
]
}
`
This ensures that:
- The subagent directory is always accessible (via the "." entry)
- Template folders remain accessible at their original locations
- You can reference shared libraries or resources from your template location
$3
Provision subagents:
`bash
subagent code provision --subagents [--force] [--target-root ] [--warmup]
`
- --subagents : Number of workspaces to create
- --force: Unlock and overwrite all subagent directories regardless of lock status
- --target-root : Custom destination (default: ~/.subagent/vscode-agents or ~/.subagent/vscode-insiders-agents for code-insiders)
- --dry-run: Preview without making changes
- --warmup: Launch VS Code for the provisioned workspaces once provisioning finishes
Warm up workspaces:
`bash
subagent code warmup [--subagents ] [--target-root ] [--dry-run]
`
- --subagents : Number of workspaces to open (default: 1)
- --target-root : Custom subagent root directory (default: ~/.subagent/vscode-agents or ~/.subagent/vscode-insiders-agents for code-insiders)
- --dry-run: Show which workspaces would be opened
Start a chat with an agent:
`bash
subagent code chat -q [--prompt ] [--workspace-template ] [--attachment ] [--wait] [--dry-run]
`
- -q, --query : User query to pass to the agent (required, repeatable for multiple queries)
- --prompt : Path to a prompt file to copy and attach (optional)
- --workspace-template : Path to a custom .code-workspace file to use as template (optional)
- --attachment / -a: Additional files to attach (repeatable)
- --wait / -w: Wait for response and print to stdout (sync mode). Default is async mode.
- --dry-run: Preview without launching VS Code
Note: By default, chat runs in async mode - it returns immediately after launching VS Code, and the agent writes its response to a timestamped file in the subagent's messages/ directory. Use --wait for synchronous operation.
When multiple queries are provided (using multiple -q options), all queries are sent to the same subagent workspace with each running in its own isolated context.
List provisioned subagents:
`bash
subagent code list [--target-root ] [--json]
`
- --target-root : Custom subagent root directory (default: ~/.subagent/vscode-agents or ~/.subagent/vscode-insiders-agents for code-insiders)
- --json: Output results as JSON
Unlock subagents:
`bash
subagent code unlock [--subagent ] [--all] [--target-root ] [--dry-run]
`
- --subagent : Specific subagent to unlock (e.g., subagent-1)
- --all: Unlock all subagents
- --target-root : Custom subagent root directory (default: ~/.subagent/vscode-agents or ~/.subagent/vscode-insiders-agents for code-insiders)
- --dry-run: Show what would be unlocked without making changes
VS Code Insiders Support:
All commands are also available with code-insiders instead of code:
`bash
subagent code-insiders provision --subagents 3
subagent code-insiders chat -q "query" --prompt
subagent code-insiders warmup
subagent code-insiders list
subagent code-insiders unlock --all
`
Development
`bash
Install dependencies
npm install
Build the project
npm run build
Run in development mode (uses tsx for direct TypeScript execution)
npm run dev -- code provision --subagents 1 --dry-run
Link for local testing
npm link
Run tests (once test suite is added)
npm test
`
Project Structure
`
subagent/
├── src/
│ ├── cli.ts # Main CLI entry point
│ ├── utils/
│ │ ├── fs.ts # File system utilities
│ │ └── time.ts # Time utilities
│ └── vscode/
│ ├── agentDispatch.ts # Agent dispatch and workspace management
│ ├── constants.ts # Constants and default paths
│ ├── provision.ts # Provisioning logic
│ └── subagent_template/ # Workspace template
│ ├── subagent.code-workspace
│ └── wakeup.chatmode.md
├── dist/ # Compiled JavaScript output
├── package.json # Package configuration
├── tsconfig.json # TypeScript configuration
└── README.md # This file
`
How It Works
$3
Each subagent is an isolated VS Code workspace directory:
- Provisioned in ~/.subagent/vscode-agents/subagent-N/ (or ~/.subagent/vscode-insiders-agents/subagent-N/ for code-insiders)
- Contains a .code-workspace file
- Uses a subagent.lock file to prevent concurrent access
- Messages exchanged in a messages/ subdirectory
$3
1. Provision: Creates workspace directories from a template
2. Lock: When dispatching, claims the first unlocked subagent
3. Launch: Opens VS Code with the workspace and a chat session
4. Execute: Agent processes the query and writes results
5. Unlock: Agent signals completion by unlocking itself
$3
- Async (default): Returns immediately, agent works in background
- Sync (--wait`): Blocks until agent completes and prints response