Vity: Interact with Your Terminal in English

4 months ago 3

Vity is an AI-powered terminal assistant that helps you generate shell commands and get coding help directly from your terminal. Stop googling commands and start describing what you want to do!

🎯 Smart Command Generation: Describe what you want to do, get the exact command
🧠 Context Awareness: Record terminal sessions for better AI responses based on your current work
💬 Chat Mode: Ask questions about errors, commands, or coding concepts
🔧 Shell Integration: Seamless integration with bash/zsh
📹 Session Recording: Capture terminal output for contextual help
⚡ Fast Setup: One-command installation with automatic configuration

curl -LsSf https://raw.githubusercontent.com/kaleab-ayenew/vity/main/install.sh | sh

If you prefer manual installation:

# Install via pipx (recommended) pipx install vity # Or via pip pip install vity # Install shell integration vity install

Python: 3.9 or higher
OpenAI API Key: Get one at platform.openai.com/api-keys
OS: Linux or macOS
Shell: Bash or Zsh

After installation, run the configuration command:

This will:

Prompt you for your OpenAI API key
Save it securely to ~/.config/vity/.env
Verify the connection

You can also set up the API key manually:

# Create config directory mkdir -p ~/.config/vity # Add your API key echo "OPENAI_API_KEY=your_api_key_here" > ~/.config/vity/.env

Alternatively, export the API key in your shell:

export OPENAI_API_KEY="your_api_key_here"

To enable recording and enhanced features:

vity install source ~/.bashrc # or restart your terminal

# File operations vity do "find all python files larger than 1MB" vity do "compress all images in this directory" vity do "delete files older than 30 days" # System operations vity do "show disk usage by directory" vity do "kill process using port 3000" vity do "create a backup of this folder" # Git operations vity do "undo last commit but keep changes" vity do "create new branch from current state" vity do "show files changed in last commit"

# Error explanations vity chat "what does 'permission denied' mean?" vity chat "explain this docker error message" # Command explanations vity chat "what does 'chmod 755' do?" vity chat "difference between 'rm' and 'rm -rf'" # Coding help vity chat "how to debug python import errors" vity chat "best practices for git branching"

Advanced Usage with Context Recording

For the most powerful experience, use recording to give Vity context about your current work:

You'll see a 🔴 indicator in your prompt showing you're recording.

# Your normal workflow - all commands and output are captured ls -la cd my-project python app.py # Error occurs here...

# Vity sees the error and your project structure vity do "fix this python import error" vity chat "why did my script fail?" vity do "install missing dependencies"

exit # Stops recording and returns to normal terminal

Command Description Example

vity do "<task>"	Generate a shell command	vity do "find large files"
vity chat "<question>"	Ask AI a question	vity chat "explain this error"
vity record	Start recording session	vity record
vity status	Show recording status	vity status
vity config	Manage configuration	vity config --reset
vity install	Install shell integration	vity install
vity help	Show detailed help	vity help

Scenario 1: Docker Troubleshooting

vity record docker build -t myapp . # Build fails with error... vity do "fix this docker build error" # Output: docker system prune -f && docker build --no-cache -t myapp . vity chat "why did the build fail?" # Explains the error and suggests improvements

vity do "create feature branch for user authentication" # Output: git checkout -b feature/user-authentication vity do "stage only python files" # Output: git add *.py vity chat "should I rebase or merge this feature branch?" # Explains the differences and best practices

Scenario 3: System Administration

vity record df -h # Shows disk usage... vity do "find what's using the most disk space" # Output: du -sh */ | sort -rh | head -10 vity do "safely clean up log files older than 7 days" # Output: find /var/log -name "*.log" -mtime +7 -exec rm {} \;

~/.config/vity/.env (primary)
.env in current directory (fallback)

# Required OPENAI_API_KEY=your_api_key_here # Optional (set via environment) VITY_MODEL=gpt-4.1-mini # Default model VITY_LOG_LEVEL=INFO # Logging level

Shell Integration Features

When you run vity install, it adds these features to your shell:

🔴 Recording Indicator: Visual prompt when recording
📁 Auto Log Management: Logs stored in ~/.local/share/vity/logs/
⚡ Context Commands: vity do and vity chat automatically use session context
📊 Status Commands: vity status shows current recording state

"OpenAI API key not found"

# Check configuration vity config # Or set environment variable export OPENAI_API_KEY="your_key_here"

"Command not found: vity"

# Ensure ~/.local/bin is in PATH echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc # Or reinstall curl -LsSf https://raw.githubusercontent.com/kaleab-ayenew/vity/main/install.sh | sh

"Shell integration not working"

# Reinstall shell integration vity install source ~/.bashrc # Check if functions are loaded type vity

# Check if script command is available which script # Install if missing (Ubuntu/Debian) sudo apt install util-linux # Install if missing (macOS) # script is built-in on macOS

Enable verbose logging:

export VITY_LOG_LEVEL=DEBUG vity do "test command"

# Reset all settings vity config --reset # Remove shell integration # Edit ~/.bashrc and remove the "# Vity shell integration" section

API Key Storage: Stored locally in ~/.config/vity/.env
Terminal History: Only sent when using -f flag or during recording
No Persistent Storage: Vity doesn't store your commands or data
Local Processing: All processing happens locally except OpenAI API calls

# Clone repository git clone https://github.com/kaleab-ayenew/vity.git cd vity # Install in development mode pip install -e . # Install development dependencies pip install -e .[dev] # Run tests pytest # Format code black src/ ruff src/

# Build package python -m build # Install locally pip install dist/vity-*.whl

MIT License - see LICENSE file for details.

Built with OpenAI API
Inspired by modern CLI tools like uv
Terminal recording powered by the script command

Need help? Open an issue on GitHub or run vity help for more details.

Read Entire Article

Vity: Interact with Your Terminal in English

Advanced Usage with Context Recording

Scenario 1: Docker Troubleshooting

Scenario 3: System Administration

Shell Integration Features

"OpenAI API key not found"

"Command not found: vity"

"Shell integration not working"

Related

Show HN: I Accidentally Created a Custom Clothing Brand for ...

The Drain of Scientific Publishing

Shell companies and government corruption [pdf]