https://github.com/skwid138/opencode-tui
Configurable TUI plugin for OpenCode — custom ASCII logo with dual-color theming and randomized prompt placeholders
https://github.com/skwid138/opencode-tui
cli-customization npm-package opencode opencode-plugin solid-js terminal-ui tui typescript
Last synced: 29 days ago
JSON representation
Configurable TUI plugin for OpenCode — custom ASCII logo with dual-color theming and randomized prompt placeholders
- Host: GitHub
- URL: https://github.com/skwid138/opencode-tui
- Owner: skwid138
- License: mit
- Created: 2026-05-24T16:31:28.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-24T21:55:11.000Z (about 2 months ago)
- Last Synced: 2026-05-24T23:29:16.346Z (about 2 months ago)
- Topics: cli-customization, npm-package, opencode, opencode-plugin, solid-js, terminal-ui, tui, typescript
- Language: TypeScript
- Size: 94.7 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @skwid138/opencode-tui
Lipstick for your OpenCode TUI.
[](https://npmjs.com/package/@skwid138/opencode-tui) [](https://github.com/skwid138/opencode-tui/actions/workflows/ci.yml) [](LICENSE)
`@skwid138/opencode-tui` is a configurable OpenCode TUI plugin that replaces the home screen logo and prompt placeholders with friendlier defaults. Use it as-is, customize ASCII logo rows with per-segment inline colors, swap prompt suggestions for normal and shell modes, or disable either section independently while invalid config safely falls back to defaults.
## Quick Start
Install the package:
```sh
npm install @skwid138/opencode-tui
```
Add the TUI entry to your OpenCode plugin configuration using the package's TUI export:
```jsonc
{
"plugin": ["@skwid138/opencode-tui/tui"]
}
```
## Features
- Custom ASCII logos made from rows of inline text segments.
- Per-segment logo colors using 3- or 6-digit hex values.
- Prompt placeholder customization for normal and shell modes.
- Disable logo or prompt customization independently.
- Graceful fallback to defaults when config is invalid.
- Companion Logo Builder web app for generating `logo.rows` config.
## Usage
### Zero config
Use the default JustVibes logo and default prompt placeholders:
```jsonc
{
"plugin": ["@skwid138/opencode-tui/tui"]
}
```
Plugin options are registered as a tuple: `["@skwid138/opencode-tui/tui", { config }]`.
### Disable sections
Disable only the logo:
```jsonc
{
"plugin": [
["@skwid138/opencode-tui/tui", { "logo": false }]
]
}
```
Disable only the prompt override:
```jsonc
{
"plugin": [
["@skwid138/opencode-tui/tui", { "prompt": false }]
]
}
```
Disable both sections:
```jsonc
{
"plugin": [
["@skwid138/opencode-tui/tui", { "logo": false, "prompt": false }]
]
}
```
### Custom prompts
```jsonc
{
"plugin": [
[
"@skwid138/opencode-tui/tui",
{
"prompt": {
"placeholders": {
"normal": [
"Build a dashboard for my team",
"Refactor this component",
"Help me debug this error"
],
"shell": [
"List files by size",
"Show current git status"
]
}
}
}
]
]
}
```
### Custom logo rows
Each row contains literal pre-rendered ASCII text segments. Segment `color` is an inline 3- or 6-digit hex string including `#`.
```jsonc
{
"plugin": [
[
"@skwid138/opencode-tui/tui",
{
"logo": {
"rows": [
{
"segments": [
{ "text": "Open", "color": "#5DBDB3" },
{ "text": "Code", "color": "#F8B4C4" }
]
}
]
}
}
]
]
}
```
## Options reference
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `logo` | `false \| LogoConfig` | default logo | Set to `false` to leave `home_logo` untouched. |
| `logo.rows` | `Array<{ segments: Array<{ text: string; color: string }> }>` | JustVibes ASCII art | Logo rows rendered as horizontal text segments. Segment colors must match `#RGB` or `#RRGGBB`. Empty arrays fall back to defaults. |
| `prompt` | `false \| PromptConfig` | default prompt | Set to `false` to leave `home_prompt` untouched. |
| `prompt.placeholders.normal` | `string[]` | 11 default ideas | Suggestions for normal prompt mode. Empty arrays fall back to defaults. |
| `prompt.placeholders.shell` | `string[]` | 3 default shell ideas | Suggestions for shell prompt mode. Empty arrays fall back to defaults. |
Invalid sections are isolated: a bad `logo` config falls back to the default logo without breaking prompt customization, and a bad `prompt` config falls back without breaking the logo. Validation never throws; warnings are logged and surfaced through the OpenCode toast API when available.
## Logo Builder
Use the companion Logo Builder app to generate custom `logo.rows` config: . The companion repo lives at .
## Development
Install dependencies:
```sh
npm install
```
Run tests:
```sh
npm test
```
Run tests with coverage:
```sh
npm run test:coverage
```
Type-check:
```sh
npm run typecheck
```
Build the package:
```sh
npm run build
```
The build emits ESM artifacts and declaration files into `dist/`.
### Commit messages
This repo uses [Conventional Commits](https://www.conventionalcommits.org/). A local
[husky](https://typicode.github.io/husky/) hook runs
[commitlint](https://commitlint.js.org/) on every commit, and PR titles are validated
by GitHub Actions (`.github/workflows/pr-title.yml`) since this repo squash-merges
with the PR title as the commit subject.
Allowed types: `feat`, `fix`, `perf`, `refactor` (patch), `docs`, `chore`, `ci`,
`style`, `test`, `build`, `revert`.
Notes:
- Use `git commit --no-verify` to bypass the hook in unusual cases (e.g. WIP commits
you'll squash later).
- A `BREAKING CHANGE:` footer in the commit body triggers a major release regardless
of the type prefix — use deliberately.
- The conventional prefix governs the release type, but the human is responsible for
matching prefix to actual change (a `feat:` whose diff is a README typo will still
publish a minor release).
## License
MIT © [Spencer Miller](https://github.com/skwid138)