profiles

ctx.agents.profiles

Read the user's Agent Profiles and start one — optionally with an opening prompt. A profile is the user's own named recipe for launching a coding agent (a label, a command line like claude-work, and an optional config directory for running a second account), defined on Settings → Agents → Profiles.

ctx.agents.profiles: AgentProfilesService

A profile is a way to start a terminal, not a way to talk to an agent. What comes up is a PTY running a real agent CLI, exactly as if the user had typed the command themselves — there is no agent-agnostic messaging layer here, and there is not meant to be one. Talking to an agent that is already running is out of scope.

There is deliberately no pick() — build one from list() and ctx.ui.showMenu — and no get(), which is list().find().

Example

Let the user pick a profile and start it on a task

function startOn(ctx: ExtensionContext, profileId: string): void {
  const result = ctx.agents.profiles.launch({
    profileId,
    prompt: "Fix the failing test in src/foo.test.ts",
  });
  if (result.ok) {
    ctx.ui.notify("info", `Started in terminal ${result.terminalId}.`);
  } else {
    ctx.ui.notify("warn", `Couldn't start it: ${result.refusal}`);
  }
}

export const extension: Extension = {
  id: "my.start-task",
  activate(ctx) {
    ctx.subscriptions.push(
      ctx.registerCommand({
        id: "my.startTask",
        label: "My: Start a task",
        run: () => {
          const profiles = ctx.agents.profiles.list();
          if (profiles.length === 0) {
            ctx.ui.notify(
              "warn",
              "No agent profiles yet — add one in Settings → Agents.",
            );
            return;
          }
          void ctx.ui.showMenu({
            items: profiles.map((p) => ({
              label: p.isDefault ? `${p.label} (default)` : p.label,
              run: () => startOn(ctx, p.id),
            })),
          });
        },
      }),
    );
  },
};