Tutorial 1: Hello World

This tutorial walks you through the absolute minimum needed to see something render in Tango. By the end you’ll have a sidebar panel showing a greeting.

1. Scaffold

bunx github:MartinGonzalez/tango-create
# Enter "hello-world" as the directory name, skip backend
cd hello-world

2. Write the panel

Replace src/index.tsx with:

import { defineReactInstrument, useInstrumentApi, UIRoot, UIPanelHeader, UISection, UICard } from "tango-api";

function SidebarPanel() {
  const api = useInstrumentApi();

  return (
    <UIRoot>
      <UIPanelHeader title="Hello World" subtitle={api.instrumentId} />
      <UISection title="Greeting">
        <UICard>
          <p>Hello from my first instrument!</p>
        </UICard>
      </UISection>
    </UIRoot>
  );
}

export default defineReactInstrument({
  defaults: {
    visible: { sidebar: true },
  },
  panels: {
    sidebar: SidebarPanel,
  },
});

3. Run it

bun run dev

Open Tango — your “Hello World” panel appears in the sidebar.

What just happened

Let’s break down the key pieces:

defineReactInstrument

This is the entry point for React-based instruments. It wraps your components with the API provider and handles mounting/unmounting:

export default defineReactInstrument({
  defaults: {
    visible: { sidebar: true },  // sidebar starts visible
  },
  panels: {
    sidebar: SidebarPanel,       // React component for the sidebar slot
  },
});

The defaults.visible object controls which panels are shown by default. Users can toggle panel visibility later.

useInstrumentApi

This hook gives you the full InstrumentFrontendAPI object:

const api = useInstrumentApi();

Through api you can access:

• api.instrumentId — your instrument’s unique ID
• api.storage — key-value, file, and SQLite storage
• api.sessions — start/stop Claude sessions
• api.events — subscribe to host events
• api.actions — call backend actions
• api.emit() — emit custom events
• api.settings — read/write instrument settings

UIRoot

Every panel should be wrapped in UIRoot. This component injects the Tango UI stylesheet so all tui-* components render with the correct theme:

<UIRoot>
  {/* your panel content */}
</UIRoot>

UIPanelHeader

A standardized header with title, optional subtitle, optional back button, and optional right-side actions:

<UIPanelHeader
  title="Hello World"
  subtitle="sidebar panel"
  rightActions={<UIBadge label="v1" tone="info" />}
/>

Next steps

Your panel is static right now. In the next tutorial you’ll use more UI components to build interactive interfaces.