{"id":16223867,"url":"https://github.com/kohkimakimoto/gptx","last_synced_at":"2025-04-03T05:30:30.885Z","repository":{"id":162859362,"uuid":"618999796","full_name":"kohkimakimoto/gptx","owner":"kohkimakimoto","description":"An extensible command-line utility powered by ChatGPT, designed to enhance your productivity.","archived":false,"fork":false,"pushed_at":"2023-05-08T11:50:11.000Z","size":42,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T10:21:23.624Z","etag":null,"topics":["chatgpt","cli","openai","shell"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kohkimakimoto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-26T00:40:04.000Z","updated_at":"2024-05-12T09:15:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"acb0b2a9-f060-4971-8660-9de3c1658dc4","html_url":"https://github.com/kohkimakimoto/gptx","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kohkimakimoto%2Fgptx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kohkimakimoto%2Fgptx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kohkimakimoto%2Fgptx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kohkimakimoto%2Fgptx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kohkimakimoto","download_url":"https://codeload.github.com/kohkimakimoto/gptx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246944377,"owners_count":20858773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatgpt","cli","openai","shell"],"created_at":"2024-10-10T12:20:38.858Z","updated_at":"2025-04-03T05:30:30.602Z","avatar_url":"https://github.com/kohkimakimoto.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gptx\n\n[![test](https://github.com/kohkimakimoto/gptx/actions/workflows/test.yml/badge.svg)](https://github.com/kohkimakimoto/gptx/actions/workflows/test.yml)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kohkimakimoto/gptx/blob/main/LICENSE)\n[![release](https://img.shields.io/github/release/kohkimakimoto/gptx/all.svg)](https://github.com/kohkimakimoto/gptx/releases)\n\nAn extensible command-line utility powered by ChatGPT, designed to enhance your productivity.\n\n## Overview\n\nGptx is designed to bridge the gap between the [ChatGPT API](https://platform.openai.com/docs/api-reference/chat) and your shell environment.\nSeamlessly integrate ChatGPT's natural language processing capabilities with familiar shell functionalities.\nWith Gptx, you can easily script, automate, and elevate your shell tasks with the power of ChatGPT, unlocking a new world of AI-assisted productivity in a terminal environment.\n\n### Features\n\n- [Chat](#simple-chat-messages) with ChatGPT from your terminal\n- Manage a series of messages as a [conversation](#conversations)\n- [Cache](#cache) responses from ChatGPT API\n- Highly customizable with [Hooks](#hooks) and [Custom subcommands](#custom-subcommands)\n\n## Installation\n\n### Precompiled binaries\n\nGptx is a single binary command line program. You can download a precompiled binary at the Github releases page.\n\n[Download the latest version](https://github.com/kohkimakimoto/gptx/releases/latest)\n\n### Homebrew\n\n```sh\nbrew install kohkimakimoto/gptx/gptx \n```\n\n### From source\n\n```sh\ngo install github.com/kohkimakimoto/gptx/cmd/gptx@latest\n```\n\n## Usage\n\nAfter installing, you can run `gptx init` command to initialize the configuration.\n\n```sh\ngptx init\n```\n\nThis command creates a directory `~/.gptx`. It has a configuration file `config.toml`.\n\n\u003e :information_source: Note: You can also change the directory path by setting the environment variable `GPTX_HOME`.\n\u003e This directory is used to store the configuration file, along with other files utilized by the gptx command.\n\nOpen the configuration file `~/.gptx/config.toml` with your favorite editor, and enter your OpenAI API key in the `openai_api_key` field.\n\n```toml\n# ~/.gptx/config.toml\nopenai_api_key = \"sk-*******\"\n```\n\n### Simple chat messages\n\nYou can chat with ChatGPT by running the `gptx chat` or `gptx c` command.\n\n```sh\ngptx chat \"What is the capital city of Japan?\"\n# -\u003e The capital city of Japan is Tokyo.\n````\n\nGptx can accept prompt text from STDIN.\n\n```sh\necho \"What is the most famous landmark in Tokyo?\" | gptx chat\n# -\u003e The most famous landmark in Tokyo is the Tokyo Tower.\n```\n\n\u003e :information_source: Note: You can use both STDIN and arguments at the same time. They are concatenated with a newline such as `STDIN + \"\\n\" + ARGUMENTS`.\n\nhttps://user-images.githubusercontent.com/761462/235860236-7704caa2-6f5f-49a2-b7f8-b472ec255e15.mp4\n\n### Conversations\n\nConversations in Gptx consist of a series of messages. Each conversation has one or more messages.\nMessages comprise user's message or assistant's message. A user's message is a text that you send to ChatGPT, and a assistant's message is a text that ChatGPT returns to you.\n\nBy default, Gptx creates a new conversation for each chat process described above. You can list the created conversations by running the `gptx list` or `gptx ls` command.\n\n```sh\ngptx list\n```\n\n````\nID   PROMPT                                         MESSAGES   NAME   LABEL   HOOKS   CREATED                ELAPSED\n 1   What is the capital city of Japan?                    2                          2023-05-03T06:40:24Z   21 seconds ago\n 2   What is the most famous landmark in Tokyo?            2                          2023-05-03T06:40:37Z   8 seconds ago\n````\n\n\u003e :information_source: Note: Conversations are saved to the internal database file `$GPTX_HOME/gptx.db`.\n\nYou can display the conversation details by running the `gptx inspect` or `gptx i` command with conversation ID.\n\n```sh\ngptx inspect -p 1\n```\n\n\u003e :information_source: Note: The -p option is used for pretty-printing JSON data.\n\n```json\n{\n  \"id\": 1,\n  \"prompt\": \"What is the capital city of Japan?\",\n  \"created_at\": \"2023-05-03T06:40:24.465656Z\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What is the capital city of Japan?\"\n    },\n    {\n      \"role\": \"assistant\",\n      \"content\": \"The capital city of Japan is Tokyo.\"\n    }\n  ]\n}\n```\n\nIf you want to send a message in an existing conversation context, you can use the `--resume` or `-r` option.\n\n```sh\ngptx chat --resume 1 \"What about the USA?\"\n# -\u003e The capital city of the United States of America (USA) is Washington D.C.\n```\n\nYou can assign a unique name to a conversation using the `--name` or `-n` option. This is helpful if you want to resume the conversation later.\n\n```sh\n# Create a new conversation with a name.\ngptx chat -n city \"What is the capital city of Japan?\"\n# -\u003e The capital city of Japan is Tokyo.\n\n# Resume the conversation by name.\ngptx chat -r city \"What about the USA?\"\n# -\u003e The capital city of the United States of America (USA) is Washington D.C.\n```\n\nhttps://user-images.githubusercontent.com/761462/235863838-e1792bdb-542f-426e-8dba-bd62b1d655c4.mp4\n\n### Cache\n\nBy default, Gptx caches the response from ChatGPT API. When you send the exact same message to ChatGPT API, Gptx returns the cached response instead of sending a request to ChatGPT API.\nIf you don't want to use the cache, you can use the `--no-cache` option.\n\n```sh\ngptx chat --no-cache \"What is the capital city of Japan?\"\n```\n\nYou can also clear the all cache by running the `gptx clean` command.\n\n```sh\ngptx clean\n```\n\n### Interactive mode\n\nGptx has an interactive (REPL) mode. You can enter the interactive mode by running the `gptx chat` command with `--interactive` or `-i` option.\n\n```sh\ngptx chat -i\n```\n\n```\nWelcome to gptx v0.0.1.\nType \".help\" for more information.\n\u003e What is the capital city of Japan?\nThe capital city of Japan is Tokyo.\n\u003e What about the USA?\nThe capital city of the United States of America (USA) is Washington D.C.\n\u003e\n```\n\n\u003e :information_source: Note: In the interactive mode, your input messages are in the same conversation context.\n\nhttps://user-images.githubusercontent.com/761462/235866177-eb76ca9c-3f81-406e-966c-a196899ae282.mp4\n\n## Configuration\n\nThe configuration file must be written in [TOML](https://github.com/toml-lang/toml).\nBy default, Gptx loads the configuration file from  `~/.gptx/config.toml`.\nIf you want to change the path, you can set the environment variable `GPTX_HOME` and then it will load the configuration file from `$GPTX_HOME/config.toml`.\n\n### Example\n\n```toml\n# OpenAI API Key. You can override this value by using the OPENAI_API_KEY environment variable.\nopenai_api_key = \"\"\n\n# Default model for Chat API\nmodel = \"gpt-3.5-turbo\"\n\n# Maximum number of cached responses.\nmax_cache_length = 100\n```\n\n## Hooks\n\nGptx hooks offer a powerful mechanism for extending the functionality of your Gptx processes.\nDesigned to inspect and filter the messages, hooks provide the flexibility to execute custom logic both before and after submitting a request to the ChatGPT API.\nHooks can generate dynamic prompts, parse outputs, and implement any other custom behavior to tailor your ChatGPT experience to your specific needs.\n\n### Example: Shell Hook\n\nGptx has a reference implementation of the hook called *Shell Hook*. You can use it by running the `gptx chat` command with `--hook` or `-H` option. Try the following command.\n\n```sh\ngptx chat --hook shell \"start http server with python3\"\n```\n\nYou will see the following output.\n\n```\npython3 -m http.server\nChoose an action: Run (r), Copy to clipboard (c), or Nothing (n):\n```\n\nUsing the *Shell Hook*, Gptx is able to generate shell commands based on your input message and then asks for additional action.\n\nhttps://user-images.githubusercontent.com/761462/236078907-6016b8e5-83cd-44ed-bd68-5467838678bd.mp4\n\n### How do hooks actually work?\n\nHooks are command line programs that you can write in any programming language.\nThe Gptx chat process goes through a series of steps, with hooks being executed along the way to provide opportunities for modifying the chat process behavior.\n\nThe following diagram illustrates the chat process with hooks incorporated.\n\n![hooks-diagram](https://user-images.githubusercontent.com/761462/236674975-1d0eab37-8a6a-4904-a853-acf8d2e90636.svg)\n\nAs you can see in the diagram, there are various points at which hooks are executed: `pre-message`, `post-message`, and `finish`.\nThese execution points are called [Types of hooks](#types-of-hooks).\nHooks specified by the `--hook` or `-H` option are executed at all of these points.\nYou can retrieve the hook execution point from the `GPTX_HOOK_TYPE` environment variable in the hook programs.\n\nSo, the minimum hook written in Bash script is like the following:\n\n```bash\n#!/usr/bin/env bash\nset -e -o pipefail\n\ncase \"$GPTX_HOOK_TYPE\" in\n  'pre-message')\n    echo \"run pre-message hook\"\n    ;;\n  'post-message')\n    echo \"run post-message hook\"\n    ;;\n  'finish')\n    echo \"run finish hook\"\n    ;;\n  *)\n    echo \"invalid hook kind: $GPTX_HOOK_TYPE\" 1\u003e\u00262\n    exit 1\n    ;;\nesac\n```\n\nHooks must have a `gptx-hook-` prefix in their file name and be executable.\nFor example, if you want to use the above minimum example hook, you should create a file named `gptx-hook-example` and make it executable.\n\nYou can place the hooks in the directory indicated by the PATH environment variable, just like general command line programs.\nGptx also provides a `libexec` directory under the Gptx home directory (`~/.gptx/libexec` by default) for placing executable programs related to Gptx.\nThe `libexec` directory is automatically added to the PATH environment variable while Gptx is running.\nIt is recommended to place the hook programs in the `libexec` directory.\n\n\u003e :information_source: Note: [*Shell Hook*](#example-shell-hook) is also placed in the `libexec` directory.\n\nIf you run the above example hook, you will see the following output.\n\n```sh\ngptx chat -H example \"Say hello\"\n# -\u003e run pre-message hook\n# -\u003e run post-message hook\n# -\u003e Hello! How may I assist you today?\n# -\u003e run finish hook\n```\n\nThat's it! These are the requirements for implementing the minimum hook.\nIf you want more details, please read the following sections.\n\n### Environment variables\n\nGptx uses environment variables to pass information to hooks. The following environment variables are available to all hooks.\n\n- `GPTX_HOOK_TYPE`: The type of hook in which the hook is executed. The value is one of `pre-message`, `post-message`, or `finish`.\n- `GPTX_MESSAGE_INDEX`: The index of the current message within the conversation. The value is an integer starting from `0`, with `0` representing the first message.\n- `GPTX_CONVERSATION_ID`: The ID of the conversation. If the hook processes a new conversation and is in the `pre-message` stage, the value is `0`. This indicates that the conversation has not been saved and does not have an ID yet.\n\n### Types of hooks\n\nHooks are executed at various points during the chat process.\nYou need to implement appropriate logic in the hook programs based on the execution points.\nIf no action is needed at a specific point, you should write programs that ignore it.\n\nThe following sections describe the types of hooks in detail.\n\n#### pre-message\n\nThis hook is executed before sending a message to the ChatGPT API, allowing you to modify the message in advance.\nYou can read the input prompt text from the file whose path is specified by the `GPTX_PROMPT_FILE` environment variable.\nThe `GPTX_PROMPT_FILE` environment variable also indicates the path to the file where the hook should write the modified prompt text.\n\nExample: `gptx-hook-translation`\n\n```bash\n#!/usr/bin/env bash\nset -e -o pipefail\n\ncase \"$GPTX_HOOK_TYPE\" in\n  'pre-message')\n    # read the input prompt text\n    prompt=$(cat \"$GPTX_PROMPT_FILE\")\n    # modify the prompt text and write it to the file\n    cat \u003c\u003c EOF \u003e \"$GPTX_PROMPT_FILE\"\nTranslate the following text into Japanese.\nText: $prompt\nJapanese:\nEOF\n    ;;\n  'post-message')\n    # for post-message code...\n    ;;\n  'finish')\n    # for post-message code...\n    ;;\n  *)\n    echo \"invalid hook kind: $GPTX_HOOK_TYPE\" 1\u003e\u00262\n    exit 1\n    ;;\nesac\n```\n\nOutput:\n\n```sh\ngptx chat -H translation hello\n# -\u003e こんにちは\n```\n\n#### post-message\n\nThis hook is executed after receiving a message from the ChatGPT API, allowing you to modify the AI generated output.\nYou can read the AI-generated output from the file whose path is specified by the `GPTX_COMPLETION_FILE` environment variable.\nThe `GPTX_COMPLETION_FILE` environment variable also indicates the path to the file where the hook should write the modified AI-generated output.\n\n#### finish\n\nThis hook is executed at the last stage of the chat process.\nYou can read the final output of the chat process from the file whose path is specified by the `GPTX_COMPLETION_FILE` environment variable.\nYou can use this hook to run additional processing with the chat process output.\n\n### Caveats\n\n- You can assign multiple hooks to the `--hook` or `-H` option. In this case, the hooks are executed in the order in which they are specified.\n- You can only assign hooks to the new conversation. Assigned hooks are saved in the conversation object. If you [resume](#conversations) the conversation, the saved hooks will be executed.\n- The hook can use an exit code `3` as a *Cancel* signal. If the hook returns an exit code `3`, the Gptx process is terminated immediately with no error.\n\n## Custom subcommands\n\nGptx allows you to add custom subcommands.\nGptx recognizes commands with the `gptx-` prefix as these custom subcommands.\nFor example, if you create a command named `gptx-foo`, you can run it as `gptx foo`.\n\nAs I mentioned in the [How do hooks actually work?](#how-do-hooks-actually-work) section, you can place the executable programs in the `libexec` directory under the Gptx home directory (`~/.gptx/libexec` by default).\nThe custom subcommands should also be placed in the libexec directory, as it is the recommended location.\n\n## Author\n\nKohki Makimoto \u003ckohki.makimoto@gmail.com\u003e\n\n## License\n\nThe MIT License (MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkohkimakimoto%2Fgptx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkohkimakimoto%2Fgptx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkohkimakimoto%2Fgptx/lists"}