---

What is this?

A TypeScript SDK for building VS Code extensions that extend Antigravity IDE. It gives you programmatic access to the agent's conversations, preferences, step control, real-time activity monitoring, and a declarative API for integrating custom UI directly into the Agent View — all through Antigravity's own extension protocols.

---

Quick Start

npm install antigravity-sdk
Copy

import { AntigravitySDK } from 'antigravity-sdk';

export async function activate(context: vscode.ExtensionContext) {
  const sdk = new AntigravitySDK(context);
  await sdk.initialize();

  // List conversations with real titles
  const sessions = await sdk.cascade.getSessions();
  console.log(`${sessions.length} conversations`);

  // Read all 16 agent preferences
  const prefs = await sdk.cascade.getPreferences();
  console.log('Terminal policy:', prefs.terminalExecutionPolicy);

  // Monitor agent activity in real time
  sdk.monitor.onStepCountChanged((e) => {
    console.log(`${e.title}: +${e.delta} steps`);
  });
  sdk.monitor.onActiveSessionChanged((e) => {
    console.log(`Switched to: ${e.title}`);
  });
  sdk.monitor.start();

  // Accept/reject agent steps programmatically
  await sdk.cascade.acceptStep();
  await sdk.cascade.acceptTerminalCommand();

  context.subscriptions.push(sdk);
}
Copy

---

Features

Agent View UI Integration

The SDK provides 9 integration points in the Agent View panel — add buttons, metadata, badges, menu items, and interactive elements with a fluent, declarative API. Everything is theme-aware and survives Antigravity updates via auto-repair.

import { IntegrationManager, IntegrationPoint } from 'antigravity-sdk';

const ui = new IntegrationManager();

// Fluent API — chain calls
ui.addTopBarButton('stats', '📊', 'Show Stats', {
    title: 'Session Stats',
    rows: [{ key: 'Steps:', value: '42' }],
  })
  .addInputButton('tokens', '🔢', 'Token Counter')
  .addTurnMetadata('meta', ['turnNumber', 'userCharCount', 'aiCharCount', 'codeBlocks'])
  .addUserBadges('badges', 'charCount')
  .addBotAction('inspect', '🔍', 'Inspect Response')
  .addDropdownItem('export', 'Export Chat', '📋')
  .addTitleInteraction('title', 'dblclick', 'Double-click to bookmark');

await ui.install();
ui.enableAutoRepair(); // Survives Antigravity updates
Copy

Integration Point	Location	Use Cases
TOP_BAR	Header icon bar	Session overview, navigation
TOP_RIGHT	Before close button	Status indicators, quick toggle
INPUT_AREA	Next to send button	Token counter, prompt templates
BOTTOM_ICONS	Bottom icon row	Mode switches, quick actions
TURN_METADATA	Inside each turn	Character count, code block stats, turn numbers
USER_BADGE	User message bubble	Message length indicator
BOT_ACTION	Next to Good/Bad	Response analysis, copy actions
DROPDOWN_MENU	3-dot overflow menu	Export, settings, debug tools
CHAT_TITLE	Conversation title	Rename, bookmark on interaction

Conversation Management

Full control over Cascade conversations — list, create, switch, send messages, and manage agent steps.

// List sessions with titles, step counts, timestamps
const sessions = await sdk.cascade.getSessions();

// Switch to a conversation
await sdk.cascade.focusSession(sessions[0].id);

// Send a message to the active chat
await sdk.cascade.sendPrompt('Analyze this file');

// Create a background conversation
const id = await sdk.cascade.createBackgroundSession('Run tests quietly');
Copy

Real-Time Event Monitoring

Watch for state changes as they happen — new conversations, step progress, session switches, preference updates.

// Agent made progress (added steps)
sdk.monitor.onStepCountChanged((e) => {
  statusBar.text = `${e.title}: step ${e.newCount}`;
});

// User switched to a different conversation
sdk.monitor.onActiveSessionChanged((e) => {
  console.log(`Now viewing: ${e.title}`);
});

// New conversation created
sdk.monitor.onNewConversation(() => {
  console.log('New conversation detected');
});

// Any USS state changed (preferences, settings, etc.)
sdk.monitor.onStateChanged((e) => {
  console.log(`${e.key}: ${e.previousSize} → ${e.newSize} bytes`);
});

sdk.monitor.start(3000, 5000); // USS poll: 3s, trajectory poll: 5s
Copy

Agent Step Control

Programmatically accept, reject, or run agent actions — build approval workflows, auto-accept policies, or custom review UIs.

await sdk.cascade.acceptStep();           // Accept code edit
await sdk.cascade.rejectStep();           // Reject code edit
await sdk.cascade.acceptTerminalCommand(); // Accept terminal command
await sdk.cascade.rejectTerminalCommand(); // Reject terminal command
await sdk.cascade.runTerminalCommand();    // Run pending command
await sdk.cascade.acceptCommand();         // Accept non-terminal action
Copy

State & Preferences

Read the agent's current settings — terminal policies, secure mode, sandbox config, and more. Decoded directly from protobuf sentinel values.

const prefs = await sdk.cascade.getPreferences();

prefs.terminalExecutionPolicy  // OFF | AUTO | EAGER
prefs.artifactReviewPolicy     // ALWAYS | TURBO | AUTO
prefs.secureModeEnabled        // boolean
prefs.terminalSandboxEnabled   // boolean
prefs.shellIntegrationEnabled  // boolean
prefs.allowNonWorkspaceFiles   // boolean
// ... 16 preferences total
Copy

IDE Diagnostics

Access system information, extension logs, and recent conversation metadata.

const diag = await sdk.cascade.getDiagnostics();

console.log(diag.systemInfo.operatingSystem);
console.log(diag.systemInfo.userName);
console.log(diag.isRemote); // SSH?

// MCP URL, browser port, git status
const mcpUrl = await sdk.cascade.getMcpUrl();
const browserPort = await sdk.cascade.getBrowserPort();
const ignored = await sdk.cascade.isFileGitIgnored('secret.env');
Copy

---

Architecture

Your Extension
     │
     ▼
┌──────────────────────────────────────────┐
│            antigravity-sdk               │
│                                          │
│  sdk.cascade     ← CascadeManager       │
│    Sessions, preferences, step control   │
│                                          │
│  sdk.monitor     ← EventMonitor         │
│    USS polling, trajectory tracking      │
│                                          │
│  sdk.integration ← IntegrationManager   │
│    Declarative UI for Agent View         │
│                                          │
│  sdk.commands    ← CommandBridge         │
│    60+ verified Antigravity commands     │
│                                          │
│  sdk.state       ← StateBridge          │
│    Read-only access to USS preferences   │
│                                          │
│  sdk.ls          ← LSBridge             │
│    Local LS communication (advanced)     │
│                                          │
└────────────────────────────────────────-─┘
         │
    vscode.commands.executeCommand()
    + read-only state.vscdb (sql.js)
Copy

---

Compliance

What this SDK is for

• Building VS Code extensions that run inside Antigravity IDE
• Extending Antigravity's functionality for your own workflows
• Adding custom UI elements to the Agent View
• Monitoring and automating agent step approval
• Reading preferences and conversation metadata

What this SDK is NOT for

• Integrating Antigravity with external applications or services
• Proxying or relaying requests to Google's infrastructure
• Extracting AI model outputs for training other models
• Accessing Google's backend servers, gRPC endpoints, or auth systems
• Building alternative clients or wrappers around Antigravity

How it works

All SDK communication goes through two safe channels:

1. vscode.commands.executeCommand() — the standard VS Code Extension API that all extensions use. Antigravity decides what to execute.
2. Read-only local state — the SDK reads state.vscdb for preferences and metadata, never writes.

The SDK includes a SENSITIVE_KEYS blocklist that prevents extension developers from accidentally (or intentionally) accessing authentication data.

---

Documentation

• GEMINI.md — Full internal architecture docs, verified DOM selectors, protobuf schemas
• LEGAL.md — Legal notice, interoperability rights, compliance details
• API Reference — TypeDoc (coming soon)

---

Contributing

This is a community project. PRs welcome!

1. Fork the repo
2. Create a feature branch
3. Follow the existing code style
4. Add JSDoc comments for all public methods
5. Submit a PR

---

Disclaimer

---

License

AGPL-3.0-or-later