Tux-GPT: A Command-Line AI Assistant Built for Your Terminal

Fábio Berbert de Paula — Wed, 05 Nov 2025 02:44:46 +0000

If you love living inside the terminal but still want the reach of GPT models at your fingertips, let me introduce the latest release of Tux-GPT. It’s a command-line assistant (not a persistent background agent) that gives you conversational help, code guidance, and shell-ready automations without breaking your flow.

If you ask me, I’d say this is like a lite version of the Codex client.

Why Tux-GPT?

Terminal-native experience: prompts, responses, and formatting stay inside your shell (rendered with rich).
Context-aware conversations: history and preferences live in ~/.config/tux-gpt/, so the CLI remembers your last 20 exchanges.
System-aware commands: at startup, Tux-GPT inspects the host OS (distro, architecture, version) so suggestions match your environment.
Flexible interaction modes: free-form chat, single-shot questions, machine-readable JSON, or even “please craft & run this shell command”.

Installation

Most platforms:

pip install tux-gpt

Recent Debian/Ubuntu releases route pip to the system Python, so use pipx to keep your global environment clean:

pipx install tux-gpt

From source:

git clone https://github.com/fberbert/tux-gpt.git
cd tux-gpt
pip install -r requirements.txt
pip install .

Just set your OpenAI key (OPENAI_API_KEY), and you're all set to go! For more detailed guidance, feel free to visit our GitHub repository.

Getting Started

Interactive session (multi-line input supported):

tux-gpt

Press Ctrl+j to send (Enter adds a new line).
Type Ctrl+c or Ctrl+d to quit.
Conversation history resumes automatically next time.

Single-shot question:

tux-gpt -q "Summarize the latest Kubernetes news"

JSON-ready response (great for scripts):

tux-gpt --json -q "What are three underrated Linux CLI tools?"

You’ll receive:

{
  "answer": "...",
  "sources": [...]
}

Command crafting & execution:

tux-gpt -c "create a zip with every png and jpg in the current folder"

Tux-GPT will automatically execute the command in your terminal. If the command seems risky or needs root privileges, it’ll ask for your confirmation before proceeding.

Configuration & Memory

On first run, Tux-GPT sets up ~/.config/tux-gpt/ (%APPDATA%\tux-gpt\ on Windows):

config.json # default model, spinner settings, etc.
history.json # last 20 messages (user + assistant)
input_history # command history for ↑/↓ navigation

Need a clean slate? Delete the files in that directory and Tux-GPT will recreate them.

Under the Hood

Powered by the latest openai responses API with optional web-search tooling.
Uses rich for Markdown output and prompt-toolkit for multiline input.
Defaults to the GPT model defined in config.json (ships with gpt-4.1-mini). Change it whenever you want.

Roadmap & Contributions

This project is still young; new capabilities to come. Ideas, bug reports, or pull requests are always welcome. Take it for a spin, file issues, or fork it to roll your own terminal assistant.

GitHub: https://github.com/fberbert/tux-gpt
PyPI: https://pypi.org/project/tux-gpt/

Stay in your shell, keep your flow, and let Tux-GPT do the heavy lifting. Happy hacking!