{"id":18054068,"url":"https://github.com/ioanniswd/pot","last_synced_at":"2026-04-19T10:02:24.408Z","repository":{"id":47058786,"uuid":"268252113","full_name":"ioanniswd/pot","owner":"ioanniswd","description":"PRs overview to better distribute load amongst devs","archived":false,"fork":false,"pushed_at":"2022-06-21T07:01:00.000Z","size":79,"stargazers_count":5,"open_issues_count":12,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-10T22:53:34.852Z","etag":null,"topics":["cli","github","productivity","pull-requests"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/ioanniswd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-31T09:56:15.000Z","updated_at":"2022-06-21T06:45:54.000Z","dependencies_parsed_at":"2022-09-05T11:51:17.338Z","dependency_job_id":null,"html_url":"https://github.com/ioanniswd/pot","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioanniswd%2Fpot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioanniswd%2Fpot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioanniswd%2Fpot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioanniswd%2Fpot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ioanniswd","download_url":"https://codeload.github.com/ioanniswd/pot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248312172,"owners_count":21082638,"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":["cli","github","productivity","pull-requests"],"created_at":"2024-10-31T00:09:08.412Z","updated_at":"2026-04-19T10:02:24.401Z","avatar_url":"https://github.com/ioanniswd.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pot\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\nA CLI to instantly get an overview of one or more repos' PRs, and decide which PR to act upon next.\n\n![Version badge](https://img.shields.io/badge/version-3.0.0-green.svg)\n\n`pot` stands for Pr Overview Tool\n\nNote: This is an ongoing project, and issues are frequently opened and closed. Refactorings and improvements are on the way. Check the [issues section](https://github.com/ioanniswd/pot/issues) for more info.\n\n# How it works\n\n`pot` creates accumulated data for users concerning one or more repositories, using\nGitHub's API through the official GitHub CLI (`gh`), and provides a terminal\ntable overview of the current PR workload distribution for each team member.\n\n\u003e **AI assistants:** A structured skill for using and interpreting `pot` is available at\n\u003e [`.claude/skills/pot/SKILL.md`](.claude/skills/pot/SKILL.md). It includes column\n\u003e definitions, the full decision process, and common `--json` + `jq` patterns.\n\n# Why pot\n\nTo keep releases fast, idle time zero, and context switching minimal.\n\nIn larger teams, PRs stall because reviewers open new PRs instead of clearing their\nactionables. This compounds: more concurrent open PRs → more context switching → slower\nreleases. Developers do this for two reasons: they don't want idle time, and they lack a\nclear picture of what they are currently blocking. `pot` solves the latter.\n\n`pot` is not a management tool. It does not require a team meeting or a tech lead to\ninterpret. Each team member runs it independently to answer one question: **What should I\ndo next?**\n\n# Decision Process\n\nPlease refer to the [SKILL.md](.claude/skills/pot/SKILL.md) for a detailed\ndecision process and column reference.\n\n# Prerequisites\n\n1. **GitHub CLI (`gh`)** v2.0+ — handles all GitHub API access and authentication\n   ```sh\n   # Install: https://cli.github.com\n   gh auth login    # authenticate once\n   gh auth status   # verify\n   ```\n\n2. **Bun** — runtime and package manager\n   ```sh\n   curl -fsSL https://bun.com/install | bash\n   ```\n\n3. **go-task** — task runner (dev/build only, not needed for the standalone binary)\n   ```sh\n   sh -c \"$(curl -L https://taskfile.dev/install.sh)\" -- -d -b ~/.local/bin\n   ```\n\n# Installation\n\n### Option A — Standalone binary (recommended, no runtime required)\n\nDownload the binary for your platform from the [Releases](https://github.com/ioanniswd/pot/releases) page and put it in your PATH:\n\n```sh\n# Example for Linux x64\ncurl -L https://github.com/ioanniswd/pot/releases/latest/download/pot-linux-x64 -o pot\nchmod +x pot\nsudo mv pot /usr/local/bin/pot\n```\n\n### Option B — From source with `bun link`\n\n```sh\ngit clone https://github.com/ioanniswd/pot\ncd pot\nbun install\ntask build\nbun link          # makes `pot` available globally\n```\n\nTo unlink: `bun unlink pot`\n\n### First-time setup\n\nAfter installing, configure your repositories:\n\n```sh\npot config\n```\n\nFollow the interactive prompts to set your GitHub owner (org or user) and repository names.\n\n# Usage\n\n`pot` uses the GitHub CLI for authentication, which means your GitHub credentials\nare managed by `gh`.\n\n### Authentication\n\nFirst, ensure you've authenticated with GitHub CLI:\n\n```sh\n$ gh auth login\n```\n\nThen simply use `pot` as normal:\n\n```sh\n$ pot --users=john,jane,doe\n```\n\n### All-in-one Setup\n\nFor first-time users, here's the complete setup:\n\n```sh\n# 1. Install GitHub CLI (if not already installed)\n# Visit: https://cli.github.com\n\n# 2. Authenticate with GitHub\n$ gh auth login\n\n# 3. Configure pot (one-time setup)\n$ pot config\n\n# 4. Use pot!\n$ pot --users=john,jane,doe\n```\n\n\n## Multiple user overview\n\n```sh\n$ pot --users=john,jane,doe\n\n+------+----------+-----------+-------+---------------+-------------+-------------------+-----------+\n| User | Authored | Reviewing | Total |  Total + / -  | Actionables | Actionable  + / - | Untouched |\n+------+----------+-----------+-------+---------------+-------------+-------------------+-----------+\n| doe  | 3        | 0         | 3     | 146 / 82      | 1           | 40 / 37           | 0         |\n| jane | 1        | 2         | 3     | 270 / 254     | 2           | 200 / 187         | 0         |\n| john | 2        | 1         | 3     | 34 / 48       | 3           | 34 / 48           | 0         |\n+------+----------+-----------+-------+---------------+-------------+-------------------+-----------+\n```\n\nNote: By default, `pot` only counts open PRs.\n\n#### Authored\nNumber of PRs authored by the user\n\n#### Reviewing\nNumber of PRs currently reviewing, meaning that said user has not\napproved, or rejected the PR. If user is a requested reviewer, or if user has\nplaced comments but has not approved or rejected the PR yet, they are considered\n**active reviewers**, and said PR counts as one they are currently reviewing.\n\n#### Total\nAuthored + Reviewing\n\n#### Total + / -\nAdditions/Deletions for all active PRs of user\n\n#### Actionables\nA PR is considered actionable for a user, when said user can\nperform any action in said PR, and is probably blocking another user. For\nexample, if `john` is the author of a PR, and `jane` places some comments, that PR\nbecomes actionable for `john`, and non actionable for `jane`. When `john` responds to\n`jane's` comments and re-requests review from her, PR becomes non actionable for\n`john` and actionable for `jane`.\n\n#### Actionable + / -\nAdditions/Deletions for all actionable PRs of user\n\n#### Untouched\nWhen a user is requested to review a PR, and until the moment\nthey place their first comment, that PR is considered untouched for said user.\nThis is useful when workload ends up unevenly distributed amongst devs, and a\ndev who has an easier time, tries to decide whose PR they are going to review to\neven the load.\n\n### Note:\nThe above rows are sorted. First by **Total**, then by **Actionable**, and finally by **Untouched** (asc). This way, the most likely candidate to whom a new PR will be assigned, will be closer to the top, and the most likely candidate who might need some help with their PRs, will be closer to the bottom.\n\n## Details about a specific user's PRs\n\nThe above example only shows the accumulated counts for each user. Usually, one\nwill want more details about a specific user's PRs. In that case the\n`--user=\u003cuser\u003e` option can be used.\n\n```sh\n$ pot --user=doe\n\n+------+----------+-----------+-------+---------------+-------------+-------------------+-----------+\n| User | Authored | Reviewing | Total |  Total + / -  | Actionables | Actionable  + / - | Untouched |\n+------+----------+-----------+-------+---------------+-------------+-------------------+-----------+\n| doe  | 2        | 3         | 5     | 5287 / 2095   | 3           | 5270 / 2035       | 1         |\n| john | 3        | 2         | 5     | 5287 / 2095   | 1           | 5270 / 2035       | 1         |\n+------+----------+-----------+-------+---------------+-------------+-------------------+-----------+\n\n+------------+-----------+-------------+---------------------------+\n|                         Authored                                 |\n+------------+-----------+-------------+---------------------------+\n| Actionable | Approvals | +/-         | PR                        |\n+------------+-----------+-------------+---------------------------+\n| Yes        | 2 / 2     | 4729 / 1561 | Add feature cool (PR_url) |\n| No         | 1 / 3     | 12 / 58     | Fix bug wah(PR_url)       |\n+------------+-----------+-------------+---------------------------+\n\n+------------+-----------+---------------------+-----------+-----------+--------------------------+\n|                                      Reviewing                                                  |\n+------------+-----------+---------------------+-----------+-----------+--------------------------+\n| Actionable | Untouched | Author: Actionables | Approvals | +/-       | PR                       |\n+------------+-----------+---------------------+-----------+-----------+--------------------------+\n| Yes        | Yes       | john: 1             | 1 / 2     | 304 / 39  | Add feature wow (PR_url) |\n| Yes        | No        | john: 1             | 0 / 2     | 237 / 435 | Fix bug dang (PR_url)    |\n| No         | No        | jane: 1             | 3 / 3     | 5 / 2     | Improve styles (PR_url)  |\n+------------+-----------+---------------------+-----------+-----------+--------------------------+\n```\n\nNote: Both `--users=\u003cuser, names\u003e` and `--user='user'` can be used:\n```sh\n$ pot --users=john,jane --user=doe\n```\nAnd both the accumulative and the specific output will be shown\n\nIn the above example, the accumulative data is shown for user `doe`, as well\nas some details about each of the PRs they are involved in. This can be used by\n`doe` to figure out which PR needs their attention first, or by another user\nwho happened to have some idle time and wants to help out. Information about\n`john` appear as well, since john is the author of all the PRs that `doe` is\nreviewing, and is also reviewing all PRs that `doe` has authored. This allows\none to simply pass the `--user` argument and get information on the status of all\nusers with which they share any PRs, without explicitly passing a `--users`\nargument.\n\n#### Approvals\nThe ratio of users who have approved the PR, to all users ever involved in the PR.\n\n#### +/-\nAdditions / Deletions in lines of code\n\n## List all of user's PR urls\n\nThis is used to conveniently open all of a users PRs in the browser\n\n```sh\n$ pot --user=doe --url-only\n\n```\n\nThis way one can open all of `doe's` PRs in a browser like this:\n```sh\n$ pot --user=doe --url-only | xargs -L1 xdg-open\n```\n\n\n# Configuration\n\n## GitHub Authentication\n`pot` uses the GitHub CLI (`gh`) for authentication. Credentials are managed by `gh`, not by `pot`.\n\nTo authenticate:\n```sh\n$ gh auth login\n```\n\nThis step is **required** before using `pot`.\n\n## Repository Configuration\n\nYou can provide repository information either via command-line options or by saving a default configuration.\n\n### Option 1: Command-line Options\n\nProvide options each time you run `pot`:\n\n```sh\n$ pot --user=doe --repository_names \"octo, cat\" --owner_name 'repo_owner_name'\n```\n\n### Option 2: Save Default Configuration\n\nTo save frequently-used repository information:\n\n```sh\n$ pot --config\n```\n\nFollow the interactive wizard to define:\n- **Repository names** (comma-separated): Which repositories to analyze\n- **Owner name**: GitHub user or organization that owns the repositories\n- **Cache enabled**: Whether to cache PR data for faster subsequent runs\n\nThe configuration is saved to `~/.pot/config` for future use.\n\n# Register\nIn case a command is usually being used with certain options, options can be saved\nunder a certain name like so:\n\n```sh\n$ pot --users=jane,jack --user=doe --repository_names \"octo, cat\" --register_new \u003cregister_name\u003e\n```\nAnd then:\n\n```sh\n$ pot --registered \u003cregister_name\u003e\n```\n\nIn the above example, options `users`, `user` etc are being filled through the\nsaved registry in the config.\n\nYou can also override some of the underlying options saved in the registry:\n```sh\n$ pot --registered \u003cregister_name\u003e --repository_names 'some, other, repos'\n```\n\n# Speeding up\nThere is the option of caching raw data returned from github for future use,\nwhich significantly speeds up further responses. For example, running:\n\n```sh\n$ pot --users=john,jane,doe\n```\n\nAnd then, wanting to know more about a specific user through the detailed view:\n\n```sh\n$ pot --user=doe --cached\n```\n\nThis way, for the second command, no request is made, the data is considered to\nbe the same.\n\nTo enable this feature, run the config wizard. If enabled, the raw data from\nthe request(s) are stored in `pot_root_folder/cached_response` everytime the command\nsends a request to github. Results are cached under the repo names used\nin the command. If different repo names are used, the request is made and its\nresponse is **also** saved in the aforementioned file.\n\ne.g.\n\nAssume the cache was just enabled (`cache_enabled: true` in the config file).\n\nNote: The `--cached` option specifies that we want to use the cached response, if\npresent. If not present, the request is made as if `--cached` was ommited.\n\nThis **sends** the request and saves the raw response:\n\n```sh\n$ pot --users=jane,doe --repository_names=octo --cached\n```\n\nThis **also sends** the request and saves the raw response under a different key:\n\n```sh\n$ pot --users=jane,doe --repository_names=octo,cat --cached\n```\n\nSubsequent requests made with the repositories being `octo`, `octo,cat` or `cat, octo` and the `--cached` option will use the cached response from the previous requests.\nFor example, the following commands will **not** trigger a request:\n\n```sh\n$ pot --users=john --repository_names=octo,cat --cached\n```\n```sh\n$ pot --users=jane --repository_names=cat,octo --cached\n```\n```sh\n$ pot --users=doe --repository_names=octo --cached\n```\n\nBut this one will, since response for repo `cat` alone has not been received so\nfar:\n```sh\n$ pot --users=doe --repository_names=cat --cached\n```\n\nNote: `--cached` is not saved when using `--register` [See `register`](#register)\n\n\n# Troubleshooting\n\n## GitHub CLI (`gh`) Not Found\n**Error:** `gh: command not found`\n\n**Solution:** Install the GitHub CLI from https://cli.github.com\n\n## Not Authenticated\n**Error:** `Error fetching PRs: authentication required`\n\n**Solution:** Run `gh auth login` and follow the interactive prompts to authenticate with GitHub\n\n## Permission Issues\n**Error:** `Error fetching PRs: insufficient permissions`\n\n**Solution:** Ensure your GitHub credentials have access to the repositories you're querying. Check your GitHub token permissions:\n```sh\n$ gh auth status\n```\n\n## Repository Not Found\n**Error:** `Error fetching PRs: repository not found`\n\n**Solution:** Verify that:\n1. The owner name and repository names are correct\n2. You have access to the repository\n3. The repository exists on GitHub\n\n# Contributing\n\n1. Create an issue describing the purpose of the pull request unless there is one already\n2. Fork the repository ( https://github.com/ioanniswd/pot/fork )\n3. Create your feature branch (`git checkout -b my-new-feature`)\n4. Commit your changes (`git commit -am 'Add some feature'`)\n5. Push to the branch (`git push origin my-new-feature`)\n6. Create a new Pull Request\n\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://iridakos.com\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/9477868?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eLazarus Lazaridis\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-iridakos\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/sntokos\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/56229533?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eStefanos Ntokos\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-sntokos\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-enable --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n\n# License\n\nThis tool is open source under the [MIT License](https://opensource.org/licenses/MIT) terms.\n\n[[Back To Top]](#pot)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioanniswd%2Fpot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fioanniswd%2Fpot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioanniswd%2Fpot/lists"}