Skip to content

PyModel/pythinker-code / .agents/skills/opentui

opentui

Verified

Build terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.

FileKindSize
SKILL.mdskill md5.4 KB
docs/bindings/react.mdxmarkdown11.0 KB
docs/bindings/solid.mdxmarkdown15.0 KB
docs/components/ascii-font.mdxmarkdown4.3 KB
docs/components/box.mdxmarkdown5.5 KB
docs/components/code.mdxmarkdown10.2 KB
docs/components/diff.mdxmarkdown4.2 KB
docs/components/frame-buffer.mdxmarkdown6.7 KB
docs/components/input.mdxmarkdown5.6 KB
docs/components/line-number.mdxmarkdown4.0 KB
docs/components/markdown.mdxmarkdown10.6 KB
docs/components/qr-code.mdxmarkdown4.3 KB
docs/components/scrollbar.mdxmarkdown2.3 KB
docs/components/scrollbox.mdxmarkdown7.5 KB
docs/components/select.mdxmarkdown6.2 KB
docs/components/slider.mdxmarkdown2.2 KB
docs/components/tab-select.mdxmarkdown6.0 KB
docs/components/text-table.mdxmarkdown9.0 KB
docs/components/text.mdxmarkdown4.5 KB
docs/components/textarea.mdxmarkdown7.7 KB
docs/components/time-to-first-draw.mdxmarkdown4.7 KB
docs/core-concepts/audio.mdxmarkdown32.2 KB
docs/core-concepts/colors.mdxmarkdown7.8 KB
docs/core-concepts/console.mdxmarkdown3.2 KB
docs/core-concepts/constructs.mdxmarkdown5.8 KB
docs/core-concepts/keyboard.mdxmarkdown10.4 KB
docs/core-concepts/layout.mdxmarkdown4.0 KB
docs/core-concepts/lifecycle.mdxmarkdown4.4 KB
docs/core-concepts/notifications.mdxmarkdown2.3 KB
docs/core-concepts/renderables-vs-constructs.mdxmarkdown4.5 KB
docs/core-concepts/renderables.mdxmarkdown9.9 KB
docs/core-concepts/renderer.mdxmarkdown30.9 KB
docs/core-concepts/testing.mdxmarkdown14.6 KB
docs/getting-started.mdxmarkdown3.2 KB
docs/keymap/addons.mdxmarkdown15.6 KB
docs/keymap/core.mdxmarkdown38.9 KB
docs/keymap/custom-addons.mdxmarkdown26.7 KB
docs/keymap/hosts.mdxmarkdown15.7 KB
docs/keymap/overview.mdxmarkdown18.1 KB
docs/keymap/react.mdxmarkdown4.9 KB
docs/keymap/solid.mdxmarkdown5.1 KB
docs/plugins/core.mdxmarkdown12.6 KB
docs/plugins/react.mdxmarkdown6.5 KB
docs/plugins/slots.mdxmarkdown12.7 KB
docs/plugins/solid.mdxmarkdown7.0 KB
docs/reference/color-matrix.mdxmarkdown3.8 KB
docs/reference/env-vars.mdxmarkdown6.5 KB
docs/reference/native-span-feed.mdxmarkdown6.0 KB
docs/reference/package-entrypoints.mdxmarkdown9.6 KB
docs/reference/qr-encoder.mdxmarkdown12.3 KB
docs/reference/ssh.mdxmarkdown14.8 KB
docs/reference/standalone-executables.mdxmarkdown7.1 KB
docs/reference/three.mdxmarkdown14.8 KB
docs/reference/tree-sitter.mdxmarkdown4.6 KB

docs/core-concepts/lifecycle.mdx

View on GitHub
---
title: Lifecycle and cleanup
description: Managing renderer lifecycle and terminal cleanup
order: 10
---

# Lifecycle and cleanup

OpenTUI gives you control over terminal cleanup. Call `renderer.destroy()` when you shut down. It restores the terminal to its original state, and it frees resources.

## Why you must handle cleanup

OpenTUI does not automatically clean up on `process.exit` or unhandled errors. This design gives you more control over shutdown behavior:

- You may want to handle errors and keep running
- You may use effect systems, like Effect.ts, with their own shutdown handling
- You may need custom cleanup order or additional shutdown logic

## Use `renderer.destroy()`

Call `destroy()` when your app exits:

```typescript
import { createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer()

// ... your application code ...

// Clean shutdown
renderer.destroy()
```

For reliable cleanup, keep renderer teardown in the same control flow as your app startup:

```typescript
import { createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer()

try {
  // ... your application code ...
} finally {
  renderer.destroy()
}
```

## Signal handling

OpenTUI listens for common exit signals and calls `destroy()` when it receives them. By default, it handles these signals:

| Signal     | Description              |
| ---------- | ------------------------ |
| `SIGINT`   | Ctrl+C                   |
| `SIGTERM`  | Termination signal       |
| `SIGQUIT`  | Ctrl+\                   |
| `SIGABRT`  | Abort signal             |
| `SIGHUP`   | Hangup (terminal closed) |
| `SIGBREAK` | Ctrl+Break on Windows    |
| `SIGPIPE`  | Broken pipe              |
| `SIGBUS`   | Bus error                |

You can customize which signals trigger cleanup:

```typescript
// Only handle SIGINT and SIGTERM
const renderer = await createCliRenderer({
  exitSignals: ["SIGINT", "SIGTERM"],
})

// Disable all signal-based cleanup (handle it yourself)
const renderer = await createCliRenderer({
  exitSignals: [],
})
```

## Ctrl+C behavior

By default, Ctrl+C calls `destroy()`. If you want to handle Ctrl+C yourself, disable the internal handler and remove `SIGINT` from `exitSignals`:

```typescript
const renderer = await createCliRenderer({
  exitOnCtrlC: false,
  exitSignals: ["SIGTERM", "SIGQUIT", "SIGABRT", "SIGHUP", "SIGBREAK", "SIGPIPE", "SIGBUS"],
})

renderer.keyInput.on("keypress", (key) => {
  if (key.ctrl && key.name === "c") {
    // Custom Ctrl+C handling
    console.log("Ctrl+C pressed, but not exiting")
  }
})
```

## Destroy callback

Run custom logic when the renderer is destroyed:

```typescript
const renderer = await createCliRenderer({
  onDestroy: () => {
    console.log("Renderer destroyed, performing additional cleanup...")
  },
})
```

## What `destroy()` cleans up

The `destroy()` method cleans up these resources:

- Removes the signal and process listeners that OpenTUI adds
- Clears timers and render loops
- Destroys all renderables in the tree
- Restores stdin raw mode
- Resets terminal state (cursor, alternate screen, etc.)
- Flushes pending split-footer captured output
- Frees native resources

## Custom stream sessions

For socket, SSH, or pty sessions, give each connection its own renderer. Destroy it before closing the transport:

```typescript
import { createCliRenderer, type CliRenderer } from "@opentui/core"

interface TerminalSession {
  renderer: CliRenderer
  closeTransport: () => void
}

async function startSession(
  stdin: NodeJS.ReadStream,
  stdout: NodeJS.WriteStream,
  closeTransport: () => void,
): Promise<TerminalSession> {
  const renderer = await createCliRenderer({
    stdin,
    stdout,
    width: stdout.columns || 80,
    height: stdout.rows || 24,
    exitOnCtrlC: false,
    exitSignals: [],
  })

  return { renderer, closeTransport }
}

async function closeSession(session: TerminalSession): Promise<void> {
  session.renderer.destroy()
  await new Promise<void>((resolve) => queueMicrotask(resolve))
  session.closeTransport()
}
```

Use `exitOnCtrlC: false` and `exitSignals: []` when a long-lived server process owns many renderer sessions. A `stdin` or `stdout` stream cannot be shared by active renderers; `destroy()` releases it.

## Troubleshooting

If your terminal stays in a broken state after a crash:

1. Run `reset` in your terminal to restore it
2. Add `uncaughtException` and `unhandledRejection` handlers to your app
3. Make sure you call `renderer.destroy()` in all exit paths
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall