What is this? • Installation • Usage • Contributing

uwu is a lightweight, focused CLI tool that converts natural language into shell commands using Large Language Models (LLMs) like GPT-5. Unlike comprehensive agentic development tools like Claude Code or Cursor, uwu has a simple, singular purpose: helping you write shell commands faster, without switching context.

uwu is not a replacement for comprehensive agentic development tools -- it is simple tool that excels at one thing. Consider it the terminal equivalent of quickly searching "how do I..." and getting an immediately runnable answer.

After a response is generated, you can edit it before pressing enter to execute the command. This is useful if you want to add flags, or other modifications to the command.

git clone https://github.com/context-labs/uwu.git
cd uwu

Make sure you have Bun installed.

bun install
bun run build

This will produce the uwu-cli binary in the dist/ build output directory.

chmod +x dist/uwu-cli
mv dist/uwu-cli /usr/local/bin/uwu-cli

uwu is configured through a single config.json file. The first time you run uwu, it will automatically create a default configuration file to get you started.

The config.json file is located in a standard, platform-specific directory:

• Linux: ~/.config/uwu/config.json
• macOS: ~/Library/Preferences/uwu/config.json
• Windows: %APPDATA%\\uwu\\config.json (e.g., C:\\Users\\<user>\\AppData\\Roaming\\uwu\\config.json)

You can configure uwu to use different AI providers by setting the type field in your config.json. The supported types are "OpenAI", "Custom", "Claude", "Gemini", and "GitHub".

Below are examples for each provider type.

This is the default configuration.

{
  "type": "OpenAI",
  "apiKey": "sk-your_openai_api_key",
  "model": "gpt-4.1"
}

• apiKey: Your OpenAI API key. If this is empty, uwu will use the OPENAI_API_KEY environment variable.

Uses the native Anthropic API.

{
  "type": "Claude",
  "apiKey": "your-anthropic-api-key",
  "model": "claude-3-opus-20240229"
}

• apiKey: Your Anthropic API key.

Uses the native Google Gemini API.

{
  "type": "Gemini",
  "apiKey": "your-google-api-key",
  "model": "gemini-pro"
}

• apiKey: Your Google AI Studio API key.

Uses multiple free to use GitHub models.

{
  "type": "GitHub",
  "apiKey": "your-github-token",
  "model": "openai/gpt-4.1-nano"
}

• apiKey: Your GitHub token.

This type is for any other OpenAI-compatible API endpoint, such as Ollama, LM Studio, or a third-party proxy service.

{
  "type": "Custom",
  "model": "llama3",
  "baseURL": "http://localhost:11434/v1",
  "apiKey": "ollama"
}

• model: The name of the model you want to use (e.g., "llama3").
• baseURL: The API endpoint for the service.
• apiKey: An API key, if required by the service. For local models like Ollama, this can often be a non-empty placeholder like "ollama".

uwu can include recent command history from your shell to provide better context for command generation. This feature is disabled by default but can be enabled. When enabled, uwu includes the raw last N lines from your shell history (e.g., bash, zsh, fish), preserving any extra metadata your shell records:

{
  "type": "OpenAI",
  "apiKey": "sk-your_api_key",
  "model": "gpt-4.1",
  "context": {
    "enabled": true,
    "maxHistoryCommands": 10
  }
}

• enabled: Whether to include command history context (default: false)
• maxHistoryCommands: Number of recent commands to include (default: 10) When enabled, uwu automatically detects and parses history from bash, zsh, and fish shells.

• Chunk size unit: When scanning shell history files, uwu reads from the end of the file in fixed-size chunks of 64 KiB. This is not currently configurable but can be made if desired.

• History detection: On Windows, uwu searches for PowerShell PSReadLine history at:
  • %APPDATA%\Microsoft\Windows\PowerShell\PSReadLine\ConsoleHost_history.txt (Windows PowerShell 5.x)
  • %APPDATA%\Microsoft\PowerShell\PSReadLine\ConsoleHost_history.txt (PowerShell 7+) If not found, it falls back to Unix-like history files that may exist when using Git Bash/MSYS/Cygwin (e.g., .bash_history, .zsh_history).
• Directory listing: On Windows, directory listing uses dir /b; on Linux/macOS it uses ls.

uwu can automatically copy generated commands to your system clipboard:

{
  "type": "OpenAI",
  "apiKey": "sk-your_api_key",
  "model": "gpt-4.1",
  "clipboard": true
}

• clipboard: Whether to automatically copy generated commands to clipboard (default: false)

When enabled, every command generated by uwu is automatically copied to your system clipboard, making it easy to paste commands elsewhere. The clipboard integration works cross-platform:

• macOS: Uses pbcopy
• Windows: Uses clip
• Linux: Uses xclip or xsel (falls back to xsel if xclip is not available)

Note: On Linux, you'll need either xclip or xsel installed for clipboard functionality to work.

This function lets you type uwu <description> and get an editable command preloaded in your shell.

# ~/.zshrc

uwu() {
  local cmd
  cmd="$(uwu-cli "$@")" || return
  vared -p "" -c cmd
  print -s -- "$cmd"   # add to history
  eval "$cmd"
}

After editing ~/.zshrc, reload it:

source ~/.zshrc

uwu() {
  local cmd
  cmd="$(uwu-cli "$@")" || return
  # requires interactive shell and Bash 4+
  read -e -i "$cmd" -p "" cmd || return
  builtin history -s -- "$cmd"
  eval -- "$cmd"
}

Note: This only applies to Windows with Powershell installed

To your Powershell profile, add this snippet

function uwu {
    param(
        [Parameter(ValueFromRemainingArguments=$true)]
        $args
    )
    $Source = '
    using System;
    using System.Runtime.InteropServices;

    public class ConsoleInjector {
        [StructLayout(LayoutKind.Sequential)]
        public struct KEY_EVENT_RECORD {
            public bool bKeyDown;
            public ushort wRepeatCount;
            public ushort wVirtualKeyCode;
            public ushort wVirtualScanCode;
            public char UnicodeChar;
            public uint dwControlKeyState;
        }

        [StructLayout(LayoutKind.Sequential)]
        public struct INPUT_RECORD {
            public ushort EventType;
            public KEY_EVENT_RECORD KeyEvent;
        }

        [DllImport("kernel32.dll", SetLastError = true)]
        public static extern IntPtr GetStdHandle(int nStdHandle);

        [DllImport("kernel32.dll", SetLastError = true)]
        public static extern bool WriteConsoleInput(
            IntPtr hConsoleInput,
            INPUT_RECORD[] lpBuffer,
            int nLength,
            out int lpNumberOfEventsWritten
        );

        const int STD_INPUT_HANDLE = -10;
        const ushort KEY_EVENT = 0x0001;

        public static void SendCommand(string text) {
            IntPtr hIn = GetStdHandle(STD_INPUT_HANDLE);
            var records = new INPUT_RECORD[text.Length];
            
            int i = 0;
            for (; i < text.Length; i++) {
                records[i].EventType = KEY_EVENT;
                records[i].KeyEvent.bKeyDown = true;
                records[i].KeyEvent.wRepeatCount = 1;
                records[i].KeyEvent.UnicodeChar = text[i];
            }

            int written;
            WriteConsoleInput(hIn, records, i, out written);
        }
    }';
    $cmd = uwu-cli @args;
    Add-Type -TypeDefinition $Source;
    [ConsoleInjector]::SendCommand($cmd)
}

This will work for Powershell terminals. To add this functionality to Conhost / Terminal, save this as uwu.bat and let it be accessible in PATH (you must do the Powershell step as well). For example,

:: assumes that ECHO ON and CHCP 437 is user preference
@ECHO OFF
CHCP 437 >NUL
POWERSHELL uwu %*
@ECHO ON

Once installed and configured:

uwu generate a new ssh key called uwu-key and add it to the ssh agent

You'll see the generated command in your shell's input line. Press Enter to run it, or edit it first. Executed commands will show up in your shell's history just like any other command.

MIT

Contributions are welcome! Please feel free to submit a pull request.