gpt-clip

gpt-clip is a lightweight command-line tool that sends clipboard content to the OpenAI Chat API and copies the response back to the clipboard.

Features

• Single-command chat via clipboard content
• Configurable system prompt & model via JSON
• Clipboard-agnostic: uses pyperclip (supports xclip, pbcopy, etc.)
• Supports Python 3.7 and above
  • Logs each session to a daily Markdown file (gpt-clip.md) in your config directory with 30-day rotation, capturing prompts, inputs, replies, model, and token usage.

Prerequisites

• Python 3.7 or higher
• pip
• wheel (pip install wheel)
• Python OpenAI client library version >=0.27.7 (pip install 'openai>=0.27.7')
• Linux with xclip installed: sudo apt-get install xclip
• OpenAI API key

Installation

From PyPI

Install the latest release directly from PyPI:

pip install --upgrade gpt-clip

From source

Clone the repository and install locally:

git clone https://github.com/chenle02/ReviseClipBoard.git
cd ReviseClipBoard
pip install .

For development mode (editable install):

pip install -e .

Installing via pipx

If you'd like to install gpt-clip in an isolated environment using pipx, note that the CLI has been tested with OpenAI client openai==0.27.7. To pin the compatible OpenAI version and ensure all dependencies (including pyperclip) are installed, follow these steps:

1. (Optional) Uninstall any existing gpt-clip installation:

   pipx uninstall gpt-clip || true
   

2. Install from your local path, forcing a fresh install and pinning the OpenAI client:

   pipx install --force \
     --spec . \
     --pip-args "openai==0.27.7" \
     gpt-clip
   

3. (Optional) To install in editable mode (so local changes take effect immediately):

   pipx install --force \
     --spec . \
     --editable \
     --pip-args "openai==0.27.7" \
     gpt-clip
   

4. If you see a warning about missing pyperclip, inject it manually:

   pipx inject gpt-clip pyperclip
   

This setup creates an isolated virtual environment for gpt-clip, installs its dependencies, and pins the OpenAI client to a tested version.

Configuration

1. Copy the example configuration to your config directory:

   mkdir -p ~/.config/gpt-clip
   cp config.json.example ~/.config/gpt-clip/config.json
   

2. Edit ~/.config/gpt-clip/config.json to set your system prompt and model. For example, to revise emails professionally:

   {
     "system_prompt": "You are a helpful and professional assistant. Your task is to revise the user's email, improving clarity, tone, and grammar. The email may include a reply history; please take that into account to ensure the response is appropriate in tone, content, and context.",
     "model": "gpt-4.1"
   }
   

Usage

Ensure your OpenAI API key is set:

export OPENAI_API_KEY="<your_api_key>"

Copy text to the clipboard and run:

gpt-clip [options]

Options:

  -c, --config PATH       Path to config JSON file (default: ~/.config/gpt-clip/config.json)
      --model MODEL        Override the model specified in the config file
      --prompt PROMPT      Override the system prompt specified in the config file
  -v, --version            Show program version and exit
  -h, --help               Show this help message and exit

The response from ChatGPT will be copied back to the clipboard.

Logging

gpt-clip automatically maintains a Markdown log file at $XDG_CONFIG_HOME/gpt-clip/gpt-clip.md (default ~/.config/gpt-clip/gpt-clip.md). Each entry includes:

• Timestamp
• System Prompt
• User Input
• Reply
• Model Name
• Token Usage (prompt_tokens, completion_tokens, total_tokens)
• Response ID

The log rotates daily and retains the last 30 days of entries via timed rotation.

Integrations

Awesome WM Keybinding

If you use Awesome Window Manager, you can bind a key to run gpt-clip and show the response via a desktop notification. Add the following to your ~/.config/awesome/rc.lua, adjusting modkey and the key binding as desired:

local gears = require("gears")
local awful = require("awful")

-- Add this inside your globalkeys declaration:
awful.key({ modkey }, "g",
    function()
        awful.spawn.with_shell(
            "gpt-clip && notify-send 'GPT' \"$(xclip -o -selection clipboard)\""
        )
    end,
    {description = "Chat via clipboard and notify result", group = "launcher"}
)

-- After defining your key, ensure you set the new keys table:
root.keys(gears.table.join(globalkeys, /* include the key above */))

This setup will:

• Send the current clipboard content to gpt-clip.
• Copy the AI response back to the clipboard.
• Display the response in a notification via notify-send.

If you're on Wayland with wl-clipboard, replace xclip -o -selection clipboard with wl-paste.

Troubleshooting

Compatibility with older OpenAI clients

gpt-clip auto-detects your OpenAI SDK version:

• If you have openai>=0.27.0, it uses the new OpenAI() client class.
• Otherwise it falls back to the legacy top-level API (openai.ChatCompletion.create).

If you encounter unexpected API errors or want to force the new client, upgrade:

pip install --upgrade 'openai>=0.27.7'

Then, if installed via pipx, reinstall to pick up the updated SDK:

pipx uninstall gpt-clip || true
pipx install --force \
  --spec . \
  --pip-args "openai==0.27.7" \
  gpt-clip

Contributing

Contributions are welcome! Please open issues or pull requests on GitHub.

Author

Le Chen

License

This project is licensed under the MIT License - see the LICENSE file for details. </augment_code_snippet>