### Clone and Setup Termcast

Source: https://github.com/remorses/termcast/blob/main/CONTRIBUTING.md

Clone the repository, navigate to the directory, and install dependencies using Bun.

```bash
git clone https://github.com/remorses/termcast
cd termcast/termcast
bun install
```

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

### Install Extension Dependencies

Source: https://github.com/remorses/termcast/blob/main/termcast/TESTING_RAYCAST_EXTENSIONS.md

Navigate to the downloaded extension's directory and install its dependencies using `bun install`.

```bash
cd extensions/<extension-name>
bun install
```

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

### Run Termcast Examples

Source: https://github.com/remorses/termcast/blob/main/CONTRIBUTING.md

Execute example extensions using Bun, with hot-reloading enabled for development.

```bash
bun --watch src/examples/simple-list.tsx
```

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

### Termcast Installation Script Example

Source: https://github.com/remorses/termcast/blob/main/README.md

Example of a curl command to install a Termcast TUI from a GitHub release. This script is typically provided after running `termcast release`.

```sh
curl -sf https://termcast.app/owner/repo/install | bash
```

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

### Install and Scaffold termcast

Source: https://github.com/remorses/termcast/blob/main/SKILL.md

Commands to install the CLI globally and initialize a new project.

```bash
bun install -g termcast
termcast new my-extension    # scaffold
cd my-extension && termcast dev   # hot-reload dev mode
```

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

### Install Local Extension

Source: https://github.com/remorses/termcast/blob/main/CONTRIBUTING.md

Add a local extension to Termcast's store using the `termcast install` command.

```bash
termcast install <path>
```

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

### Start Dev Mode

Source: https://github.com/remorses/termcast/blob/main/termcast/EXTENSIONS.md

Initializes an extension in development mode using a local filesystem path.

```typescript
startDevMode({ extensionPath })
```

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

### Log a greeting in TypeScript

Source: https://context7.com/remorses/termcast/llms.txt

A basic example demonstrating console output in a TypeScript environment.

```typescript
const greeting = "Hello, Terminal!"
console.log(greeting)
```

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

### Initialize and Develop Termcast Extensions

Source: https://context7.com/remorses/termcast/llms.txt

Commands to scaffold a new project and start the development server with hot reloading.

```bash
# Create a new extension
termcast new my-extension

# Navigate and start development
cd my-extension
termcast dev
```

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

### Open Termcast Home Screen

Source: https://github.com/remorses/termcast/blob/main/CONTRIBUTING.md

Launch Termcast to its default home screen, showing installed extensions.

```bash
termcast
```

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

### Create a Searchable List

Source: https://github.com/remorses/termcast/blob/main/SKILL.md

Example of a basic List component with various item configurations.

```tsx
import { List } from 'termcast'

export default function Command() {
  return (
    <List searchBarPlaceholder="Search items...">
      <List.Item title="First Item" subtitle="A subtitle" />
      <List.Item title="Second Item" accessories={[{ text: 'Badge' }]} />
      <List.Item
        title="Third Item"
        accessories={[
          { tag: { value: 'Important', color: Color.Red } },
          { date: new Date() },
        ]}
      />
    </List>
  )
}
```

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

### Install Termcast CLI

Source: https://github.com/remorses/termcast/blob/main/README.md

Installs the Termcast command-line interface globally using Bun. Note that this package requires Bun and does not work with Node.js.

```sh
bun install -g termcast
```

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

### Browse Extension Store

Source: https://github.com/remorses/termcast/blob/main/CONTRIBUTING.md

Access the Termcast extension store to browse and install extensions.

```bash
termcast store
```

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

### Start Compiled Mode

Source: https://github.com/remorses/termcast/blob/main/termcast/EXTENSIONS.md

Initializes a pre-compiled extension using embedded metadata and command components.

```typescript
startCompiledExtension({ packageJson, compiledCommands })
```

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

### Vitest Test File Structure for Extensions

Source: https://github.com/remorses/termcast/blob/main/termcast/TESTING_RAYCAST_EXTENSIONS.md

A Vitest test file template for automating extension testing. It includes setup for dependency installation, session launching, and tests that gracefully skip if the extension is not present locally.

```typescript
import { test, expect, beforeEach, afterEach, beforeAll } from 'vitest'
import { launchTerminal, Session } from 'tuistory/src'
import { spawnSync } from 'node:child_process'
import path from 'node:path'
import fs from 'node:fs'

const extensionDir = path.resolve(__dirname, '../../extensions/<extension-name>')

// Check if extension exists (gitignored, only present locally)
const extensionExists = fs.existsSync(extensionDir)

// Install dependencies before running tests (only if extension exists)
beforeAll(() => {
  if (!extensionExists) return

  // Skip if already installed
  if (fs.existsSync(path.join(extensionDir, 'node_modules', '.bin'))) {
    return
  }

  const result = spawnSync('bun', ['install'], {
    cwd: extensionDir,
    stdio: 'inherit',
    timeout: 120000,
  })

  if (result.status !== 0 || result.signal) {
    throw new Error(
      `bun install failed: status=${result.status}, signal=${result.signal}`,
    )
  }
}, 180000)

let session: Session

beforeEach(async (ctx) => {
  if (!extensionExists) {
    ctx.skip()
    return
  }
  session = await launchTerminal({
    command: 'bun',
    args: ['src/cli.tsx', 'dev', extensionDir],
    cwd: path.resolve(__dirname, '../..'),
    cols: 80,
    rows: 30,
  })
})

afterEach(() => {
  session?.close()
})

test.skipIf(!extensionExists)('extension loads correctly', async () => {
  // Wait for the extension to load
  const initialView = await session.text({
    waitFor: (text) => {
      // Adjust this condition based on what the extension shows
      return /Some Expected Text/i.test(text)
    },
    timeout: 30000,
  })

  expect(initialView).toMatchInlineSnapshot()
}, 60000)

test.skipIf(!extensionExists)('extension navigation works', async () => {
  // Wait for initial load
  await session.text({
    waitFor: (text) => /Some Expected Text/i.test(text),
    timeout: 30000,
  })

  // Send key presses to navigate
  await session.press('down')
  
  const afterNavigate = await session.text()
  expect(afterNavigate).toMatchInlineSnapshot()

  // Open actions panel
  await session.press(['ctrl', 'k'])
  
  const actionsOpen = await session.text()
  expect(actionsOpen).toMatchInlineSnapshot()
}, 60000)

```

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

### Termcast App Build Command Example

Source: https://github.com/remorses/termcast/blob/main/termcast/CHANGELOG.md

Demonstrates the usage of the `termcast app build` command for creating standalone macOS `.app` and Windows folder bundles. This command wraps WezTerm with a compiled termcast extension into a portable desktop application.

```bash
termcast app build
```

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

### Run Termcast Extension in Development Mode

Source: https://github.com/remorses/termcast/blob/main/README.md

Starts the development server for a Termcast extension, enabling hot reloading for automatic updates on file changes.

```sh
termcast dev
```

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

### Navigate from List to Detail

Source: https://github.com/remorses/termcast/blob/main/termcast/ARCHITECTURE.md

Example of triggering a navigation push from a list view to a detail view with a cleanup callback.

```tsx
function ListView() {
  const navigation = useNavigation()

  const openDetail = () => {
    navigation.push(<DetailView itemId={selectedId} />, () =>
      console.log('Detail view closed'),
    )
  }
}
```

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

### Run Termcast E2E Tests

Source: https://github.com/remorses/termcast/blob/main/CONTRIBUTING.md

Execute end-to-end tests for Termcast examples. Use the -u flag to update snapshots.

```bash
bun e2e                                    # Run all
bun e2e src/examples/list.vitest.tsx -u   # Update snapshots
```

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

### Create and Develop a New Termcast Extension

Source: https://github.com/remorses/termcast/blob/main/README.md

Scaffolds a new Termcast extension and starts the development server with hot reloading. Navigate into the created directory before running the dev command.

```sh
termcast new my-extension
cd my-extension
termcast dev
```

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

### Verifying Test Assertions

Source: https://github.com/remorses/termcast/blob/main/PREFIX.md

Example of using expect to verify key behavior in E2E tests.

```tsx
expect(beforeEnter).toContain('[Undo')
expect(afterEnter).toContain('Undone')
```

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

### Run e2e tests

Source: https://github.com/remorses/termcast/blob/main/CLAUDE.md

Execute end-to-end tests for Termcast examples using the `bun e2e` command, specifying the test file path. Use the `-u` flag to update snapshots.

```bash
bun e2e src/examples/form-dropdown.vitest.tsx
```

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

### Create a GitHub issue

Source: https://github.com/remorses/termcast/blob/main/CLAUDE.md

Use the `gh issue create` command to open new issues on GitHub. Avoid using markdown headings in the body; opt for simple paragraphs, lists, and code examples for clarity.

```bash
gh issue create --title "Fix login timeout" --body "The login form times out after 5 seconds on slow connections. This affects users on mobile networks.

Steps to reproduce:
1. Open login page on 3G connection
2. Enter credentials
3. Click submit

Expected: Login completes within 30 seconds
Actual: Request times out after 5 seconds

Error in console:
```bash
Error: Request timeout at /api/auth/login
```"
```

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

### Show Toast Notifications with Different Styles

Source: https://github.com/remorses/termcast/blob/main/termcast/ARCHITECTURE.md

Provides examples of how to display user feedback using toast notifications, including success, error, and loading states. Ensure `showToast` and `Toast` are imported from 'termcast/src/toast'.

```typescript
import { showToast, Toast } from 'termcast/src/toast'

// Success
showToast({
  title: 'Success',
  message: 'File saved',
  style: Toast.Style.Success,
})

// Error
showToast({
  title: 'Error',
  message: error.message,
  style: Toast.Style.Failure,
})

// Loading
showToast({
  title: 'Loading',
  message: 'Fetching data...',
  style: Toast.Style.Animated,
})
```

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

### Start a tmux session for a background task

Source: https://github.com/remorses/termcast/blob/main/CLAUDE.md

Use this command to start a new tmux session in detached mode for background processes like development servers. Ensure to provide a descriptive session name and change the directory to your project's root.

```bash
tmux new-session -d -s project-name-vite-dev-port-8034 'cd /path/to/project && npm run dev --port 8034'
```

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

### Create a Form with Submit Action and Navigation

Source: https://github.com/remorses/termcast/blob/main/termcast/ARCHITECTURE.md

Shows how to build a form with input fields and a submit action that triggers a toast notification and navigates back upon successful submission. Uses `useNavigation`, `Form`, and `showToast`.

```typescript
function MyForm() {
  const navigation = useNavigation()
  const [name, setName] = useState('')

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            onSubmit={(values) => {
              // Process form
              showToast({
                title: 'Saved',
                style: Toast.Style.Success,
              })
              navigation.pop()
            }}
          />
          <Action title='Cancel' onAction={() => navigation.pop()} />
        </ActionPanel>
      }
    >
      <Form.TextField id='name' title='Name' value={name} onChange={setName} />
    </Form>
  )
}
```

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

### Implement ActionPanel with List Items

Source: https://context7.com/remorses/termcast/llms.txt

Demonstrates a searchable command palette using ActionPanel. Includes sections for navigation, clipboard operations, and file management.

```tsx
import { List, ActionPanel, Action, useNavigation } from 'termcast'

function SecondaryView() {
  return <Detail markdown="# Secondary View\n\nYou navigated here!" />
}

export default function ActionsDemo() {
  const { push } = useNavigation()

  return (
    <List>
      <List.Item
        title="Item with Actions"
        actions={
          <ActionPanel title="Item Actions">
            <ActionPanel.Section title="Primary">
              <Action
                title="Custom Action"
                shortcut={{ modifiers: ['cmd'], key: 'o' }}
                onAction={() => console.log('Custom action triggered')}
              />
              <Action.Push title="Navigate" target={<SecondaryView />} />
            </ActionPanel.Section>
            <ActionPanel.Section title="Clipboard">
              <Action.CopyToClipboard
                title="Copy Text"
                content="Hello from Termcast!"
                shortcut={{ modifiers: ['cmd'], key: 'c' }}
              />
              <Action.Paste title="Paste Content" content="Pasted text" />
            </ActionPanel.Section>
            <ActionPanel.Section title="Files">
              <Action.Open title="Open File" target="/path/to/file.txt" />
              <Action.ShowInFinder title="Reveal in Finder" path="/path/to/file.txt" />
              <Action.Trash title="Move to Trash" paths={['/path/to/file.txt']} />
            </ActionPanel.Section>
          </ActionPanel>
        }
      />
    </List>
  )
}
```

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

### Launching WezTerm GUI from Rust

Source: https://github.com/remorses/termcast/blob/main/termcast/docs/wezterm-fork.md

This Rust code snippet demonstrates how to launch the wezterm-gui executable with a specific configuration file argument. This is part of the wrapper layer for launching WezTerm on Windows.

```rust
Command::new("wezterm-gui.exe").arg("--config-file")
```

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

### Build Extension

Source: https://github.com/remorses/termcast/blob/main/CONTRIBUTING.md

Compile an extension for deployment using the `termcast build` command.

```bash
termcast build <path>
```

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

### Render a List with Navigation and Clipboard Actions

Source: https://github.com/remorses/termcast/blob/main/termcast/ARCHITECTURE.md

Illustrates how to create a list component where each item has associated actions for navigation, copying to clipboard, and opening URLs. Requires `useNavigation` and `List` components.

```typescript
function MyList() {
  const navigation = useNavigation()

  return (
    <List>
      {items.map((item) => (
        <List.Item
          key={item.id}
          title={item.name}
          subtitle={item.description}
          actions={
            <ActionPanel>
              <Action.Push
                title='View Details'
                target={<DetailView item={item} />}
              />
              <Action.CopyToClipboard title='Copy ID' content={item.id} />
              <Action.OpenInBrowser title='View Online' url={item.url} />
            </ActionPanel>
          }
        />
      ))}
    </List>
  )
}
```

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

### Launching WezTerm with a Custom Config File

Source: https://github.com/remorses/termcast/blob/main/termcast/docs/wezterm-fork.md

This command shows how to launch the wezterm-gui application with a specific configuration file. This approach works identically across different platforms and provides both configuration loading and instance isolation.

```bash
wezterm-gui --config-file /path/to/wezterm.lua
```

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

### Get the current GitHub repository origin URL

Source: https://github.com/remorses/termcast/blob/main/CLAUDE.md

Retrieves the URL of the remote 'origin' for the current Git repository.

```bash
git config --get remote.origin.url
```

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

### Windows MyApp.exe Launcher (Rust)

Source: https://github.com/remorses/termcast/blob/main/termcast/docs/wezterm-fork.md

This Rust program acts as a tiny compiled launcher for Windows. It hides the console window and launches WezTerm with a specific configuration file, enabling multi-app isolation. Ensure the Rust compiler and necessary build tools are set up.

```rust
#![windows_subsystem = "windows"]

fn main() {
    let dir = std::env::current_exe().unwrap()
        .parent().unwrap().to_owned();
    let config = dir.join("config").join("wezterm.lua");
    std::process::Command::new(dir.join("wezterm-gui.exe"))
        .arg("--config-file")
        .arg(&config)
        .spawn()
        .expect("failed to launch");
}
```

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

### Fetch Raycast Documentation

Source: https://github.com/remorses/termcast/blob/main/CLAUDE.md

Commands to retrieve Raycast API documentation in markdown format or view the sitemap.

```bash
curl -s https://developers.raycast.com/api-reference/user-interface/list.md
```

```bash
curl -s https://developers.raycast.com/sitemap-pages.xml
```

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

### List all active tmux sessions

Source: https://github.com/remorses/termcast/blob/main/CLAUDE.md

This command lists all currently running tmux sessions. Sessions not started by agents can be ignored.

```bash
tmux ls
```

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

### Class method binding example

Source: https://github.com/remorses/termcast/blob/main/AGENTS.md

Always bind all class methods to `this` in the constructor to ensure they function correctly in any context, such as callbacks or event handlers.

```typescript
constructor(options: Options) {
    // Initialize properties
    this.prop = options.prop

    // Bind all methods to this instance
    this.method1 = this.method1.bind(this)
    this.method2 = this.method2.bind(this)
    this.privateMethod = this.privateMethod.bind(this)
  }
```

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

### Fetch OpenTUI Documentation

Source: https://github.com/remorses/termcast/blob/main/CONTRIBUTING.md

Retrieve documentation for the OpenTUI React package, which is required for Termcast's UI.

```bash
curl -s https://raw.githubusercontent.com/sst/opentui/refs/heads/main/packages/react/README.md
```

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

### Get Current Terminal State with `tuistory`

Source: https://github.com/remorses/termcast/blob/main/SKILL.md

Captures and displays the current state of the terminal session. Use `--trim` to remove leading/trailing whitespace.

```bash
tuistory -s my-ext snapshot --trim
```

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

### Create a platform-aware download page

Source: https://github.com/remorses/termcast/blob/main/termcast/docs/wezterm-fork.md

An HTML page that fetches release assets from the GitHub API and updates download links based on the user's detected operating system.

```html
<!DOCTYPE html>
<html>
<head>
  <title>My App — Download</title>
  <style>
    body { font-family: system-ui; max-width: 600px; margin: 80px auto; text-align: center; }
    .btn { display: inline-block; padding: 16px 32px; background: #f60; color: white;
           border-radius: 8px; text-decoration: none; font-size: 18px; font-weight: 600; }
    .btn:hover { background: #e50; }
    .alt { margin-top: 24px; color: #666; font-size: 14px; }
    .alt a { color: #333; }
  </style>
</head>
<body>
  <h1>My App</h1>
  <p>A short description of what the app does.</p>
  <a id="download" class="btn" href="#">Download for your platform</a>
  <div class="alt">
    Also available for
    <a id="alt-mac" href="#">macOS</a> ·
    <a id="alt-win" href="#">Windows</a> ·
    <a id="alt-linux" href="#">Linux</a>
  </div>

  <script>
    const REPO = 'owner/my-termcast-app'
    const APP_NAME = 'MyApp'

    async function main() {
      const res = await fetch(`https://api.github.com/repos/${REPO}/releases/latest`)
      const release = await res.json()
      const assets = release.assets || []

      const urls = {
        mac: assets.find(a => a.name.includes('macos'))?.browser_download_url,
        win: assets.find(a => a.name.includes('windows'))?.browser_download_url,
        linux: assets.find(a => a.name.includes('linux'))?.browser_download_url,
      }

      // Detect platform
      const ua = navigator.userAgent.toLowerCase()
      const platform = ua.includes('mac') ? 'mac' : ua.includes('win') ? 'win' : 'linux'
      const labels = { mac: 'macOS', win: 'Windows', linux: 'Linux' }

      const btn = document.getElementById('download')
      btn.href = urls[platform] || '#'
      btn.textContent = `Download for ${labels[platform]}`

      document.getElementById('alt-mac').href = urls.mac || '#'
      document.getElementById('alt-win').href = urls.win || '#'
      document.getElementById('alt-linux').href = urls.linux || '#'
    }
    main()
  </script>
</body>
</html>
```

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

### Build and Release Termcast Extension

Source: https://github.com/remorses/termcast/blob/main/README.md

Compiles the Termcast extension for multiple platforms (macOS, Linux, Windows) and uploads them to GitHub releases. Provides an installation script URL upon completion.

```sh
termcast release
```

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

### Run Extension with `termcast dev`

Source: https://github.com/remorses/termcast/blob/main/SKILL.md

Use this command to launch your extension in development mode with hot-reloading for fast iteration.

```bash
cd my-extension
termcast dev
```

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

### Termcast App Build Options

Source: https://github.com/remorses/termcast/blob/main/termcast/CHANGELOG.md

Lists the available options for the `termcast app build` command, including `--theme`, `--font`, and `--icon`, for customizing the appearance and configuration of the standalone application.

```bash
--theme` option to bake a theme into the app
--font` option for font customization
--icon` option with fallback to built-in default icon
```

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

### React Refresh Registration Example

Source: https://github.com/remorses/termcast/blob/main/termcast/docs/hot-reload.md

Illustrates how React Refresh registers a component using a stable ID derived from the source file path. This ensures correct component swapping even after module re-imports.

```javascript
$RefreshReg$(MyCommand, "/path/to/src/my-command.tsx MyCommand")
```

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

### Implement Navigation with useNavigation

Source: https://context7.com/remorses/termcast/llms.txt

Use the useNavigation hook to manage view stacks with push, pop, and popToRoot operations.

```tsx
import { List, Detail, Action, ActionPanel, useNavigation } from 'termcast'

function ItemDetail({ item }: { item: { id: string; title: string } }) {
  const { pop, popToRoot } = useNavigation()

  return (
    <Detail
      markdown={`# ${item.title}\n\nViewing item ${item.id}`}
      actions={
        <ActionPanel>
          <Action title="Go Back" onAction={pop} />
          <Action title="Return to Root" onAction={popToRoot} />
        </ActionPanel>
      }
    />
  )
}

function SubList() {
  const { push, pop } = useNavigation()

  return (
    <List navigationTitle="Sub List">
      <List.Item
        title="Nested Item"
        actions={
          <ActionPanel>
            <Action
              title="Go Deeper"
              onAction={() => push(<Detail markdown="# Deep View" />)}
            />
            <Action title="Go Back" onAction={pop} />
          </ActionPanel>
        }
      />
    </List>
  )
}

export default function NavigationDemo() {
  const { push } = useNavigation()
  const items = [
    { id: '1', title: 'First Item' },
    { id: '2', title: 'Second Item' },
  ]

  return (
    <List navigationTitle="Navigation Demo">
      {items.map((item) => (
        <List.Item
          key={item.id}
          title={item.title}
          actions={
            <ActionPanel>
              <Action.Push title="View Details" target={<ItemDetail item={item} />} />
              <Action title="Open Sub List" onAction={() => push(<SubList />)} />
            </ActionPanel>
          }
        />
      ))}
    </List>
  )
}
```

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

### Fetch Raycast API Documentation

Source: https://github.com/remorses/termcast/blob/main/CONTRIBUTING.md

Retrieve documentation for specific Raycast APIs, such as the List component, using curl.

```bash
curl -s https://developers.raycast.com/api-reference/user-interface/list.md
```

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

### Invalid Hook Usage in React Render Props

Source: https://github.com/remorses/termcast/blob/main/PREFIX.md

React hooks like useState cannot be called inside render props or callbacks. Move hooks to the top-level of your component instead. This example shows incorrect usage.

```tsx
<Controller
  name={props.id}
  control={control}
  defaultValue={props.defaultValue || props.value || ''}
  render={({ field, fieldState, formState }) => {
    // Store selected title for display
    // ❌ INVALID: React hooks like useState cannot be called inside render props or callbacks
    // Instead, move hooks to the top-level of your component, not inside the render prop
    // The below is incorrect usage and will cause React errors
    const [selectedTitle, setSelectedTitle] = React.useState<string>('')
    const [dropdownItems, setDropdownItems] = React.useState<FormDropdownItemDescendant[]>([])

    // ...rest of render logic
    return (
      /* JSX goes here */
    )
  }}
/>
```

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

### Fetching Raycast Sitemap

Source: https://github.com/remorses/termcast/blob/main/AGENTS.md

Use this command to retrieve the sitemap of Raycast documentation pages.

```bash
curl -s https://developers.raycast.com/sitemap-pages.xml
```

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

### Compile Termcast Extension to Executable

Source: https://github.com/remorses/termcast/blob/main/README.md

Builds a standalone executable binary for the Termcast extension.

```sh
termcast compile
```

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

### Corrected Hook Usage in React Render Props

Source: https://github.com/remorses/termcast/blob/main/PREFIX.md

To resolve invalid hook usage within render props, either create a separate component for the render prop or lift the hooks to the component's scope. This example demonstrates creating a separate component.

```tsx
function MyRenderComponent({ field, fieldState, formState }) {
  const [selectedTitle, setSelectedTitle] = React.useState<string>('')
  const [dropdownItems, setDropdownItems] = React.useState<FormDropdownItemDescendant[]>([])

  // ...rest of render logic
  return (
    /* JSX goes here */
  )
}

// ...

<Controller
  name={props.id}
  control={control}
  defaultValue={props.defaultValue || props.value || ''}
  render={(args) => <MyRenderComponent {...args} />}
 />
```

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

### Fetch repositories with opensrc

Source: https://github.com/remorses/termcast/blob/main/CLAUDE.md

Use the opensrc command to download source code from GitHub. It supports full URLs, specific branches, or tags.

```bash
opensrc https://github.com/colinhacks/zod
```

```bash
opensrc owner/repo@v1.0.0
```

```bash
opensrc owner/repo#main
```

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

### WezTerm Lua Configuration

Source: https://github.com/remorses/termcast/blob/main/termcast/docs/wezterm-fork.md

This Lua configuration file customizes WezTerm for Termcast. It sets the default program, disables UI chrome, enables Kitty protocols for graphics and keyboard, configures rendering for crispness, and defines custom key bindings. Ensure WezTerm is installed and this file is placed in the correct configuration directory.

```lua
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Resolve the termcast binary relative to config file
local config_dir = wezterm.config_dir
local sep = package.config:sub(1, 1)
local termcast_bin
if sep == '\\'
  then
  termcast_bin = config_dir .. '\\..\\my-app.exe'
else
  termcast_bin = config_dir .. '/my-app'
end

config.default_prog = { termcast_bin }

-- Strip all chrome
config.enable_tab_bar = false
config.window_decorations = 'RESIZE'
config.window_padding = { left = 0, right = 0, top = 0, bottom = 0 }

-- Snap resize to cell grid (no sub-character pixel gaps)
config.use_resize_increments = true

-- Kitty protocols
config.enable_kitty_graphics = true   -- images (default on)
config.enable_kitty_keyboard = true   -- progressive keyboard enhancement

-- Crisp rendering (macOS Metal backend)
config.front_end = 'WebGpu'
config.webgpu_power_preference = 'HighPerformance'
config.max_fps = 120
config.freetype_render_target = 'HorizontalLcd'
config.freetype_load_target = 'Light'

-- Termcast controls all key bindings
config.disable_default_key_bindings = true
config.keys = {
  -- Forward cmd+c/v to terminal via kitty keyboard protocol
  { key = 'c', mods = 'SUPER', action = wezterm.action.SendKey { key = 'c', mods = 'SUPER' } },
  { key = 'v', mods = 'SUPER', action = wezterm.action.SendKey { key = 'v', mods = 'SUPER' } },
  { key = 'q', mods = 'SUPER', action = wezterm.action.QuitApplication },
}

-- Drag-and-drop: POSIX-escape file paths pasted into PTY
config.quote_dropped_files = 'Posix'

return config

```

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

### Render TUI with renderWithProviders

Source: https://context7.com/remorses/termcast/llms.txt

Initialize a Termcast application programmatically as a library without the CLI.

```tsx
import { renderWithProviders, List, Action, ActionPanel } from 'termcast'

function MyApp() {
  return (
    <List navigationTitle="My Terminal App">
      <List.Item
        title="Hello World"
        subtitle="Built with Termcast"
        actions={
          <ActionPanel>
            <Action title="Greet" onAction={() => console.log('Hello!')} />
            <Action title="Exit" onAction={() => process.exit(0)} />
          </ActionPanel>
        }
      />
    </List>
  )
}

// Start the application
await renderWithProviders(<MyApp />, {
  extensionName: 'my-app', // Used for storage paths
  // Optional: extensionPath for custom storage location
  // Optional: packageJson for preferences and metadata
})
```

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

### Download and Test Synonyms Extension

Source: https://github.com/remorses/termcast/blob/main/termcast/TESTING_RAYCAST_EXTENSIONS.md

Commands to download the synonyms extension and then run its associated end-to-end tests with snapshot updates.

```bash
# Download
bun run src/cli.tsx raycast download synonyms -o extensions

# Test
bun e2e src/examples/synonyms.vitest.tsx -u
```

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

### Implement Custom Component with Keyboard and Dialog Actions

Source: https://github.com/remorses/termcast/blob/main/termcast/ARCHITECTURE.md

Demonstrates how to create a custom component that responds to keyboard events, specifically Ctrl+K to open a dialog with actions. Utilizes `useDialog` and `useIsInFocus` hooks.

```typescript
function CustomView({ data }) {
  const dialog = useDialog()
  const inFocus = useIsInFocus()

  const actions = (
    <ActionPanel>
      <Action title='Process' onAction={() => processData(data)} />
      <Action.CopyToClipboard content={data.text} />
    </ActionPanel>
  )

  useKeyboard((evt) => {
    if (!inFocus) return

    if (evt.name === 'k' && evt.ctrl) {
      dialog.push(actions, 'bottom-right')
    }
  })

  return <box>{/* Your component UI */}</box>
}
```

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

### Linux AppImage AppRun Script

Source: https://github.com/remorses/termcast/blob/main/termcast/docs/wezterm-fork.md

This bash script is the entry point for the Linux AppImage. It determines the directory of the AppImage and executes the wezterm-gui binary with the specified configuration file.

```bash
#!/bin/bash
DIR="$(dirname "$(readlink -f "$0")")"
exec "$DIR/wezterm-gui" --config-file "$DIR/config/wezterm.lua"
```

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

### Read Repository Source Code

Source: https://github.com/remorses/termcast/blob/main/CLAUDE.md

Use the opensrc tool to view source code for packages or repositories.

```bash
opensrc zod # npm package name

# Using github: prefix
opensrc github:owner/repo

# Using owner/repo shorthand
opensrc facebook/react
```

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

### Launch Extension in Managed Terminal with `tuistory`

Source: https://github.com/remorses/termcast/blob/main/SKILL.md

Launches your extension within a managed terminal session for interactive testing. Specify columns and rows for the terminal size.

```bash
tuistory launch "termcast dev" -s my-ext --cols 120 --rows 36
```

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

### Run Tests with Snapshot Update

Source: https://github.com/remorses/termcast/blob/main/termcast/TESTING_RAYCAST_EXTENSIONS.md

Execute tests using Bun and update inline snapshots. This command runs all tests and fills in `toMatchInlineSnapshot()` calls with actual output.

```bash
bun e2e src/examples/<extension-name>.vitest.tsx -u
```

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

### Set OAuth Environment Variables

Source: https://github.com/remorses/termcast/blob/main/PREFIX.md

Required environment variables for deploying new OAuth provider credentials.

```bash
NEWPROVIDER_OAUTH_CLIENT_ID=...
NEWPROVIDER_OAUTH_CLIENT_SECRET=...
```

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

### Develop Local Extension

Source: https://github.com/remorses/termcast/blob/main/CONTRIBUTING.md

Run a local extension in development mode using the `termcast dev` command.

```bash
termcast dev <path>
```

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

### Run Extension in Dev Mode

Source: https://github.com/remorses/termcast/blob/main/termcast/TESTING_RAYCAST_EXTENSIONS.md

Launch an extension in development mode using `termcast dev` to test it manually. This command will show a command list, preferences form, or the main view depending on the extension's structure.

```bash
cd termcast
bun run src/cli.tsx dev extensions/<extension-name>
```

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

### Configure macOS Info.plist

Source: https://github.com/remorses/termcast/blob/main/termcast/docs/wezterm-fork.md

The property list file defining application metadata and execution settings for the macOS bundle.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleExecutable</key>
  <string>launch</string>
  <key>CFBundleIdentifier</key>
  <string>com.author.myapp</string>
  <key>CFBundleName</key>
  <string>My App</string>
  <key>CFBundleDisplayName</key>
  <string>My App</string>
  <key>CFBundleIconFile</key>
  <string>app.icns</string>
  <key>CFBundlePackageType</key>
  <string>APPL</string>
  <key>CFBundleShortVersionString</key>
  <string>1.0.0</string>
  <key>NSHighResolutionCapable</key>
  <true/>
  <key>NSSupportsAutomaticGraphicsSwitching</key>
  <true/>
  <key>NSRequiresAquaSystemAppearance</key>
  <string>NO</string>
</dict>
</plist>
```

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

### View the Linux app build bundle structure

Source: https://github.com/remorses/termcast/blob/main/termcast/CHANGELOG.md

The directory structure produced by the termcast app build command when targeting Linux, including the bash launcher and WezTerm runtime.

```text
MyApp/
  MyApp              ← bash launcher
  runtime/
    wezterm-gui      ← WezTerm binary
    myapp            ← compiled extension
    config/
      wezterm.lua
  share/
    applications/myapp.desktop   ← freedesktop .desktop entry
    icons/myapp.png
```

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

### Open Source Code with `opensrc` CLI

Source: https://github.com/remorses/termcast/blob/main/AGENTS.md

Use the `opensrc` command-line tool to quickly open source code for npm packages or GitHub repositories. Specify packages by name or use the `github:` prefix for owner/repo.

```bash
opensrc zod # npm package name
```

```bash
# Using github: prefix
opensrc github:owner/repo
```

```bash
# Using owner/repo shorthand
opensrc facebook/react
```

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

### Build Standalone Termcast App

Source: https://github.com/remorses/termcast/blob/main/termcast/docs/wezterm-fork.md

Use this command to package a termcast extension into a standalone desktop app. It compiles the extension, downloads WezTerm, generates configuration, and assembles a distributable zip file.

```bash
termcast app build \
  --name "My App" \
  --icon ./icon.png \
  --bundle-id com.author.myapp
```

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

### Build and Release Termcast Extensions

Source: https://context7.com/remorses/termcast/llms.txt

Commands to compile extensions into standalone binaries for distribution across multiple platforms.

```bash
# Build a standalone executable
termcast compile

# Build and publish to GitHub releases for all platforms
termcast release
# Creates binaries for: macOS (arm64, x64), Linux (arm64, x64), Windows
# Outputs install script URL: curl -sf https://termcast.app/owner/repo/install | bash
```

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

### Fetch Additional Source Code

Source: https://github.com/remorses/termcast/blob/main/CLAUDE.md

Use the `npx opensrc` command to fetch source code for npm packages, Python packages, Rust crates, or GitHub repositories. This is useful for understanding internal implementation details.

```bash
npx opensrc <package>           # npm package (e.g., npx opensrc zod)
npx opensrc pypi:<package>      # Python package (e.g., npx opensrc pypi:requests)
npx opensrc crates:<package>    # Rust crate (e.g., npx opensrc crates:serde)
npx opensrc <owner>/<repo>      # GitHub repo (e.g., npx opensrc vercel/ai)
```