> Deprecation Notice: This repository is no longer maintained. It has been integrated as a VS Code provider in agentv.

Subagent

Subagent is a CLI tool for managing workspace agents across different providers. It currently supports VS Code workspace agents with plans to add support for Azure AI Agents, GitHub Copilot CLI, OpenAI Codex and Claude Code.

Features

$3

Manage isolated VS Code workspaces for parallel agent development sessions:

- Provision subagents: Create a pool of isolated workspace directories
- Chat with agents: Automatically claim a workspace and start a VS Code chat session
- Lock management: Prevent conflicts when running multiple agents in parallel

Prerequisites

- Node.js 20+
- npm or pnpm
- VS Code installed for workspace agent functionality

Quick Start

$3

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

License

MIT - See LICENSE file for details.

Contributing

This project is under active development. Contributions are welcome!

> Deprecation Notice: This repository is no longer maintained. It has been integrated as a VS Code provider in agentv.

Subagent

Features

$3

Prerequisites

- Node.js 20+
- npm or pnpm
- VS Code installed for workspace agent functionality

Quick Start

$3

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

License

MIT - See LICENSE file for details.

Contributing

This project is under active development. Contributions are welcome!