Docs — Zippy

INSTALLATION

Zippy is a Go application. You can install it directly using the go install command.

go install github.com/user/zippy@latest

Make sure you have Go 1.21 or later installed. After installation, run zippy from your terminal to start.

Prerequisites

Go 1.21 or later
A MiniMax API key (get one at platform.minimax.io)
A terminal emulator (works best with 256-color support)

CONFIGURATION

On first run, Zippy will prompt you for your MiniMax API key. Paste your API key and press Enter to save.

Your configuration is stored at:

~/.config/zippy/config.json

Example config:

{
  "api_key": "your-api-key-here",
  "nsfw": false
}

NSFW Mode

By default, Zippy uses SFW (safe-for-work) spinner verbs like "Generating" and "Processing". You can enable NSFW mode to unlock more... colorful loading messages.

Toggle NSFW mode anytime by pressing ctrl+s to open the settings panel.

USAGE

Run zippy in your terminal to start chatting.

$ zippy
~ zippy TUI agent ~
let's get you set up!

paste your MiniMax API key below.
get one at https://platform.minimax.io

>

Basic Chat

Type your message and press Enter to send. The agent will respond with its adorable loading animation while processing your request.

~ zippy TUI agent ~
minimax-powered

you: explain what a goroutine is

agent: A goroutine is a lightweight
thread managed by the Go runtime.
They're cheap to create and let you
run functions concurrently.

> _

KEYBOARD SHORTCUTS

Enter — Send message
Backspace — Delete character
Ctrl+S — Open settings panel
Ctrl+C — Quit application
Paste (Ctrl+V or Cmd+V) — Paste text into input

CONFIG FILE

The config file uses JSON format and is located at ~/.config/zippy/config.json.

Options

api_key — Your MiniMax API key (required)
nsfw — Boolean to enable NSFW spinner verbs (default: false)

SPINNER VERBS

While waiting for the AI to respond, Zippy displays a spinning animation with contextual verbs.

SFW Verbs (default)

["Generating", "Processing", "Thinking", "Computing", "Analyzing",
 "Calculating", "Reasoning", "Fetching", "Loading", "Working"]

NSFW Verbs

["Destroying", "Corrupting", "Breaking", "Obliterating",
 "Demolishing", "Wrecking", "Shattering", "Crushing"]

Toggle between modes using the settings panel (ctrl+s).

ARCHITECTURE

Zippy is built on the Bubble Tea framework, which implements the Elm Architecture in Go. Read the full architecture document for deep dive details.

View Architecture Doc →

Core Components

model — Root model holding all sub-models
onboardingModel — First-run API key setup
chatModel — Main chat interaction
settingsModel — Settings panel overlay

GETTING STARTED