Terminal Orchestrator

Built for Agentic Workflows

Running AI-assisted delivery usually means opening the same terminal stack over and over: planner, QA, fixes, task executors, then repeating that for every phase.

Terminal Orchestrator turns that setup into one action.

If your workflow includes multiple agents, role-based prompts, handoffs, and rapid task execution, this extension gives you a repeatable command center inside VS Code—without the tab chaos.

Why teams install it

Launch a complete multi-role terminal workspace in seconds.
Standardize how your team boots agent sessions (commands, prompts, env, layout).
Scale from solo work to agile/agency-style delivery with profiles and phase transitions.
Reduce setup fatigue so you can spend time shipping, not arranging terminals.

Marketplace Copy

Short description

Launch and manage a full AI-agent terminal workflow in seconds with role-based terminals, prompts, task sourcing, handoffs, and health checks.

Preview hooks (160 chars)

Build faster with organized AI-agent terminals: one command for roles, tasks, prompts, handoffs, and health checks—no more terminal setup chaos.
Turn VS Code into an agentic command center: instantly launch role-based terminals, task flows, and phase handoffs with reusable team profiles.
Stop rebuilding terminal layouts every sprint. Spin up your full AI workflow—planner, QA, fixes, tasks—in one action and stay in flow.

Terminal Orchestrator launches a complete multi-role terminal workspace for agentic delivery in one action. It creates structured PO/QA/Fixes/Task terminals, applies your command and prompt setup, supports dependency waits and env injection, and keeps phases repeatable with profiles, snapshots, and transitions.

For smaller screens, switch between grouped panes and separate top-level tabs without changing your workflow.

Quick Setup

Open VS Code settings JSON.
Add a minimal config like this:

{
  "phaseTerminals.leadershipCommand": "gemini",
  "phaseTerminals.qaCommand": "claude",
  "phaseTerminals.fixesCommand": "claude",
  "phaseTerminals.tasksCommand": "claude",
  "phaseTerminals.qaSystemPrompt": "@.prompts/qa-system.md",
  "phaseTerminals.preCommand": "cd ./src"
}

3.Run Create Phase Terminals from the Command Palette.

Quick Setup (Profile-Based)

If you prefer zero prompts, define a profile and run Create Phase Terminals from Profile:

{
  "phaseTerminals.profiles": [
    {
      "name": "Default Sprint",
      "phase": 2,
      "startTask": 1,
      "endTask": 5,
      "includeLeadership": true,
      "includeQa": true,
      "includeTechLeadReview": true,
      "includeFixes": true,
      "includeFixesFromQa": true,
      "includeFixesFromTechLead": true,
      "includeTasks": true,
      "leadershipCommand": "gemini",
      "qaCommand": "claude",
      "fixesCommand": "claude",
      "tasksCommand": "claude",
      "tasksSystemPrompt": "@.prompts/task-system.md",
      "terminalColors": {
        "po": "terminal.ansiMagenta",
        "qa": "terminal.ansiGreen",
        "fixes": "terminal.ansiRed",
        "tasks": "terminal.ansiCyan"
      },
      "terminalIcons": {
        "po": "star-full",
        "qa": "beaker",
        "fixes": "wrench",
        "tasks": "checklist"
      }
    }
  ]
}

Release and Push Workflow

Use the maintained checklist in docs/github-release-checklist.md for versioned VSIX releases. For the broader day-to-day + release lifecycle, see docs/development-and-release-workflow.md. The release checklist also includes VS Code Marketplace publish steps (vsce) after GitHub release publication.

Branching model: feature/* → dev → main.
main is the release branch (you do not need a separate release/* branch for the current workflow).
Day-to-day work: keep a -dev version in package.json, update CHANGELOG.md under Unreleased, and open PRs into dev.
Release promotion: merge dev into main, run the release checklist, then publish tag + GitHub release from main.
After each release on main: bump to next -dev version and continue work via feature/* branches back into dev.
Tag safety: release tag pushes run .github/workflows/release-tag-version-guard.yml to enforce tag/version consistency.

Features

One-Command Setup: Creates a full set of phase‑specific terminals instantly via the Command Palette or keyboard shortcut (Ctrl+Alt+T / Cmd+Option+T).
Profile-Based Setup: Run "Create Phase Terminals from Profile" to skip prompts and launch a saved terminal layout.
Flexible Task Generation: Supports generating a simple number of tasks (e.g., 5 tasks) or a specific task number range (e.g., Tasks 15 through 20).
Logical Grouping: Groups terminals into three logical categories within the terminal panel using VS Code's split-terminal feature:
- Leadership: PO, QA/SDET, Tech Lead Review
- Fixes: Fixes, Fixes from QA/SDET Report, Fixes from Tech Lead Review
- Tasks: First Task, followed by the generated range of subsequent tasks.
Grouping Mode Switch: Toggle between grouped split-pane mode and separate top-level terminal tabs.
Auto-Initialization: Automatically sends the appropriate startup commands to each terminal upon creation.
Visual Navigation: Set per-role terminal colors and codicon icons to identify tabs at a glance.
System Prompt Injection: Optionally appends role-specific --system prompts to leadership, QA, fixes, and task commands.
Pre/Post Command Hooks: Run setup and teardown commands before/after each terminal command.
Clean Up Command: Close all orchestrator-created terminals with one command.
Status Bar Dashboard: A clickable status bar item opens quick actions for create, create from profile, cleanup, and broadcast.
Editor-Area Terminals: Optionally open terminals in the editor area tabs instead of the bottom terminal panel.
Context-Aware Startup: Optionally inject active-file context as --file and --prompt at terminal startup.
Phase Handoff Snapshot: Generate a markdown artifact with active terminal layout, inferred phase/task range, effective settings, and optional git context.
Startup Restore Prompt: Ask whether to restore the last saved phase layout on VS Code startup.
Startup Health Checks: Validate command executables and track per-terminal ready/error startup status.
Task Source Integration: Generate Task terminals directly from GitHub issue search queries or Jira JQL.
Phase Transition Workflow: One command to snapshot current phase, close terminals, and open Phase N+1.
Profile Import/Export: Share profile packs as JSON files across teammates and projects.
Custom Terminal Names: Rename every terminal label (including templates for phase/task) to match any AI agent workflow.

Terminal layout screenshot

Terminal tree screenshot

Requirements

Terminal Orchestrator has no external dependencies. It runs entirely on the built‑in VS Code terminal API.

Note: If you use the default gemini or claude startup commands, ensure those CLIs are installed and accessible in your system's PATH.

Extension Settings

This extension contributes the following settings, which can be modified in your VS Code User Settings (Cmd+, or Ctrl+, -> Search "Phase Terminals"):

phaseTerminals.leadershipCommand: The default CLI command to send to the Leadership (PO) terminal. (Default: gemini)
phaseTerminals.qaCommand: Default command for QA / SDET terminals. (Default: claude)
phaseTerminals.fixesCommand: Default command for Fixes terminals. (Default: claude)
phaseTerminals.tasksCommand: Default command for Task terminals. (Default: claude)
phaseTerminals.leadershipSystemPrompt, phaseTerminals.qaSystemPrompt, phaseTerminals.fixesSystemPrompt, phaseTerminals.tasksSystemPrompt: Optional role-specific system prompts. Supports raw text or file paths (@relative/or/absolute/path, file://..., workspace-relative paths).
phaseTerminals.preCommand: Optional command sent before each terminal command.
phaseTerminals.postCommand: Optional command sent after each terminal command.
phaseTerminals.settingsWriteTarget: Where dashboard/config command updates are saved: user (default, carries across projects) or workspace.
phaseTerminals.autoRestoreLastSessionOnStartup: If true, shows a restore prompt on startup when no orchestrator terminals are open. (Default: false)
phaseTerminals.enableStartupHealthChecks: If true (default), checks role startup commands and records ready/error terminal startup status.
phaseTerminals.autoActivateVenv: If true, activate virtual environment before running pre/main/post commands.
phaseTerminals.venvPath: Virtual environment folder path (workspace-relative). Default: .venv.
phaseTerminals.venvActivationCommand: Optional explicit activation command override for your shell.
phaseTerminals.venvActivationDelayMs: Wait time after activation before running commands. Default: 600.
phaseTerminals.showVenvSkipMessage: If true, print a short status line when activation is enabled but skipped.
phaseTerminals.openInEditorArea: Legacy global toggle. Prefer phaseTerminals.editorAreaMode + phaseTerminals.editorAreaTargets.
phaseTerminals.editorAreaMode: all, none, or custom for editor-tab placement.
phaseTerminals.editorAreaTargets: When mode is custom, choose roles to open in editor tabs (po, qa, techLead, fixes, fixesQa, fixesTechLead, tasks).
phaseTerminals.broadcastScope: Broadcast target scope: all (default) or tasks.
phaseTerminals.taskDisplayOrder: Task terminal visual order: asc (default, e.g., 33→41) or desc (e.g., 41→33).
phaseTerminals.terminalGroupingMode: Panel layout mode: grouped (default) or separate.
phaseTerminals.includeActiveFileContext: Appends active file context (--file and --prompt) to startup commands.
phaseTerminals.contextPromptTemplate: Template used for context prompt. Supports ${phase} and ${filePath}.
phaseTerminals.snapshotOutputDirectory: Output folder (workspace-relative) for handoff snapshots. Default: phase-handoff.
phaseTerminals.snapshotIncludeGitContext: Include git branch + changed files in handoff snapshot. Default: true.
phaseTerminals.taskSource: GitHub/Jira settings used by Create Tasks from Issue Source.
phaseTerminals.dependencyWaits: Optional role-to-role startup dependency regex rules.
phaseTerminals.envInjection: Per-role environment variable injection plus optional .env key mapping.
phaseTerminals.outputCapture: Capture/export settings for transcript bundles and secret redaction.
phaseTerminals.terminalNames: Override all terminal labels. Supports ${phase} and ${task} in template fields.
phaseTerminals.terminalColors: Optional role->ThemeColor map (for example terminal.ansiRed).
phaseTerminals.terminalIcons: Optional role->Codicon map (for example wrench, star-full, beaker).
phaseTerminals.profiles: Optional list of saved workspace profiles used by Create Phase Terminals from Profile.

Custom Terminal Names

Use phaseTerminals.terminalNames to make labels match your own agents/roles:

"phaseTerminals.terminalNames": {
  "poNameTemplate": "Planner • Phase ${phase}",
  "qaName": "Verifier",
  "techLeadName": "Architect Review",
  "fixesName": "Patch Queue",
  "fixesQaName": "Patch from Verifier",
  "fixesTechLeadName": "Patch from Architect",
  "taskNameTemplate": "Agent Task ${task}"
}

You can also use these same fields inside each profile object for profile-specific naming.

System Prompt Sources

Each *SystemPrompt setting accepts either:

Raw text (used directly as the --system value)
Prompt file path (the file contents are loaded, then passed as the --system value)

Examples:

"phaseTerminals.qaSystemPrompt": "You are a strict QA reviewer. Focus on reproducibility."

"phaseTerminals.qaSystemPrompt": "@.prompts/qa-system.md"

"phaseTerminals.qaSystemPrompt": "C:/Users/you/prompts/qa.md"

"phaseTerminals.qaSystemPrompt": "file:///C:/Users/you/prompts/qa.md"

Notes:

@path is the clearest way to indicate "treat this as a file path".
Relative paths resolve from the workspace root.
If an @path file can't be read, the extension skips --system for that role and shows a warning.

Virtual Environment Activation

If you rely on a Python virtual environment, enable automatic activation before your agent commands run:

"phaseTerminals.autoActivateVenv": true,
"phaseTerminals.venvPath": ".venv",
"phaseTerminals.venvActivationDelayMs": 600,
"phaseTerminals.showVenvSkipMessage": true

If your shell needs a custom activation command, set:

"phaseTerminals.venvActivationCommand": "source .venv/bin/activate"

For PowerShell, for example:

"phaseTerminals.venvActivationCommand": ". .\\.venv\\Scripts\\Activate.ps1"

Broadcast Scope

phaseTerminals.broadcastScope controls which terminals receive the Broadcast Command to Phase Terminals action:

all (default): broadcasts to all orchestrator terminals (PO, QA, Tech Lead, Fixes, Tasks)
tasks: broadcasts only to terminals named Task - N

Examples:

"phaseTerminals.broadcastScope": "all"

"phaseTerminals.broadcastScope": "tasks"

Editor Area Placement

Control where terminals open (editor tabs vs terminal panel):

All in editor tabs:

"phaseTerminals.editorAreaMode": "all"

None in editor tabs (all in terminal panel):

"phaseTerminals.editorAreaMode": "none"

Any combination of roles:

"phaseTerminals.editorAreaMode": "custom",
"phaseTerminals.editorAreaTargets": ["po", "qa", "tasks"]

Example above opens PO, QA, and Task terminals in editor tabs while the rest open in terminal panel.

Task Display Order

Controls how Task terminals appear in the terminal tree:

asc: Task - 33, Task - 34, ... Task - 41
desc: Task - 41, Task - 40, ... Task - 33

Examples:

"phaseTerminals.taskDisplayOrder": "asc"

"phaseTerminals.taskDisplayOrder": "desc"

Terminal Grouping Mode

Controls whether panel terminals are created as split groups or separate tabs:

grouped (default): leadership/fixes/tasks open in grouped split stacks
separate: every terminal opens as its own top-level terminal tab

Examples:

"phaseTerminals.terminalGroupingMode": "grouped"

"phaseTerminals.terminalGroupingMode": "separate"

Startup Restore Prompt

Enable startup restore prompting for the most recent created layout:

"phaseTerminals.autoRestoreLastSessionOnStartup": false

If you prefer not to decide at startup, set this to false and use Restore Last Phase Session when you are ready.

Startup Health Checks

Checks each role startup command executable before launch and marks terminals as ready/error:

"phaseTerminals.enableStartupHealthChecks": true

Use Show Startup Health Report to inspect per-terminal status.

Task Source Integration (GitHub/Jira)

Configure issue query defaults, then run Create Tasks from Issue Source:

"phaseTerminals.taskSource": {
  "defaultSource": "github",
  "githubRepo": "owner/repo",
  "githubQuery": "is:open is:issue label:task sort:updated-desc",
  "githubMaxResults": 10,
  "jiraBaseUrl": "https://your-domain.atlassian.net",
  "jiraEmail": "you@company.com",
  "jiraApiToken": "<token>",
  "jiraJql": "assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC",
  "jiraMaxResults": 10
}

Optional auth fields:

githubToken for private repos/higher rate limits.
jiraEmail + jiraApiToken for authenticated Jira Cloud queries.

Dependency Waits

Use dependency rules to delay startup of one role until another role prints a matching regex:

"phaseTerminals.dependencyWaits": [
  {
    "sourceRole": "po",
    "targetRole": "qa",
    "pattern": "READY_FOR_QA",
    "flags": "i"
  }
]

Example above waits to start QA terminal commands until PO terminal output contains READY_FOR_QA.

Per-Role Env Injection

Inject role-specific environment variables and optionally map keys from .env:

"phaseTerminals.envInjection": {
  "enabled": true,
  "envFilePath": ".env",
  "roleEnv": {
    "po": { "AGENT_MODE": "planner" },
    "tasks": { "AGENT_MODE": "executor" }
  },
  "roleEnvFromDotEnv": {
    "qa": ["QA_API_BASE_URL", "QA_API_TOKEN"],
    "tasks": ["OPENAI_API_KEY"]
  }
}

Output Capture Bundle

Capture terminal output and export a redacted bundle with one log file per terminal:

"phaseTerminals.outputCapture": {
  "enabled": true,
  "outputDirectory": "phase-output",
  "redactSecrets": true,
  "redactionPatterns": [
    "ghp_[A-Za-z0-9]{20,}",
    "AIza[0-9A-Za-z\\-_]{20,}",
    "(?i)api[_-]?key\\s*[=:]\\s*[^\\s\"']+"
  ]
}

Run Export Output Capture Bundle to create a timestamped folder with logs and an index file.

Profile Example

"phaseTerminals.profiles": [
  {
    "name": "Backend Sprint",
    "phase": 3,
    "startTask": 1,
    "endTask": 6,
    "includeLeadership": true,
    "includeQa": true,
    "includeTechLeadReview": true,
    "includeFixes": true,
    "includeFixesFromQa": true,
    "includeFixesFromTechLead": true,
    "includeTasks": true,
    "tasksCommand": "claude",
    "tasksSystemPrompt": "You are a focused task executor.",
    "preCommand": "cd ./src",
    "terminalColors": {
      "po": "terminal.ansiMagenta",
      "qa": "terminal.ansiGreen",
      "fixes": "terminal.ansiRed",
      "tasks": "terminal.ansiCyan"
    },
    "terminalIcons": {
      "po": "star-full",
      "qa": "beaker",
      "fixes": "wrench",
      "tasks": "checklist"
    }
  }
]

Commands

Create Phase Terminals: Interactive setup for phase + task range.
Run First-Run Setup Wizard: Guided setup for default commands, restore/health preferences, and initial task source.
Create Phase Terminals from Profile: Launch terminals from a saved phaseTerminals.profiles entry.
Create Tasks from Issue Source: Query GitHub or Jira and open one task terminal per returned issue.
Restore Last Phase Session: Recreate the last saved phase layout manually.
Delete Saved Phase Session: Remove the saved phase layout used for startup/manual restore.
Show Startup Health Report: View ready/error startup command status per currently open orchestrator terminal.
Show Dependency Wait Debug: Inspect active dependency waits and configured role-to-role regex rules.
Export Output Capture Bundle: Exports transcript bundle with optional secret redaction.
Phase Transition: Snapshot, Close, Open Next: Creates handoff snapshot, cleans up terminals, and opens phase N+1.
Export Phase Profiles: Save current phaseTerminals.profiles to a JSON file.
Import Phase Profiles: Load profile JSON and merge/replace existing profiles.
Clean Up Phase Terminals: Dispose all terminals created by this extension naming pattern.
Open Terminal Orchestrator Dashboard: Opens the same quick-action menu used by the status bar button.
Configure Editor Area Mode: Opens a picker to set phaseTerminals.editorAreaMode (and editorAreaTargets in custom mode).
Toggle Editor Area Mode (Cycle): Cycles placement mode all → none → custom → all.
Toggle Terminal Grouping Mode: Switches panel layout between grouped split panes and separate tabs.
Broadcast Command to Phase Terminals: Sends one command to all currently open orchestrator terminals.
Create Phase Handoff Snapshot: Writes a markdown snapshot under phase-handoff/ (or your configured output directory).

Status Bar Dashboard Actions

When you click the status bar item ($(terminal) Orchestrator), you get:

Create Terminals: Runs interactive phase + task setup.
Create from Profile: Launches saved phaseTerminals.profiles configurations.
Run First-Run Setup Wizard: Walks through initial command and task-source setup.
Create Tasks from Issue Source: Creates task terminals from GitHub/Jira query results.
Restore Last Session: Restores the most recent saved phase layout.
Delete Saved Session: Deletes the most recent saved phase layout snapshot.
Phase Transition (Close + Snapshot + Next): Runs the full handoff-to-next-phase workflow.
Toggle Editor Area: One-click cycle through all, none, and custom editor placement.
Toggle Grouping Mode: One-click toggle between grouped and separate terminal panel layout.
Set Editor Area Mode: Changes all / none / custom on the fly (and selects targets for custom mode).
Create Phase Handoff Snapshot: Captures current orchestrator state into a shareable markdown file.
Export Output Capture Bundle: Saves captured terminal transcripts (optionally redacted).
Show Startup Health Report: Displays ready/error command launch status per terminal.
Show Dependency Wait Debug: Shows which terminals are blocked waiting for regex matches.
Export Profiles / Import Profiles: Share profile sets as JSON files.
Broadcast Command: Prompts for one command and sends it to terminals defined by phaseTerminals.broadcastScope.
Clean Up Terminals: Closes all orchestrator terminal tabs quickly.

Tip: If you mean "copy/paste to multiple terminals", use Broadcast Command from the dashboard.

Testing

Run extension tests:

npm test

Run coverage:

npm run test:coverage

Run coverage with a hard gate for src/extension.ts statements, branches, and functions coverage (project script currently enforces 80% for all three metrics):

npm run test:coverage:gate

Run the stretch target check (currently 85%, non-blocking in CI):

npm run test:coverage:stretch

To tighten over time, adjust the threshold and metrics arguments in test:coverage:gate (or run node scripts/check-extension-coverage.mjs ... <new-threshold> <metrics> directly).

CI runs this same gate automatically on pull requests and pushes to main via .github/workflows/coverage-gate.yml. The CI workflow also runs a non-blocking 85% stretch check so we can keep ratcheting coverage up as features are added.

If coverage appears inconsistent across views, treat npm run test:coverage:gate as the source of truth (it regenerates coverage and enforces the current required threshold).

Product packaging guidance (Free / Pro / Team) is documented in docs/monetization-strategy.md.

Known Issues

Very large task ranges (hundreds of terminals at once) may cause VS Code to briefly slow down while allocating memory for the terminal instances.

Release Notes

Unreleased

Added role-based terminal colors and codicon icons.
Added role-based system prompt injection with prompt-file support.
Added global pre/post command hooks.
Added "Create Phase Terminals from Profile" command.
Added "Clean Up Phase Terminals" command.
Added status bar dashboard with quick actions.
Added terminal editor-area placement option.
Added active-file context-aware command initialization.
Added command broadcast to all phase terminals.
Added "Create Phase Handoff Snapshot" command with optional git context.
Added terminal grouping mode switch (grouped/separate) with dashboard toggle.
Added auto-restore of the last saved session on startup.
Added startup command health checks with per-terminal ready/error report.
Added GitHub/Jira task-source terminal generation command.
Added phase transition workflow command (snapshot + cleanup + next phase).
Added profile import/export commands for JSON sharing.
Added dependency waits to gate role startup by source-terminal output regex.
Added per-role environment variable injection with .env key mapping.
Added output capture bundle export with optional secret redaction.
Added first-run setup wizard command.
Added dependency wait debug command for inspecting active wait chains.
Added phaseTerminals.profiles schema and examples.

1.0.0

Initial release of Terminal Orchestrator.
Added automated, grouped terminal creation for standard dev phases.
Added support for task count or start/end ranges.
Added dynamic user settings for custom startup commands.
Added custom keyboard shortcut (Ctrl+Alt+T / Cmd+Option+T).

Terminal Orchestrator

Curtis Criff

Terminal Orchestrator

Built for Agentic Workflows

Why teams install it

Marketplace Copy

Quick Setup

Quick Setup (Profile-Based)

Release and Push Workflow

Features

Requirements

Extension Settings

Custom Terminal Names

System Prompt Sources

Virtual Environment Activation

Broadcast Scope

Editor Area Placement

Task Display Order

Terminal Grouping Mode

Startup Restore Prompt

Startup Health Checks

Task Source Integration (GitHub/Jira)

Dependency Waits

Per-Role Env Injection

Output Capture Bundle

Profile Example

Commands

Status Bar Dashboard Actions

Testing

Known Issues

Release Notes

Unreleased

1.0.0