Skip to content

amansingh63/know-your-shell

BranchesTags

Repository files navigation

know-your-shell

AI-powered personalized tips for your shell — because you already have the shortcuts, you just don't remember them.

zsh MIT License Dependencies 

  ╭─ 💡 Tip for you
  │
  │  gfra  →  Pull with rebase + autostash — stashes, pulls, pops automatically
  │
  ╰─ git

  ╭─ 📊 Dev Insight
  │
  │  You ran git status 142 times — the gst alias would save you ~500 keystrokes
  │
  ╰─ know-your-shell

The Problem

You install a shell framework. It gives you 200+ aliases. You use maybe 10.

You set up fzf, zoxide, bat, eza. You forget half the keybindings within a week.

You define custom functions. Three months later, you rewrite them because you forgot they exist.

Your shell is more powerful than you remember.

The Solution

know-your-shell scans your actual shell environment — your aliases, tools, history, framework plugins — and uses AI to generate two types of content:

  1. Tips — actionable shortcuts for the tools and aliases you already have but haven't memorized
  2. Insights — interesting observations about your usage patterns, habits, and tool adoption gaps

Every time you open a terminal, one randomly appears. Over weeks, you internalize them.

Inspiration

This project was born from a real terminal customization session. While reorganizing a .zshrc into modular config files, I discovered:

  • Duplicate initializations — NVM loading twice, ~/.local/bin added to PATH by both the user and Prezto's Python module
  • 200+ aliases from Prezto modules (git, docker, npm, brew) that I had never seen
  • Conflicting aliases — custom grep=rg overriding Prezto's grep='nocorrect grep'
  • Powerful keybindings (fzf's Ctrl+T, zoxide's zi, zsh's Alt+.) that were configured but forgotten

I built a manual tips.txt with 120+ tips from that setup. It worked — but it was frozen in time. Add a new alias? The tips don't know. Switch tools? Still showing old tips.

The realization: an AI that reads your config can generate tips that stay current with your actual setup. That's know-your-shell.

Features

  • Two output types — shell productivity tips + developer usage insights
  • Scans your real environment — aliases, functions, installed CLI tools, shell history, framework plugins
  • Multiple AI providers — OpenAI, Anthropic Claude, Google Gemini, Ollama (fully local, no API key needed)
  • Zero startup overhead — display reads from flat cache files using only zsh builtins (<1ms)
  • History analysis — analyzes your last 10,000 commands with full arguments, grouped by frequency
  • Framework-aware — detects Prezto, Oh My Zsh, zinit, antidote and their loaded plugins
  • Verbose mode — -v flag shows exactly what's scanned, sent to AI, and cached
  • Works with any plugin manager — or standalone via source

Quick Start

Install

zinit:

zinit light yourusername/know-your-shell

antidote:

# Add to ~/.zsh_plugins.txt
yourusername/know-your-shell

Oh My Zsh:

git clone https://github.com/yourusername/know-your-shell \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/know-your-shell

# Add to plugins in ~/.zshrc
plugins=(... know-your-shell)

Prezto:

# Add to zpreztorc
zstyle ':prezto:load' pmodule-dirs $HOME/.zprezto-contrib
# Clone
git clone https://github.com/yourusername/know-your-shell \
  ~/.zprezto-contrib/know-your-shell
# Add to pmodule list
zstyle ':prezto:load' pmodule ... 'know-your-shell'

Manual:

git clone https://github.com/yourusername/know-your-shell ~/.know-your-shell
echo 'source ~/.know-your-shell/know-your-shell.plugin.zsh' >> ~/.zshrc

Setup

# One-time setup — choose provider, enter API key, select model
know-your-shell init

# Scan your environment + generate tips & insights
know-your-shell refresh

That's it. Open a new terminal and you'll see your first personalized tip or insight.

Commands

Command What it does
know-your-shell init Interactive setup wizard
know-your-shell scan Scan your shell environment
know-your-shell generate Generate tips & insights from scan data using AI
know-your-shell refresh Scan + generate in one step
know-your-shell config View current config
know-your-shell config set <key> <val> Update a config value
know-your-shell status Show status, tip/insight counts, last scan date
tip Show a random shell tip
insight Show a random dev insight
tips <keyword> Search tips by keyword

Global Options

Option What it does
-v, --verbose Show detailed debug output (all scanned data, prompts, AI responses, HTTP status)

The flag works in any position:

know-your-shell scan -v
know-your-shell -v refresh
know-your-shell refresh --verbose

To enable verbose permanently:

know-your-shell config set verbose true

Tips vs Insights

Tips Insights
Purpose Actionable shortcuts to memorize Observations about your usage patterns
Format [category] shortcut | description [insight] observation text
Example [git] gfra | Pull with rebase + autostash You ran git status 142 times — the gst alias saves ~500 keystrokes
Cache file data/tips.txt data/insights.txt
Function tip insight
Startup Random 50/50 with insights Random 50/50 with tips

AI Providers

Provider Models API Key Required Notes
OpenAI GPT-4o, GPT-4o-mini, o1, o3 Yes Most popular
Anthropic Claude Opus, Sonnet, Haiku Yes Great at understanding config structure
Google Gemini Gemini 2.0 Flash, Pro Yes Fast and affordable
Ollama Llama 3.2, Mistral, Qwen, CodeLlama No Fully local, no data leaves your machine

Using Ollama (fully private)

If you don't want to send your shell config to a cloud API:

# Install and start Ollama
brew install ollama
ollama serve &
ollama pull llama3.2

# Configure know-your-shell
know-your-shell init  # choose Ollama
know-your-shell refresh

What Gets Scanned

Data How it's used
Defined aliases Tips for aliases you have but don't use
User-defined functions Reminders about your custom functions
Installed CLI tools Tips for tool features you might not know
Shell history (top 100 from last 10,000 entries) Identifies commands you could alias, full commands with arguments
Framework + plugins Framework-specific tips (Prezto modules, OMZ plugins)
Config file paths Context for the AI to understand your setup

What is NOT scanned: file contents beyond your shell config, environment variables, SSH keys, API keys, or any data outside your shell setup.

How It Stays Fast

Shell startup time is sacred. Here's how know-your-shell adds <1ms:

Shell startup:
  source know-your-shell.plugin.zsh     # entry point
    → source lib/_kys_core.zsh          # define paths + config reader (builtins only)
    → source lib/_kys_tip.zsh           # define tip/insight/tips functions (builtins only)
    → tip or insight                    # read cache file, print 1 random line
                                        # total: <1ms, zero subprocess spawns

Lazy-loaded on demand:
  know-your-shell scan                  # sources scanners/* only when called
  know-your-shell generate              # sources providers/* only when called

The tip and insight functions use:

  • $(<file) — zsh builtin file read (no cat fork)
  • ${(@f)content} — zsh parameter expansion to split lines (no grep fork)
  • RANDOM — zsh builtin random (no external process)
  • printf — zsh builtin formatting

Configuration

Config and data live in the plugin's data/ directory:

provider=anthropic
api_key=sk-ant-****
model=claude-sonnet-4-20250514
tip_on_startup=true
verbose=false
tip_count=65
insight_count=25
last_scan=2026-04-08 14:30:00
last_generate=2026-04-08 14:31:00

API keys are stored with 600 permissions (owner read/write only). The data/ directory is .gitignored.

Tip Format

Tips follow the format:

[category] shortcut | description

Categories: aliases, git, docker, npm, brew, fzf, zoxide, zsh, macos, tools, safety, auto, util, ssh, workflow

Insights follow the format:

[insight] observation text

Testing

# Run all tests (88 currently)
zsh tests/run_tests.zsh

# Run specific test file
zsh tests/run_tests.zsh test_core
zsh tests/run_tests.zsh test_tip
zsh tests/run_tests.zsh test_verbose

Tests use an isolated temp $HOME — no risk to your real config.

Dependencies

  • zsh 5.0+ (you already have it)
  • curl (for API calls — pre-installed on macOS/most Linux)
  • jq (for JSON handling — brew install jq)

That's it. No Python, Node, Ruby, or compiled binaries.

Project Structure

know-your-shell/
├── know-your-shell.plugin.zsh   # Universal entry point + dispatcher
├── init.zsh                     # Prezto entry point
├── lib/
│   ├── _kys_core.zsh            # Paths, config reader, dep check, verbose helper
│   ├── _kys_tip.zsh             # tip/insight/tips display (startup hot path)
│   ├── _kys_init.zsh            # Interactive setup wizard
│   ├── _kys_config.zsh          # Config view/edit commands
│   ├── _kys_scanner.zsh         # Scanner orchestrator
│   ├── _kys_providers.zsh       # AI provider abstraction
│   └── _kys_generate.zsh        # Prompt builder + tips & insights generation
├── providers/
│   ├── openai.zsh               # OpenAI implementation
│   ├── anthropic.zsh            # Anthropic Claude implementation
│   ├── gemini.zsh               # Google Gemini implementation
│   └── ollama.zsh               # Ollama (local) implementation
├── scanners/
│   ├── aliases.zsh              # Extract defined aliases
│   ├── functions.zsh            # Extract user functions
│   ├── tools.zsh                # Detect installed CLI tools
│   ├── history.zsh              # Analyze last 10,000 history entries
│   ├── zshrc.zsh                # Scan config files
│   └── framework.zsh            # Detect Prezto/OMZ/zinit/antidote
├── completions/
│   └── _know-your-shell         # Tab completion
├── tests/
│   ├── _setup.zsh               # Test harness + assertions
│   ├── run_tests.zsh            # Test runner
│   ├── test_core.zsh            # Core/config tests
│   ├── test_tip.zsh             # Tip display tests
│   ├── test_providers.zsh       # Provider tests
│   ├── test_generate.zsh        # Generate tests
│   ├── test_scanner.zsh         # Scanner tests
│   ├── test_verbose.zsh         # Verbose logging tests
│   └── test_integration.zsh     # End-to-end tests
├── data/                        # Runtime data (gitignored)
│   ├── config                   # Provider, API key, model, preferences
│   ├── scan.json                # Latest scan results
│   ├── tips.txt                 # Cached shell tips
│   ├── insights.txt             # Cached dev insights
│   └── generate.log             # Operation log
├── LICENSE                      # MIT
├── README.md
├── .editorconfig
└── .github/workflows/test.yml   # CI

Status

Tested on Prezto (macOS). Should work with Oh My Zsh, zinit, antidote, and standalone setups — but those haven't been tested yet. Feel free to test on your setup and open a PR if you hit issues.

Contributing

Contributions welcome! Some ideas:

  • Test on other frameworks — Oh My Zsh, zinit, antidote, sheldon, zplug
  • New scanners — support for more frameworks and plugin managers
  • New providers — more AI services (Cohere, Mistral API, Together)
  • Smarter history analysis — detect multi-command patterns, suggest pipelines
  • Tip rotation — track seen tips, show unseen ones first
  • Spaced repetition — show tips you struggle to remember more often

License

MIT

About

AI-powered personalized shell tips

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.1.0: Initial Release Latest
Apr 8, 2026

Packages

 
 
 

Contributors

Languages