### Install the SDK

Source: https://github.com/silo-code/silo/blob/main/packages/sdk/README.md

Install the SDK as a development dependency.

```sh
npm i -D @silo-code/sdk
```

--------------------------------

### Build and install the extension

Source: https://github.com/silo-code/silo/blob/main/examples/extensions/sdk-playground-extension/README.md

Commands to install dependencies and build the extension package for local installation.

```sh
pnpm install
pnpm --filter sdk-playground-extension build   # → dist/index.js
```

--------------------------------

### Install the extension

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/your-first-extension.md

Install the extension from the current directory into Silo.

```sh
silo install .       # install from the current folder
```

--------------------------------

### Initialize and run Silo development environment

Source: https://github.com/silo-code/silo/blob/main/CONTRIBUTING.md

Commands to install dependencies and start the isolated development build from the repository root.

```bash
pnpm install
pnpm dev             # runs the isolated "Silo Dev" build
```

--------------------------------

### Install extension from a Git repository

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/sharing-extensions.md

Clone a repository and build the extension locally before installing it.

```sh
git clone https://github.com/you/my-extension
cd my-extension
npm install && npm run build
silo install .
```

--------------------------------

### Build and install the extension

Source: https://github.com/silo-code/silo/blob/main/examples/extensions/permissions-demo-extension/README.md

Commands to install dependencies and build the extension into the dist directory.

```sh
pnpm install
pnpm --filter permissions-demo-extension build   # produces dist/index.js
```

--------------------------------

### Install SDK and React dependencies

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/publishing-an-extension.md

Install the SDK and React as devDependencies to ensure they are not bundled with the extension.

```sh
npm i -D @silo-code/sdk react @types/react
```

--------------------------------

### Start Development Server

Source: https://github.com/silo-code/silo/blob/main/docs/automation.md

Command to initiate the development environment.

```bash
pnpm dev
```

--------------------------------

### Manage extension installation

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/claude-skill.md

Commands to install or remove extensions from the local environment.

```bash
silo install <path>        # install from a local folder
silo uninstall <id>        # remove by extension id
```

--------------------------------

### Install extension from a local folder

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/sharing-extensions.md

Use this command to install an extension directly from a local directory path.

```sh
silo install /path/to/my-extension
```

--------------------------------

### Create Terminal Examples

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/state/terminals.md

Examples showing how to open a shell terminal in the active workspace or a specific terminal kind in a designated workspace.

```tsx
// open a shell terminal in the active workspace, rooted at a folder
ctx.terminals.create({ cwd: "/path/to/project" });

// open a specific kind in a specific workspace
ctx.terminals.create({ kind: "claude", workspaceId });
```

--------------------------------

### EmptyState Usage Examples

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/EmptyState.md

Examples showing how to implement EmptyState with different tones and content.

```tsx
<EmptyState
  tone="ok"
  icon={<CheckIcon />}
  title="All workflows passing"
  description="No failures or active runs on this repo."
/>

<EmptyState
  icon={<SearchIcon />}
  title="No matching branches"
  description="Try a different filter."
/>
```

--------------------------------

### Button Usage Examples

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/Button.md

Examples demonstrating different button variants and sizes.

```tsx
<Button onClick={cancel}>Cancel</Button>
<Button variant="primary" onClick={save}>Save</Button>
<Button variant="danger" onClick={remove}>Delete</Button>
<Button size="sm">Compact</Button>
```

--------------------------------

### Performing HTTP Requests with fetch

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/net/index.md

Examples of performing GET and POST requests using the fetch method.

```ts
const { status, headers, body, finalUrl } = await ctx.net.fetch(
  "https://api.example.com/data",
);

// POST with a JSON body
const res = await ctx.net.fetch("https://api.example.com/items", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "example" }),
  timeoutMs: 5000,
});
```

--------------------------------

### ModalActions Usage Examples

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/ModalActions.md

Examples demonstrating standard button alignment and the use of the optional start slot.

```tsx
<ModalActions>
  <Button onClick={close}>Cancel</Button>
  <Button variant="primary" onClick={save}>Create</Button>
</ModalActions>

<ModalActions start="6 sessions · 6 procs">
  <Button>Go to Terminal</Button>
  <Button variant="danger">End Task</Button>
</ModalActions>

<ModalActions
  start={<Button size="sm" onClick={create}>+ Create branch</Button>}
>
  <Button onClick={fetch}>Fetch</Button>
</ModalActions>
```

--------------------------------

### Install @silo-code/git-api

Source: https://github.com/silo-code/silo/blob/main/packages/git-api/README.md

Install the package as a devDependency.

```sh
npm i -D @silo-code/git-api
```

--------------------------------

### Install an extension via CLI

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/sharing-extensions.md

Install a registered extension directly from the command line using its unique ID.

```bash
silo install <id>
```

--------------------------------

### Build the extension

Source: https://github.com/silo-code/silo/blob/main/examples/extensions/clock-extension/README.md

Commands to install dependencies and compile the extension into the dist directory.

```bash
npm install
npm run build      # → dist/index.js
```

--------------------------------

### Build the Modal Gallery extension

Source: https://github.com/silo-code/silo/blob/main/examples/extensions/modal-gallery-extension/README.md

Commands to install dependencies and build the extension bundle.

```sh
pnpm install
pnpm --filter modal-gallery-extension build   # → dist/index.js
```

--------------------------------

### Install extension via npm tarball URL

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/sharing-extensions.md

Directly provide the tarball URL for installation.

```text
https://registry.npmjs.org/silo-my-clock/-/silo-my-clock-0.1.0.tgz
```

--------------------------------

### Install extension from a collection repository

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/sharing-extensions.md

Install a specific extension from a subfolder within a collection repository.

```sh
git clone https://github.com/you/my-extensions
cd my-extensions/clock && npm install && npm run build && silo install .
```

--------------------------------

### Install and Authenticate with Acme CLI

Source: https://github.com/silo-code/silo/blob/main/apps/website/src/workspaces/docs/files/getting-started.mdx

Use these commands to install the CLI globally and authenticate your session.

```bash
npm install -g acme-cli
acme login
```

--------------------------------

### Register a file type example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/registration/register-file-type.md

An example of registering a file type with an ID, label, extensions, and new file creation settings.

```tsx
ctx.registerFileType({
  id: "acme.foo",
  label: "Foo File",
  extensions: [".foo"],
  newFile: { defaultName: "Untitled" },
});
```

--------------------------------

### Initialize and run development environment

Source: https://github.com/silo-code/silo/blob/main/README.md

Install project dependencies and launch the isolated Silo development application.

```bash
pnpm install
pnpm dev             # runs the "Silo Dev" build (isolated identity + data)
```

--------------------------------

### Managing Editors and Commands

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/editors/index.md

Examples for opening files in the editor and registering a save command.

```tsx
// open a file in the active workspace
ctx.editors.open("/path/to/file.ts");

// open it as a (single-click) preview tab
ctx.editors.open("/path/to/file.ts", { preview: true });

// jump to and select a match (e.g. from a search result) — 1-indexed
ctx.editors.open("/path/to/file.ts", {
  selection: { line: 42, column: 8, endLine: 42, endColumn: 13 },
});

// a command that saves the focused editor
ctx.registerCommand({
  id: "acme.save",
  label: "Save",
  run: () => ctx.editors.save(),
});
```

--------------------------------

### Workspace and Panel Automation

Source: https://github.com/silo-code/silo/blob/main/docs/automation.md

Example of initializing a workspace, opening a file, and activating the resulting panel using curl.

```bash
# Stand up a sandbox workspace, open a file in it, focus that panel
curl -s localhost:7878 -H 'X-Silo-Automation: 1' -d '{"op":"openWorkspace","args":{"folder":"/tmp/silo-sandbox","name":"sandbox"}}'
# {"ok":true,"result":{"id":"ws_…"}}
curl -s localhost:7878 -H 'X-Silo-Automation: 1' -d '{"op":"openFile","args":{"path":"/tmp/silo-sandbox/a.txt"}}'
# {"ok":true,"result":{"editorId":"ed_…","panelId":"editor:ed_…"}}
curl -s localhost:7878 -H 'X-Silo-Automation: 1' -d '{"op":"activatePanel","args":{"panelId":"editor:ed_…"}}'
```

--------------------------------

### Install extension via npm package name

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/sharing-extensions.md

Enter the package name in the Silo settings to install the extension.

```text
silo-my-clock
```

--------------------------------

### Path utility usage example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/variables/path.md

Demonstrates common path operations including dirname, join, relative, and extname.

```ts
import { path } from "@silo-code/sdk";

const dir  = path.dirname(filePath);            // "/home/user/docs"
const full = path.join(dir, "images/fig.png");  // "/home/user/docs/images/fig.png"
const rel  = path.relative(dir, full);           // "images/fig.png"
const ext  = path.extname(full);                 // ".png"
```

--------------------------------

### Open External Usage Examples

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/UiService.md

Demonstrates opening a URL and handling potential rejections from unsupported schemes.

```ts
// open a docs link in the browser
await ctx.ui.openExternal("https://getsilo.dev/docs");

// route a clicked Markdown link safely — bad schemes just reject
try {
  await ctx.ui.openExternal(href);
} catch {
  ctx.ui.notify("warn", "That link can't be opened.");
}
```

--------------------------------

### Install the silo-extension-builder skill

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/claude-skill.md

Downloads the skill definition file to the global Claude Code skills directory.

```bash
mkdir -p ~/.claude/skills/silo-extension-builder && \
  curl -fsSL -o ~/.claude/skills/silo-extension-builder/SKILL.md \
  https://raw.githubusercontent.com/silo-code/silo/main/skills/silo-extension-builder/SKILL.md
```

--------------------------------

### Register a command example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/registration/register-command.md

A basic implementation of a command with an ID, label, and execution function.

```tsx
ctx.registerCommand({
  id: "acme.sayHi",
  label: "Acme: Say Hi",
  run: () => console.log("hi"),
});
```

--------------------------------

### Register a keybinding example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/registration/register-keybinding.md

A basic implementation of registering a keybinding with an ID, key combination, and command.

```tsx
ctx.registerKeybinding({
  id: "acme.sayHi",
  key: "cmd+shift+h",
  command: "acme.sayHi",
});
```

--------------------------------

### Build and install Silo extensions

Source: https://github.com/silo-code/silo/blob/main/examples/extensions/README.md

Commands to build a specific extension package from the workspace.

```sh
pnpm install
pnpm --filter <name>-extension build      # e.g. hello-extension → dist/index.js
```

--------------------------------

### ctx.ui.prompt(options)

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/ui/index.md

Displays a prompt dialog to get a string input.

```APIDOC
## ctx.ui.prompt(options)

### Description
Prompts the user for a string input.

### Parameters
- **options** (object) - Configuration including title and initialValue.

### Returns
- **Promise<string | null>** - The entered string, or null if cancelled.
```

--------------------------------

### Usage Examples for ActivityGlyph

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/ActivityGlyph.md

Examples demonstrating how to use the ActivityGlyph component with different activity states and sizes.

```tsx
<ActivityGlyph activity="working" size="md" />
<ActivityGlyph activity="ready" />
<ActivityGlyph size="sm" /> // workspace neutral (omit)
```

--------------------------------

### Register a Theme Preset Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/registration/register-theme-preset.md

Demonstrates how to define and register a custom theme preset with specific color variables.

```ts
ctx.theme.registerPreset({
  id: "acme.midnight",
  name: "Midnight",
  base: "dark", // Monaco/xterm base + the data-theme attribute
  colorScheme: "dark",
  vars: {
    "--silo-color-bg": "#0b0f1a",
    "--silo-color-accent": "#5eb1ff",
    // …any subset of ThemeVars; the base palette fills the rest
  },
});
```

--------------------------------

### Publish extension to npm

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/sharing-extensions.md

Use this command to make your extension installable via package name.

```sh
npm publish --access public
```

--------------------------------

### Retrieving Output Logs

Source: https://github.com/silo-code/silo/blob/main/docs/automation.md

Examples for querying application logs, including listing channels, filtering by level, and searching by keyword.

```bash
# List all channels and the most-recent 200 entries from the first one
curl -s localhost:7878 -H 'X-Silo-Automation: 1' -d '{"op":"outputLogs"}'

# Last 50 errors from the notifications channel
curl -s localhost:7878 -H 'X-Silo-Automation: 1' \
  -d '{"op":"outputLogs","args":{"channel":"silo:notifications","level":"error","limit":50}}'

# Search across all levels for a keyword
curl -s localhost:7878 -H 'X-Silo-Automation: 1' \
  -d '{"op":"outputLogs","args":{"search":"workspace","limit":100}}'
```

--------------------------------

### ctx.process.spawn(opts)

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/process/index.md

Starts a new persistent PTY session in the specified working directory.

```APIDOC
## spawn(opts)

### Description
Starts a new session in `opts.cwd`. Resolves to a `ProcessSession` object.

### Parameters
- **opts** (ProcessSpawnOptions) - Required - Configuration options including `cwd`, `cols`, and `rows`.
```

--------------------------------

### Initialize a New Project

Source: https://github.com/silo-code/silo/blob/main/apps/website/src/workspaces/docs/files/getting-started.mdx

Create a new project directory and configuration using the init command.

```bash
acme init my-project
```

--------------------------------

### Manage extensions via CLI

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/cli.md

Install or uninstall extensions using registry IDs, local paths, or URLs.

```sh
silo install silo.local-web-viewer   # install from the Silo registry by id
silo install /path/to/my-extension   # install from a local folder
silo install <url-or-npm>            # install from a tarball URL or npm name
silo uninstall acme.clock            # uninstall an extension by id
```

--------------------------------

### Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/focusGroupNextIndex.md

Calculates the next index and updates state if a valid navigation index is returned.

```ts
const next = focusGroupNextIndex({
  current: activeIndex, count: items.length, key: e.key,
  orientation: "vertical", wrap: true,
  isNavigable: (i) => !items[i].disabled,
});
if (next !== null) setActiveIndex(next);
```

--------------------------------

### Install and uninstall extensions via registry ID

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/extensions.md

Use the CLI to manage extensions by their registry identifier.

```sh
silo install silo.local-web-viewer   # install by registry id
silo uninstall silo.local-web-viewer
```

--------------------------------

### Define start property

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/FocusGroupOptions.md

Sets the initial index for focus entry, defaulting to 0.

```ts
optional start?: number;
```

--------------------------------

### Get Active Selection Text Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/UiService.md

Demonstrates retrieving the current selection and using it as a seed for a search operation.

```ts
const seed = ctx.ui.getActiveSelectionText();
if (seed) runSearch(seed);
```

--------------------------------

### Register a menu item example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/registration/register-menu-item.md

A basic implementation of registering a command to the view menu under a specific group.

```tsx
ctx.registerMenuItem({
  id: "acme.sayHi",
  menu: "view",
  command: "acme.sayHi",
  group: "5_acme",
});
```

--------------------------------

### Implement a focusable list

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/other/use-focus-group.md

Example of using useFocusGroup to manage a listbox with keyboard navigation and activation handlers.

```tsx
import { useFocusGroup } from "@silo-code/sdk";

function List({ items, ctx }) {
  const activeIndex = items.findIndex((it) => it.selected);
  const group = useFocusGroup({
    count: items.length,
    start: activeIndex >= 0 ? activeIndex : 0, // entry parks on the selected row
    onActivate: (i) => ctx.workspaces.activate(items[i].id), // Enter / Space
    onMenu: (i, anchor) =>
      ctx.ui.showMenu({ anchor, items: menuFor(items[i]) }),
  });

  return (
    <ul role="listbox" {...group.containerProps}>
      {items.map((it, i) => (
        <li key={it.id} role="option" {...group.getItemProps(i)}>
          {it.label}
        </li>
      ))}
    </ul>
  );
}
```

--------------------------------

### Implement badge provider

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/WorkspaceService.md

Example of using bindBadge to provide dynamic status badges for workspaces.

```ts
ctx.subscriptions.push(
  ctx.workspaces.bindBadge({
    id: "my-ext.badges",
    provide(workspaceId) {
      const status = getStatus(workspaceId);
      if (!status) return [];
      return [{ id: "status", text: status.label, color: status.color }];
    },
  }),
);
```

--------------------------------

### Manage Silo Extensions

Source: https://github.com/silo-code/silo/blob/main/README.md

Commands to install extensions from the registry or local paths, and to uninstall existing extensions.

```bash
silo install silo.local-web-viewer              # from the registry by id
silo install ~/my-extensions/dave.git-branch    # or from a local folder
silo uninstall dave.git-branch
```

--------------------------------

### Implementing a Focus Group

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/useFocusGroup.md

Example of using the hook to manage a list of items with keyboard navigation and activation handlers.

```tsx
const group = useFocusGroup({
  count: items.length,
  start: activeIndex,
  onActivate: (i) => select(items[i].id),
  onMenu: (i, anchor) => showMenu(items[i], anchor),
});
return (
  <ul {...group.containerProps}>
    {items.map((it, i) => (
      <li key={it.id} {...group.getItemProps(i)}>{it.label}</li>
    ))}
  </ul>
);
```

--------------------------------

### List Component Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/List.md

An example of implementing a List with a ListRow child.

```tsx
<List aria-label="Workspace folders">
  <ListRow
    selected={folder.primary}
    leading={<FolderIcon />}
    trailing={<Badge tone="accent">primary</Badge>}
    onSelect={() => choose(folder)}
  >
    {folder.path}
  </ListRow>
</List>
```

--------------------------------

### Display workspace menu in UI

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/WorkspaceService.md

Example of integrating workspace menu items into a custom UI context menu.

```ts
ctx.ui.showMenu({
  items: [
    { label: "Mark as seen", run: acknowledge },
    { type: "separator" },
    { label: ws.name, submenu: ctx.workspaces.getWorkspaceMenuItems(ws.id) },
  ],
  at: { x: e.clientX, y: e.clientY },
});
```

--------------------------------

### show()

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/LogService.md

Opens or focuses the Output panel and selects the current extension's channel.

```APIDOC
## show()

### Description
Open (or focus) the Output panel and select this extension's channel.

### Returns
- **void**
```

--------------------------------

### Install API types

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/extension-apis.md

Add the API types package as a devDependency to ensure they are available for compile-time checking without bundling.

```sh
npm i -D @you/your-api
```

--------------------------------

### InlineEdit Usage Examples

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/InlineEdit.md

Examples showing standard single-line and multiline usage of the InlineEdit component.

```tsx
<InlineEdit
  value={ws.name}
  onSave={(name) => ctx.workspaces.rename(ws.id, name)}
  validate={validateWorkspaceName}
  aria-label="Rename workspace"
/>

<InlineEdit
  multiline
  value={description}
  onSave={setDescription}
  aria-label="Edit description"
/>
```

--------------------------------

### IconButton Usage Examples

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/IconButton.md

Examples showing standard, compact, and toolbar-variant usage of the IconButton component.

```tsx
<IconButton aria-label="Refresh" onClick={refresh}>
  <RefreshIcon size="1em" />
</IconButton>

// compact — e.g. in a ListRow's trailing slot
<IconButton size="sm" aria-label="Pin" onClick={pin}>
  <PinIcon size="1em" />
</IconButton>

// panel / breadcrumb toolbar (local-web-viewer tone)
<IconButton size="sm" variant="toolbar" aria-label="Mark">
  <FlagIcon size="1em" weight="bold" />
</IconButton>
```

--------------------------------

### Compile and Build Extension

Source: https://github.com/silo-code/silo/blob/main/skills/silo-extension-builder/SKILL.md

Commands for building the extension project.

```bash
cd <path> && npm run build
```

--------------------------------

### Scaffold a new extension

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/sharing-extensions.md

Use this command to initialize a new extension project with the necessary GitHub Actions workflow.

```bash
npx create-silo-extension
```

--------------------------------

### Register a status item example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/registration/register-status-item.md

An example of registering a status item with an ID, alignment, priority, and a React component.

```tsx
ctx.registerStatusItem({
  id: "acme.clock",
  alignment: "right",
  priority: 10,
  component: Clock, // a React component
});
```

--------------------------------

### Run development and test commands

Source: https://github.com/silo-code/silo/blob/main/apps/website/README.md

Use these commands to preview the homepage locally or execute unit tests for the package.

```bash
# Standalone homepage preview
pnpm --filter @silo-code/website dev

# Unit tests
pnpm --filter @silo-code/website test
```

--------------------------------

### activePanel

Source: https://github.com/silo-code/silo/blob/main/docs/automation.md

Gets the currently active panel.

```APIDOC
## activePanel

### Description
Returns the panel ID currently shown in the center dock.

### Response
- **panelId** (string) - The ID of the active panel or null
```

--------------------------------

### get()

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/WorkspaceService.md

Performs a one-shot lookup for a workspace by its ID.

```APIDOC
## get()

### Description
Retrieves a specific workspace by its ID. Returns undefined if not found.

### Parameters
- **id** (string) - The ID of the workspace to retrieve.

### Returns
- **Workspace | undefined** - The workspace object or undefined.
```

--------------------------------

### Build the extension

Source: https://github.com/silo-code/silo/blob/main/examples/extensions/process-monitor/README.md

Run this command to build the extension and generate the dist/index.js file.

```sh
node build.mjs
```

--------------------------------

### Uninstall the extension

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/your-first-extension.md

Remove an installed extension from Silo using its ID.

```sh
silo uninstall acme.clock
```

--------------------------------

### Accessing System Information in an Extension

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/SystemService.md

Demonstrates retrieving host OS, architecture, and Silo version within an extension's activate method.

```ts
export const extension: Extension = {
  id: "my.platform-aware",
  async activate(ctx) {
    const { os, arch, siloVersion } = await ctx.system.getInfo();

    if (os === "macos") {
      // Register a macOS-specific command.
      ctx.subscriptions.push(
        ctx.registerCommand({
          id: "my.reveal-in-finder",
          label: "Reveal in Finder",
          run() { ... },
        }),
      );
    }

    ctx.ui.notify("info", `Running Silo ${siloVersion} on ${os}/${arch}`);
  },
};
```

--------------------------------

### Get directory name

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/variables/path.md

Extracts the directory portion of a path string.

```ts
dirname(p): string;
```

--------------------------------

### ctx.ui.pickFolder()

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/ui/index.md

Opens a native OS folder picker dialog.

```APIDOC
## ctx.ui.pickFolder()

### Description
Opens a native OS dialog for the user to select a folder.

### Returns
- **Promise<string | null>** - The path of the selected folder, or null if cancelled.
```

--------------------------------

### Get Layout State

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/LayoutService.md

Retrieves the current frozen layout state.

```ts
getState(): LayoutState;
```

--------------------------------

### Tabs Component Usage

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/Tabs.md

Example of implementing the Tabs component alongside a TabPanel.

```tsx
<Tabs
  tabs={[
    { id: "panels", label: "Side Panels" },
    { id: "statusBar", label: "Status Bar" },
    { id: "options", label: "Options" },
  ]}
  active={tab}
  onSelect={setTab}
/>
<TabPanel>{tab === "panels" && <PanelsSettings />}</TabPanel>
```

--------------------------------

### TabPanel Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/TabPanel.md

Basic implementation of a TabPanel containing conditional content.

```tsx
<TabPanel>{tab === "panels" && <PanelsSettings />}</TabPanel>
```

--------------------------------

### Build the extension

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/your-first-extension.md

Use npm scripts to compile the extension code using esbuild.

```sh
cd acme.clock
npm run build        # one-shot compile
npm run dev          # watch mode — recompiles on every save
```

--------------------------------

### AddRow Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/AddRow.md

Basic implementation of the AddRow component placed after a List.

```tsx
<List aria-label="Folders">…</List>
<AddRow onClick={addFolder}>Add Folder…</AddRow>
```

--------------------------------

### Local Development Commands for Extensions Registry

Source: https://github.com/silo-code/silo/blob/main/docs/extensions-registry-repo.md

Commands to run tests, ingest data, build the static site, and start the development server for the catalog.

```sh
npm test
GITHUB_TOKEN=$(gh auth token) npm run ingest
npm run build          # → dist/ (what GitHub Pages serves)
cd site && npm run dev # Astro catalog against a freshly built index
```

--------------------------------

### Get Workspace State

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/WorkspaceService.md

Retrieves the current frozen view of the workspace state.

```ts
getState(): WorkspaceState;
```

--------------------------------

### Scaffold a new extension

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/your-first-extension.md

Use the scaffolding tool to initialize a new extension project.

```sh
npx create-silo-extension
```

```sh
npx create-silo-extension --id acme.clock --name "Clock" --path ~/my-extensions/acme.clock
```

--------------------------------

### Implement Extension Lifecycle Methods

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/Extension.md

Methods for initializing the extension and performing cleanup.

```ts
activate(ctx): void | API;
```

```ts
optional deactivate(): void;
```

--------------------------------

### Reactive Workspace Subscription

Source: https://github.com/silo-code/silo/blob/main/skills/silo-extension-builder/SKILL.md

Example of subscribing to workspace state within a React component.

```typescript
function MyStatusWidget() {
  const ws = useServiceState(ctx.workspaces);
  const folder = ws.open.find((w) => w.id === ws.activeId)?.folder ?? null;
  // ...
}
```

--------------------------------

### Persisting Extension Settings

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/storage/index.md

Demonstrates reading settings during activation and subscribing to changes to handle asynchronous state updates.

```ts
export const extension: Extension = {
  id: "my.extension",
  activate(ctx) {
    const store = ctx.storage.global;

    const apply = () => render(store.get<Settings>("settings", DEFAULTS));
    apply();
    ctx.subscriptions.push({ dispose: store.subscribe(apply) });

    // later, from a settings page or panel:
    store.set("settings", next);
  },
};
```

--------------------------------

### Use useServiceState in a component

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/useServiceState.md

Example of subscribing to a workspace service within a React component.

```tsx
function Panel({ ctx }: { ctx: ExtensionContext }) {
  const ws = useServiceState(ctx.workspaces);
  return <span>{ws.open.length} open workspaces</span>;
}
```

--------------------------------

### Tooltip Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/Tooltip.md

Basic implementation of the Tooltip component wrapping a button trigger.

```tsx
<Tooltip content="New File">
  <button onClick={createFile}>
    <FilePlus size="1.2em" />
  </button>
</Tooltip>
```

--------------------------------

### ctx.ui.pickFile(options)

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/ui/index.md

Opens a native OS file picker dialog with optional filters.

```APIDOC
## ctx.ui.pickFile(options)

### Description
Opens a native OS dialog for the user to select a file.

### Parameters
- **options** (object) - Configuration object containing filters (e.g., { name: string, extensions: string[] }).

### Returns
- **Promise<string | null>** - The path of the selected file, or null if cancelled.
```

--------------------------------

### SearchInput Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/SearchInput.md

Basic implementation of the SearchInput component with value binding and a placeholder.

```tsx
<SearchInput
  value={query}
  onValueChange={setQuery}
  placeholder="Filter branches…"
/>
```

--------------------------------

### RadioGroup Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/RadioGroup.md

Basic implementation of a RadioGroup containing multiple RadioCard components.

```tsx
<RadioGroup value={mode} onChange={setMode}>
  <RadioCard
    value="clear"
    title="Clear the finished indicator"
    description="Viewing the terminal acknowledges the run — the green check disappears."
  />
  <RadioCard
    value="keep"
    title="Keep it until the next run"
    description="Viewing changes nothing."
  />
</RadioGroup>
```

--------------------------------

### create(input?)

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/state/terminals.md

Opens a new terminal in a workspace, defaulting to the active one. Returns the terminal record.

```APIDOC
## create(input?)

### Description
Opens a new terminal in a workspace. Defaults to the active workspace if none is specified.

### Parameters
- **input** (object) - Optional - Configuration object for the terminal, including `cwd` (current working directory) or `kind` (terminal type).
```

--------------------------------

### CheckboxRow Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/CheckboxRow.md

Basic implementation of the CheckboxRow component with a label and change handler.

```tsx
<CheckboxRow
  label="Only monitor the checked-out branch"
  checked={onlyCheckedOut}
  onChange={setOnlyCheckedOut}
/>
```

--------------------------------

### Callout Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/Callout.md

Basic implementation of the Callout component wrapping explanatory text.

```tsx
<Callout>
  Opening a worktree adds it as another folder in this workspace — its
  files, terminals, and Git panel appear alongside your current ones.
  Closing a view leaves the worktree untouched on disk.
</Callout>
```

--------------------------------

### Triggering a Core Command

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/other/execute-command.md

Example of invoking a core command from a user interface component.

```tsx
// trigger a core command from your own UI
ctx.executeCommand("view.toggleLeftPanel");
```

--------------------------------

### create()

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/WorkspaceService.md

Creates a new workspace from input data.

```APIDOC
## create()

### Description
Creates a workspace using the provided input configuration.

### Parameters
- **input** (CreateWorkspaceInput) - The configuration for the new workspace.

### Returns
- **Workspace** - The created workspace object.
```

--------------------------------

### Get basename

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/variables/path.md

Returns the final component of a path, optionally stripping a specified extension.

```ts
basename(p, ext?): string;
```

--------------------------------

### Implement a status-bar toggle extension

Source: https://github.com/silo-code/silo/blob/main/apps/docs/guide/what-is-an-extension.md

A complete example demonstrating how to read state via a typed service and execute commands using the ExtensionContext.

```ts
import type { Extension } from "@silo-code/sdk";
import { useServiceState } from "@silo-code/sdk";

export const extension: Extension = {
  id: "acme.panel-toggle",
  activate(ctx) {
    const { layout } = ctx;

    function PanelToggles() {
      const state = useServiceState(layout);       // read state via a typed service
      return (
        <button
          className={state.left.collapsed ? "" : "active"}
          onClick={() => ctx.executeCommand("view.toggleLeftPanel")}  // act via a command
        >
          ▢
        </button>
      );
    }

    ctx.registerStatusItem({ id: "panel-toggles", alignment: "right", component: PanelToggles });
  },
};
```

--------------------------------

### Run recorder commands

Source: https://github.com/silo-code/silo/blob/main/apps/website-recorder/README.md

Commands for launching the UI, performing headless captures, and running unit tests.

```bash
# Open the recorder UI
pnpm --filter @silo-code/website-recorder recorder
# → http://127.0.0.1:5180/recorder.html

# Headless capture (writes into apps/website/src/assets/)
pnpm --filter @silo-code/website-recorder capture:feature-git

# Unit tests
pnpm --filter @silo-code/website-recorder test
```

--------------------------------

### Get current theme state

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/ThemeService.md

Retrieves the current frozen view of the theme state.

```ts
getState(): ThemeState;
```

--------------------------------

### prompt(opts)

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/UiService.md

Displays a host-rendered single-line input dialog and returns the entered string or null if cancelled.

```APIDOC
## prompt(opts)

### Description
Pop a host-rendered single-line input dialog and resolve to the entered string, or null if the user cancelled.

### Parameters
- **opts** (PromptOptions) - Required - Configuration options for the prompt dialog.
```

--------------------------------

### Get Editor State

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/EditorService.md

Returns a referentially stable snapshot of the current editor state.

```ts
getState(): EditorsState;
```

```ts
const { active } = ctx.editors.getState();
if (active) ctx.log.info(`Active file: ${active.filePath ?? "(untitled)"}`);
```

--------------------------------

### Get file metadata

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/FileService.md

Retrieves metadata for a path, returning null if the path does not exist.

```ts
stat(path): Promise<FileMeta | null>;
```

--------------------------------

### Create directory

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/FileService.md

Creates a new directory and any missing parent directories.

```ts
createDir(path): Promise<void>;
```

--------------------------------

### createFromFolderPicker()

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/WorkspaceService.md

Opens a folder picker to create a new workspace.

```APIDOC
## createFromFolderPicker()

### Description
Displays a system folder picker and creates a new workspace from the selected folder.

### Returns
- **Promise<Workspace | null>** - A promise resolving to the created workspace or null if cancelled.
```

--------------------------------

### activate()

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/interfaces/WorkspaceService.md

Activates a workspace.

```APIDOC
## activate()

### Description
Activates the specified workspace, reopening it if it was previously closed.

### Parameters
- **id** (string) - The ID of the workspace to activate.
```

--------------------------------

### SettingRow Usage Example

Source: https://github.com/silo-code/silo/blob/main/apps/docs/api/types/functions/SettingRow.md

A standard implementation of SettingRow containing a label, hint, and a Switch control.

```tsx
<SettingRow
  label="Format on save"
  hint="Run Format Document before writing to disk."
>
  <Switch
    checked={formatOnSave}
    onChange={setFormatOnSave}
    aria-label="Format on save"
  />
</SettingRow>
```