penguin-tamer 0.6.0.dev2

Penguin Tamer - AI-powered terminal assistant for Linux systems

🐧 Penguin Tamer

🐧 Tame your Linux terminal with AI power! Ask questions to ChatGPT, Deep Seek, Grok and many other large language models (LLM). Execute scripts and commands suggested by the neural network directly from the command line. Perfect for beginners in Linux and Windows administration.

🌍 Available in: English | Русский

Table of Contents

• penguin-tamer!
  • Table of Contents
  • Description
    • Features
    • Quick Start
  • Connecting to Neural Networks
    • Getting a Token (API_KEY) and Connecting to a Pre-installed Model
    • Adding a New Model
      • Connection Example
  • Examples
    • Quick Query
    • Dialog Mode
    • Running Code from AI Response
  • Security
    • Best Practices
  • Installation
    • Ubuntu/Debian (pipx)
    • Ubuntu/Debian (DEB Package)
    • Windows (Experimental)
  • Removal
    • If installed with pipx
    • If installed as DEB package
    • If installed on Windows
  • Configuration
    • Initial Setup
    • Supported AI Providers
    • Configuration File
    • Reset Settings
  • Contributing
    • Areas for Contribution
    • Development Environment Setup
    • Contribution Guidelines
  • License
  • Contacts

Description

Features

• Quick AI queries — Get answers from large language models via the command line
• No GUI — Communicate with your chosen AI in natural language and any locale: ai how to install Russian fonts?
• Interactive dialog mode — Chat with AI in dialog mode with preserved conversation context
• Code execution — Execute scripts and commands suggested by AI in the console
• Friendly interface — Formatted output with syntax highlighting — just like you’re used to when working with neural networks
• Multiple AI providers — Support for OpenAI, OpenRouter, DeepSeek, Anthropic and other popular providers
• Multi-language support — En and Ru are available now. You can (help with translation) into other languages.

Quick Start

Install penguin-tamer using one of the convenient methods.

Try asking the assistant a question, for example pt who are you?. In a couple of seconds, the neural network will respond:

On first launch, the program uses a Microsoft-hosted model — DeepSeek-R1-Lite-Preview with a public token. This is not the best option since you may see a quota-exceeded message due to high traffic, but it’s fine for a test run.

For full operation, you need to obtain a personal token and add it to the selected model in the program settings.

[!NOTE] penguin-tamer can work with any neural network that supports API access. Today this includes almost all large language models (LLMs) on the market. How to add a new model.

Connecting to Neural Networks

penguin-tamer ships with several popular models pre-configured, such as DeepSeek, Grok 4 Fast, Qwen3 Coder. However, provider policies don’t allow full operation without authorization. You must obtain a personal token (API_KEY) from the provider’s website.

Getting a Token (API_KEY) and Connecting to a Pre-installed Model

We recommend the provider OpenRouter — simple registration and dozens of popular models available for free with a single token.

• Register on the website
• Get a token by clicking Create API key. Save it — OpenRouter will show it only once!
• Add the token to penguin-tamer in the settings of the selected model
• Make this model the current one

Done! Now the selected model will answer you in the console. You can connect any other model from this website in the same way.

[!NOTE] One OpenRouter token is valid for all models available from this provider.

A similar procedure applies to other providers, although with OpenRouter available, you may not need it.

Adding a New Model

To add a new model to penguin-tamer, including a local model or one from major providers, simply enter in penguin-tamer settings:

• API_KEY (your personal token)
• API_URL (API base URL)
• model (model name)

You can find this information on the provider’s website in the API section.

Connection Example

Using the example of the free Meta: Llama 3.1 model listed on OpenRouter among dozens of other free models.

Open the model’s page and find the API section.

Among the connection examples, look for information similar to:

• API_URL — for OpenRouter, this parameter is called base_url
• model — listed as model

How to get API_KEY is described above.

Enter these values (without quotes) in penguin-tamer settings and set this model as current. Now Meta: Llama 3.1 will answer your questions.

Examples

Quick Query

# Simple question
ai kernel update script

Dialog Mode

To start a dialog, use the -d key or simply type pt and press Enter. In dialog mode, penguin-tamer preserves the conversation context throughout the session.

pt -d what python version is installed?

pt  # Enter

Running Code from AI Response

When in dialog mode, if the response contains code blocks — they are numbered. To run code, simply enter the block number in the console.

Security

[!WARNING] Never execute code suggested by the neural network if you’re not sure what it does!

Best Practices

1. Review code before execution

   # Always check what AI suggests
   ai Delete all files from /tmp  # Don’t run this blindly!
   

2. Use safe commands

   # Prefer these over destructive operations
   ai Show disk usage
   ai Show running processes
   

Installation

Ubuntu/Debian (pipx)

Recommended installation method

1. Install pipx (if not installed):

   sudo apt update
   sudo apt install pipx python3-venv -y
   pipx ensurepath
   

2. Restart the terminal

3. Install penguin-tamer:

   pipx install penguin-tamer
   

Note: If pipx doesn’t work, you can install via pip:

pip install penguin-tamer

Ubuntu/Debian (DEB Package)

1. Download the latest DEB package from GitHub:

   wget -qO penguin-tamer.deb $(wget -qO- https://api.github.com/repos/Vivatist/penguin-tamer/releases/latest \
     | grep "browser_download_url.*\.deb" | cut -d '"' -f 4)
   

2. Install the package:

   sudo dpkg -i ./penguin-tamer.deb
   sudo apt-get install -f -y
   

3. Restart the terminal

Windows (Experimental)

1. Install Python 3.11+ (if not installed)

2. Install penguin-tamer:

   pip install penguin-tamer
   

3. Restart the terminal

Removal

If installed with pipx

pipx uninstall penguin-tamer

If installed as DEB package

sudo apt remove penguin-tamer
# Or for complete deletion, including configuration files:
sudo apt purge penguin-tamer

or you can also use dpkg:

sudo dpkg -r penguin-tamer
# Or for complete deletion, including configuration files:
sudo dpkg -P penguin-tamer

If installed on Windows

pip uninstall penguin-tamer

Configuration

Initial Setup

Run the setup mode to configure your AI provider:

pt -s

Supported AI Providers

• OpenAI (GPT-3.5, GPT-4)
• Anthropic (Claude)
• OpenRouter (Multiple models)
• Local models (Ollama, LM Studio)

And many others that support API access.

Configuration File

Settings are stored in:

• Linux: ~/.config/penguin-tamer/config.yaml
• Windows: %APPDATA%\penguin-tamer\config.yaml

Reset Settings

To restore defaults, delete the configuration file manually or run:

# For Linux
rm ~/.config/penguin-tamer/config.yaml

# For Windows
rm %APPDATA%\penguin-tamer\config.yaml

Contributing

I’ll be glad for any help!

Areas for Contribution

• 🌍 Localization — Adding support for new languages (template), including README.md
• 🤖 AI Providers — Integrating new AI providers
• 🎨 UI/UX — Improving the configuration manager interface (yes, it’s not perfect)
• 🔧 Tools — Creating additional utilities
• 💡 Ideas — I welcome any ideas to improve and develop penguin-tamer. Join the discussion

Here’s how to get started:

Development Environment Setup

1. Fork the repository

2. Clone your fork:

   git clone https://github.com/your-username/penguin-tamer.git
   cd penguin-tamer
   

3. Set up the development environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   pip install -e .
   

Contribution Guidelines

• 📝 Code Style: Follow PEP 8
• 🧪 Testing: Add tests for new features
• 📚 Documentation: Update README for new features
• 🔄 Pull Requests: Use clear commit messages

License

This project is licensed under the MIT License.

Contacts

• Author: Andrey Bochkarev
• GitHub Issues: 🐛 Report issues
• Discussions: 💬 Join

---

Created with ❤️ for the Linux community

⭐ Star on GitHub