ohai-mcp
An MCP server that displays notification popups via Quickshell on Linux.
Installation
npm install
npm run build
Tools
ohai
Display a notification popup.
| Parameter | Type | Required | Description |
|---|---|---|---|
message | string | yes | Message body |
title | string | no | Popup title (defaults to message) |
severity | info | warn | crit | no | Accent color (default: info) |
color | string | no | Custom accent color (CSS/hex; overrides severity) |
timeoutSeconds | number | no | Auto-hide delay (default: 8; 0 = persistent) |
pattern | string | no | Background pattern ID or path |
image | string | no | Image ID or path (default: ghost) |
workspace | string | no | Workspace to switch to on backtick |
app | string | no | App/window to focus on backtick |
transition | glow | ghost | ripple | none | no | Entry transition effect (default: glow) |
ohai_status
Check if Quickshell is running with the ohai IPC target registered.
Transition Effects
| Effect | Description |
|---|---|
glow | Soft blur glow pulse (default) |
ghost | Expanding/fading copies of actual notification content |
ripple | Border ripples emanating outward |
none | No transition effect |
Set a default transition via environment variable:
export OHAI_TRANSITION=ghost
Quickshell Setup
- Start the popup daemon:
qs -p /path/to/ohai-mcp/ohai/shell.qml
- Verify the IPC target is registered:
qs ipc show
# Should list: target ohai
- Test manually:
qs ipc call ohai notify "Hello" "Test message" "info" 5 "" "" "" "" "" "glow"
- Controls while popup is visible:
Escape- hide popup- Backtick (`) - switch to workspace or focus app (if configured), then hide
Testing with ohai-test
A CLI helper for testing notification appearance:
bin/ohai-test [preset] # Run a preset
bin/ohai-test custom [options] # Custom notification
Presets:
| Preset | Description |
|---|---|
info | Basic info notification (default) |
warn | Warning notification |
crit | Critical notification |
long | Long text (test layout) |
short | Minimal notification |
claude | Claude-themed |
openai | OpenAI-themed |
grid | Grid pattern background |
stripes | Stripes pattern background |
waves | Waves pattern background |
glow | Test glow transition effect |
ghost | Test ghost echo transition effect |
ripple | Test ripple transition effect |
all | Cycle through all presets |
Custom options:
bin/ohai-test custom \
-t "Title" \
-b "Body text" \
-s warn \
-i claude \
-p grid-01 \
-d 10 \
-c "#ff00ff" \
-x ghost
| Option | Description |
|---|---|
-t, --title | Title text |
-b, --body | Body text |
-s, --severity | info | warn | crit |
-i, --image | Image ID or path |
-p, --pattern | Pattern ID or path |
-d, --duration | Timeout in seconds |
-c, --color | Custom accent color (hex) |
-w, --workspace | Workspace to switch on backtick |
-a, --app | App to focus on backtick |
-x, --transition | glow | ghost | ripple | none |
Bundled Assets
Patterns (background overlays):
waves-01,grid-01,stripes-01,sunset-01
Images (left panel):
ghost(default),claude,openai
Use an absolute path for custom assets.
Integration
Use environment variables to configure defaults per client.
Claude Code
~/.claude.json:
{
"mcpServers": {
"ohai": {
"type": "stdio",
"command": "node",
"args": ["/path/to/ohai-mcp/bin/ohai-mcp"],
"env": {
"OHAI_DEFAULT_IMAGE": "claude",
"OHAI_TRANSITION": "glow"
}
}
}
}
Cursor
Add to MCP settings:
{
"mcpServers": {
"ohai": {
"command": "node",
"args": ["/path/to/ohai-mcp/bin/ohai-mcp"],
"env": {
"OHAI_DEFAULT_IMAGE": "claude",
"OHAI_TRANSITION": "ghost"
}
}
}
}
codex-cli
~/.codex/config.toml:
[mcp_servers.ohai]
command = "node"
args = ["/path/to/ohai-mcp/bin/ohai-mcp"]
[mcp_servers.ohai.env]
OHAI_DEFAULT_IMAGE = "openai"
OHAI_TRANSITION = "glow"
Auto-launch (Hyprland)
exec-once = qs -p /path/to/ohai-mcp/ohai/shell.qml
Environment Variables
| Variable | Description |
|---|---|
OHAI_DEFAULT_IMAGE | Default image when image param is not specified (e.g., claude, openai, ghost) |
OHAI_TRANSITION | Default transition effect (e.g., glow, ghost, ripple, none) |
Architecture
┌─────────────┐ qs ipc call ┌─────────────────┐
│ MCP Client │ ──────────────────▶ │ Quickshell │
│ (Claude) │ │ (shell.qml) │
└─────────────┘ └─────────────────┘
│ │
│ │
▼ ▼
┌─────────────┐ ┌─────────────────┐
│ ohai-mcp │ │ IpcHandler │
│ (Node.js) │ │ target: "ohai" │
└─────────────┘ └─────────────────┘
The MCP server communicates with Quickshell via its built-in IPC mechanism (qs ipc call), which uses a Unix socket for instant, reliable delivery.
Development
npm run dev # Watch mode
npm run build # Build
npm run lint # Lint
npm run format # Format
Requirements
- Linux with Quickshell
- Node.js 18+