Build for Vanish.
One object, the whole app.

api.events.on('themeChanged', (themeName: string) => {
  api.log(`Theme was just changed to ${themeName}!`);
});

interface LogEntry {
  id: number;
  level: 'log' | 'info' | 'warn' | 'error' | 'success' | 'system';
  message: string;
  timestamp: number; // Unix epoch milliseconds
}

const recentErrors = api.log
  .getRecent(100)
  .filter((entry) => entry.level === 'error');

const unsubscribe = api.log.subscribe((entry) => {
  if (entry.level === 'warn' || entry.level === 'error') {
    // react to errors or warnings
  }
});

await api.data.editData('index.json', (current) => {
  const base = current && typeof current !== 'string'
    ? current
    : { version: 1, sessions: [] };

  return {
    ...base,
    sessions: [...base.sessions, { id: 'chat-123', title: 'New Session' }],
  };
});

api.data.publish('vanish:shared:hud-weather', {
  summary: '72F Clear',
  locationLabel: 'Brooklyn, NY',
  updatedAt: Date.now(),
});

const unsubscribe = api.data.subscribe('vanish:shared:hud-weather', (entries) => {
  const latest = entries.at(-1);
  api.log(`Current weather: ${latest?.value.summary ?? 'none'}`);
});

export default function (api: VanishAPI) {
  api.events.on('themeChanged', () => {
    let opacity = 1.0;
    const cleanup = api.animator.onFrame(() => {
      opacity -= 0.1;
      const { width, height } = api.renderer.getSize();
      for (let y = 0; y < height; y++) {
        for (let x = 0; x < width; x++) {
          api.renderer.setCell(x, y, { char: ' ', bg: '#ffffff' });
        }
      }
      if (opacity <= 0) {
        cleanup();
        api.renderer.forceFullRender();
      }
    });
  });
}

const progress = api.easing.easeOutQuart(elapsedTime / totalDuration);

export default function (api: VanishAPI) {
  api.startup.setArtwork([
    ' __  __       _     __  __ ',
    '|  \/  |     | |   |  \/  |',
    '| \  / | ___ | |__ | \  / |',
    '| |\/| |/ _ \| \'_ \| |\/| |',
    '| |  | | (_) | | | | |  | |',
    '|_|  |_|\___/|_| |_|_|  |_|',
  ]);
}

interface NotificationOptions {
  title?: string;
  message: string;            // required
  duration?: number;          // ms; 0 = manual dismiss
  position?: NotificationPosition;
  animation?: string | NotificationAnimation;
  theme?: string | NotificationTheme;
  width?: number;
  height?: number;
  icon?: string;
  tone?: 'info' | 'success' | 'warning' | 'error';
  onDismiss?: () => void;
  dismissible?: boolean;      // default: true
  actions?: NotificationAction[];
}

const handle = api.notifications.send({
  title: 'Download in Progress',
  message: 'Downloading update... 45%',
  tone: 'info',
  duration: 0, // never auto-dismiss
});

handle.update({ message: 'Downloading update... 78%' });
handle.dismiss();

api.notifications.send({
  title: 'Search Extension',
  message: 'Agent permission is required for web search tools.',
  tone: 'warning',
  duration: 0,
  actions: [
    {
      id: 'permission-requests',
      label: 'Permission requests',
      shortcut: "Ctrl+'",
      onPress: () => api.events.emit('permissionRequests:open'),
    },
  ],
});

interface ChatSessionSummary {
  id: string;
  title: string;
  createdAt: string;
  updatedAt: string;
  messageCount: number;
  isStreaming: boolean;
  providerName: string | null;
  providerDisplayName: string | null;
  model: string | null;
  preview: string;
}

const session = api.chat.createSession({ title: 'Refactor Notes', activate: true });
const result = api.chat.sendMessage('Summarize the tradeoffs of this refactor.', {
  sessionId: session.id,
});

if (result.accepted) {
  await api.views.activate('chat');
}

const off = api.chat.registerMessageRenderer({
  id: 'demo-bullets',
  priority: 10,
  filter: (m) => m.role === 'assistant',
  render: (m, ctx) => {
    const lines = ctx.defaultRender();
    if (lines.length === 0) return null;
    lines[0] = { ...lines[0], text: '• ' + lines[0].text };
    return lines;
  },
});

interface Message {
  role: 'system' | 'user' | 'assistant';
  content: string;
}

interface CompletionOptions {
  temperature?: number;
  maxTokens?: number;
  topP?: number;
  stop?: string[];
}

interface CompletionResult {
  content: string;
  finishReason?: 'stop' | 'length' | 'content_filter';
  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };
}

try {
  const result = await api.llm.response.heavy([
    { role: 'system', content: 'You are a code reviewer.' },
    { role: 'user', content: 'Review: function add(a,b){return a+b}' },
  ], { temperature: 0.3, maxTokens: 1000 });
  api.log(`Heavy response: ${result.content}`);
} catch (error) {
  // notification already shown to the user
  api.log.error(`Heavy model not available: ${error.message}`);
}

let full = '';
for await (const chunk of api.llm.stream.chat([
  { role: 'user', content: 'Tell me a short joke' },
])) {
  if (chunk.content) full += chunk.content;
  if (chunk.done) api.log(`Stream complete: ${full}`);
}

interface ToolDefinition {
  name: string;          // globally unique, kebab-case
  description: string;   // shown to the LLM
  parameters: {
    type: 'object';
    properties: Record<string, ToolParameter>;
    required?: string[];
  };
  annotations?: ToolAnnotations; // readOnlyHint, destructiveHint, …
  timeoutMs?: number;
  handler: (
    args: Record<string, unknown>,
    context?: ToolHandlerContext, // { signal, onProgress }
  ) => ToolResult | Promise<ToolResult>;
}

const unregister = api.agent.registerTool({
  name: 'fetch-url',
  description: 'Fetches the plain-text content of a URL.',
  parameters: {
    type: 'object',
    properties: {
      url: { type: 'string', description: 'Full URL including https://' },
    },
    required: ['url'],
  },
  annotations: { readOnlyHint: true, idempotentHint: true },
  handler: async (args) => {
    const res = await fetch(args.url as string);
    if (!res.ok) return { content: `HTTP ${res.status}`, isError: true };
    return { content: (await res.text()).slice(0, 4000) };
  },
});

api.agent.setPromptProfile({
  guardrails: [
    'Never claim a file was changed unless a tool result in this run confirms it.',
    'If a tool fails, explain the blocker plainly instead of pretending it succeeded.',
  ],
  finalAnswerGuidance: ['State what you verified before giving the conclusion.'],
});

interface SkillRegistration {
  id: string;            // kebab-case, globally unique
  name: string;
  description: string;   // doubles as the judge's rubric anchor
  segmentId: string;     // harness segment this body backs
  position: 'prepend' | 'append';
  defaultBody: string;   // persisted as version 1
}

const dispose = await api.evolve.registerSkill({
  id: 'final-answer-style',
  name: 'Final answer style',
  description: 'Keep final answers concise and action-oriented.',
  segmentId: 'vanish-agent-final-answer-style',
  position: 'append',
  defaultBody: [
    'Style guidance for final answers:',
    '- Lead with the answer in the first sentence.',
    '- Avoid restating the question.',
  ].join('\n'),
});

const current = api.getTheme();
api.log(`Current background: ${current.colors.background}`);

if (api.listThemes().includes('my-custom-theme')) {
  api.setTheme('my-custom-theme');
}

import { BaseModal } from 'vanish-tui';

class AlertModal extends BaseModal<boolean> {
  // ... modal implementation ...
}

const alert = new AlertModal('Warning', 'Are you sure?');
api.modal.open(alert, (result) => {
  api.log(result ? 'User confirmed.' : 'User cancelled.');
});

const cleanup = api.settings.registerSections([{
  id: 'my-extension',
  title: 'My Extension Config',
  elements: [{
    id: 'enable-feature-x',
    type: 'boolean',
    label: 'Enable Feature X',
    value: 'Enabled',
    editable: true,
    sectionId: 'my-extension',
    persistence: {
      namespace: 'myExtension',
      key: 'enabled',
      fromStored: (s) => (s === true ? 'Enabled' : 'Disabled'),
      toStored: (v) => v === 'Enabled',
    },
    onActivate: async () => ({ message: 'Feature X toggled.', tone: 'success' }),
  }],
}]);

interface CommandContext {
  sourceViewId: string | null;
  query: string;
  mode: '>' | '#' | '@' | '?' | ':' | '/' | null;
  pickFrom: <T>(items: PickableItem<T>[], prompt: string) => Promise<T | null>;
  promptFor: (options: PromptOptions) => Promise<string | null>;
  confirm: (options: { message: string; confirmWord?: string }) => Promise<boolean>;
  runCommand: (id: string, args?: Record<string, unknown>) => Promise<CommandResult>;
  namespace: string;
}

api.commands.registerCommand({
  id: 'my-ext.pick-rule',
  label: 'Disable rule…',
  category: 'extensions',
  handler: async (ctx) => {
    const rule = await ctx.pickFrom(
      [
        { id: 'no-console', label: 'no-console', value: 'no-console' },
        { id: 'no-debugger', label: 'no-debugger', value: 'no-debugger' },
      ],
      'Disable which rule?',
    );
    if (!rule) return { message: 'Cancelled.', tone: 'info' };
    return { message: `Disabled ${rule}.`, tone: 'success' };
  },
});

// toggle a view
const chatEnabled = api.views.isEnabled('chat');
api.views.setEnabled('chat', !chatEnabled);

// reverse the sidebar order
api.views.setOrder([...api.views.getOrder()].reverse());

api.events.on('viewEnabledChanged', ({ viewId, enabled }) => {
  api.log(`View ${viewId} was ${enabled ? 'enabled' : 'disabled'}`);
});

interface KeyPress {
  name: string;
  ctrl: boolean;
  meta: boolean;
  alt: boolean;
  shift: boolean;
  sequence: string; // raw terminal bytes
  text?: string;    // printable character, when reported
}

api.input.registerHandler((key, context) => {
  if (context.currentViewId !== 'chat' || context.modalOpen) return false;
  if (key.ctrl && key.name === 'h') {
    api.log('Open chat history modal');
    return true;
  }
  return false;
});

api.events.on('mouse:scroll', (e) => {
  if (e.scrollDelta < 0) api.log('Scrolled up');
});

const location = await api.location.get();
if (location) {
  api.log(`Detected: ${location.city}, ${location.region}`);
} else {
  api.log('Location access denied or unavailable.');
}

const summary = api.location.getSummary();
if (summary) api.renderer.drawText(0, 0, summary);

const tokenKey = 'github-personal-access-token';
if (!(await api.secrets.has(tokenKey))) {
  await api.secrets.set(tokenKey, 'ghp_example123');
  api.log('Token securely stored!');
} else {
  const token = await api.secrets.get(tokenKey);
  api.log('Retrieved stored token securely.');
}

vanish audit secrets                    # last 100 entries, all extensions
vanish audit secrets -x my_extension    # filter to one extension
vanish audit secrets --json -n 500      # JSON output, last 500 entries

const { denied } = api.permissions.check(['agent']);
if (denied.includes('agent')) {
  api.permissions.request(['agent'], {
    title: 'Search Extension: Agent permission required',
    message: 'Needs agent access to expose web search tools.',
    duration: 0,
  });
}

{
  "name": "notify_request_perms",
  "capabilities": ["permissionManager"]
}

api.outguard.report({
  kind: 'custom',
  target: 'vendor-sdk:lookup',
  metadata: { lookupType: 'symbol', symbol: 'MSFT' },
});

const recent = await api.outguard.getRecent(10);
api.log(`Outguard has ${recent.length} recent signal(s).`);

{
  "name": "vanish_hud_plus",
  "displayName": "Vanish HUD Plus",
  "version": "1.0.0",
  "dependencies": ["vanish_hud"],
  "main": "main.ts"
}

async function safeDisable(api: VanishAPI, name: string) {
  const ext = await api.extensions.getInstalled(name);
  if (!ext) return;
  if (ext.dependents.length > 0) {
    api.notifications.send({
      title: 'Dependents Warning',
      message: `Disabling "${ext.displayName}" affects: ${ext.dependents.join(', ')}`,
      tone: 'warning',
      duration: 5000,
    });
  }
  await api.extensions.setEnabled(name, false);
}