promptx

README

PromptX

AI-Powered Terminal Assistant — Ask, Generate, Debug.

English | 简体中文

---

PromptX brings AI superpowers directly into your terminal. Ask questions, generate shell commands, debug errors, and chat with AI models — without leaving the command line.

• Single binary — no Python, no Node.js, no Docker. Just download and run.
• Multi-model — OpenAI, Anthropic, Ollama, OpenRouter, Groq, and any OpenAI-compatible API.
• Beautiful TUI — interactive chat mode with markdown rendering and syntax highlighting.
• Privacy-first — API keys never leave your machine. Use local models for 100% offline use.
• Shell integration — pipe errors directly: command 2>&1 | px ask "fix this"

Quick Start

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/luoowei/promptx/main/install.sh | bash

# Homebrew
brew install luoowei/tap/promptx

# Go
go install github.com/luoowei/promptx/cmd/px@latest

# Windows
iwr https://raw.githubusercontent.com/luoowei/promptx/main/install.ps1 | iex

Set your API key and start:

export OPENAI_API_KEY="sk-..."     # or ANTHROPIC_API_KEY
px ask "how do I find the largest files in a directory?"

Usage

Interactive Chat Mode

px
# Opens beautiful TUI — chat with AI in your terminal

One-Shot Questions

px ask "explain this regex: ^(?=.*[A-Z])(?=.*[a-z])(?=.*\d).{8,}$"
px ask "what's the git command to undo the last commit but keep changes?"

Shell Command Generation

px sh "find all .log files modified in the last 24 hours and compress them"
px sh "create a new user with sudo privileges on ubuntu"

Debug Errors

# Pipe errors directly
make build 2>&1 | px ask "what's wrong and how do I fix it?"

# Or paste the error
px ask "what causes 'bind: address already in use' and how to fix it?"

Configuration

px config show                          # View current config
px config set-provider anthropic        # Switch to Claude
px config set-key openai sk-...         # Store API key
px --provider ollama --model llama3.2   # Use local Ollama model

Supported Providers

Provider	Model Examples	Setup
OpenAI	gpt-4o, gpt-4.1	export OPENAI_API_KEY=sk-...
Anthropic	claude-opus-4-8, claude-sonnet-4-6	export ANTHROPIC_API_KEY=sk-ant-...
Ollama	llama3.2, mistral, qwen	ollama pull llama3.2 (no key needed)
OpenRouter	250+ models	export OPENROUTER_API_KEY=...
Groq	llama-3.3-70b	export GROQ_API_KEY=...
Any OpenAI-compatible	Custom endpoint	px config set-key custom <key>

How It Works

  Terminal     PromptX CLI      AI API
  (You)   -->  (Go Binary)  --> (OpenAI/
                |               Anthropic/
                v               Ollama)
              Response <--  Backend

PromptX is a statically-compiled Go binary that:

1. Reads your input from CLI args, pipes, or interactive TUI
2. Sends the request to your configured AI provider
3. Streams the response back with markdown rendering

Zero dependencies at runtime. No Python venv. No npm install. No Docker pull.

Why PromptX?

	PromptX	LLM CLI wrappers	Web Chat UIs
Single binary	Yes	No (Python/Node)	No (Browser only)
Pipe support	Yes	Partial	No
Shell integration	Yes	Partial	No
Offline (local models)	Yes	Yes	No
Multi-provider	Yes	Partial	Yes
TUI mode	Yes	Yes	No
Fast startup	<50ms	200-2000ms	2-5s
Binary size	~15MB	50-500MB+	N/A

Build from Source

# Requires Go 1.22+
git clone https://github.com/luoowei/promptx.git
cd promptx
go build -o px ./cmd/px
./px ask "hello world"

Project Structure

promptx/
├── cmd/px/main.go          # Entry point
├── internal/
│   ├── ai/                 # AI provider clients
│   │   ├── client.go       # Client interface + factory
│   │   ├── openai.go       # OpenAI-compatible client
│   │   └── anthropic.go    # Anthropic client
│   ├── cli/root.go         # Cobra CLI commands
│   ├── config/config.go    # Configuration management
│   ├── shell/handler.go    # Shell command generation
│   └── tui/
│       ├── tui.go          # Bubble Tea UI model
│       └── renderer.go     # Markdown renderer
├── docs/                   # Landing page (GitHub Pages)
└── install.sh              # One-line installer

Roadmap

• Streaming responses in TUI mode
• Shell auto-completion scripts (bash, zsh, fish, powershell)
• Session history with search
• Custom system prompts
• MCP server integration
• Plugin system for additional providers
• Windows Terminal theming

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT © PromptX Contributors — see LICENSE

---

Star this repo if you find it useful!
_{Built with Go, Bubble Tea, and love for the terminal}