PyModel/pythinker-code / .agents/skills/opentui
opentui
VerifiedBuild terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |