Developers Terminal command defaults

Terminal command defaults

A terminal command default adds flags in front of the user's arguments when a command runs in a Terminay terminal. The bundled agents extension uses one to run codex with --no-daemon, so Terminay can tell which terminal each Codex runs in. Added in API 3.4.

Use sparingly

Terminay observes agents and never changes how they run. Each command default is an exception to that rule, and needs the repository owner's approval in an ADR before it ships in a bundled extension. Prefer a session source whenever observing is enough.

Manifest contribution

JSON

"api": "^3.4.0",
"permissions": ["terminal-command-defaults"],
"contributes": {
  "terminalCommandDefaults": [{
    "id": "com.example.agent/defaults",
    "command": "example",
    "harness": { "source": "com.example.agent/sessions", "harness": "example-agent" }
  }]
}

Field	Meaning
`id`	Required. Namespaced by the extension ID.
`command`	Required and fixed by the manifest: one plain word of at most 64 characters that is not a builtin or reserved word of zsh, bash, fish, or PowerShell.
`harness`	Optional `{ source, harness }`. While that harness is switched off the default does not apply and is not called.

 Requires the terminal-command-defaults permission. A manifest may declare up to 8.

  Runtime contract
   TypeScript  
 context.subscriptions.add(
  context.terminals.registerCommandDefault('com.example.agent/defaults', {
    async resolve(signal) {
      const help = await exampleHelp(signal);
      if (help === null) return { applies: false, reason: 'not_installed' };
      return help.includes('--no-daemon')
        ? { applies: true, args: ['--no-daemon'] }
        : { applies: false, reason: 'unsupported', detail: 'This version has no --no-daemon flag.' };
    },
  }),
);
 
   resolve(signal) returns { applies: true, args }, up to 8 arguments that each
      start with -, or { applies: false, reason, detail? } with reason not_installed, unsupported, or unavailable.
 
  What Terminay does
 
Terminay's shell integration for zsh, bash, fish, and PowerShell turns each default into a shell
      function in new terminals, so typing example run runs example --no-daemon run.
      It also appends the flags when a terminal launcher
starts that command. The extension supplies data only; Terminay writes every line of shell code and
      all quoting.
  A user's own alias or function of the same name wins.
 Two extensions claiming one command cancel each other out.
 Shells without integration, and profiles with arguments Terminay does not recognise, start unchanged.
 
 
Test with registeredCommandDefaultIds() and resolveCommandDefault(id) on the
agent extension harness.