{"id":51368875,"url":"https://github.com/zaripych/gpt-refactor-bot","last_synced_at":"2026-07-03T04:04:47.545Z","repository":{"id":183244004,"uuid":"669823670","full_name":"zaripych/gpt-refactor-bot","owner":"zaripych","description":"Refactor your TypeScript codebase using OpenAI ChatGPT models","archived":false,"fork":false,"pushed_at":"2025-05-15T13:37:16.000Z","size":1160,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-04T21:48:57.072Z","etag":null,"topics":["bot","chatgpt","gpt","openai","refactor","ts-morph","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/zaripych.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-07-23T14:47:39.000Z","updated_at":"2026-01-24T19:44:15.000Z","dependencies_parsed_at":"2024-01-28T09:50:36.131Z","dependency_job_id":null,"html_url":"https://github.com/zaripych/gpt-refactor-bot","commit_stats":null,"previous_names":["zaripych/refactor-bot","zaripych/gpt-refactor-bot"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/zaripych/gpt-refactor-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaripych%2Fgpt-refactor-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaripych%2Fgpt-refactor-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaripych%2Fgpt-refactor-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaripych%2Fgpt-refactor-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zaripych","download_url":"https://codeload.github.com/zaripych/gpt-refactor-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaripych%2Fgpt-refactor-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35071474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["bot","chatgpt","gpt","openai","refactor","ts-morph","typescript"],"created_at":"2026-07-03T04:04:46.973Z","updated_at":"2026-07-03T04:04:47.538Z","avatar_url":"https://github.com/zaripych.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# refactor-bot\n\n`refactor-bot` is a CLI for automated code refactoring using OpenAI's LLMs.\n\nBased on the goal provided by the user the CLI will use the OpenAI API to\ngenerate a plan for the refactoring, and refactor one file at a time using \"Plan\nand Execute\" technique, at the same time making sure the code still compiles and\npasses linting and tests.\n\nThe difference between `refactor-bot` and other tools is that it provides rich\nfunctions API based on `ts-morph` that allows it to extract TypeScript specific\ninformation from the codebase. This deeper insight into the codebase allows the\nCLI to perform more complex refactoring tasks that span across multiple files.\n\n# Installation\n\n```\npnpm add refactor-bot\n```\n\n## From source\n\nDon't you want to tinker with the code yourself? Off-course you do. Then you can\ninstall the CLI from source, and it should be quite easy to do so - no build\nprocess is required. It will just run TypeScript.\n\n```\ngit clone git@github.com:zaripych/gpt-refactor-bot.git\n```\n\n```\n# Install refactor-bot dependencies\npnpm install\n\n# Switch back to your project's repository and add refactor-bot as a dependency\ncd ../your-project-repository pnpm add --save-dev\nfile://../refactor-bot/packages/refactor-bot\n\n# Use `tsx` to run refactor-bot TypeScript code directly without building it\npnpm add tsx\n\n# Run the CLI:\npnpm refactor-bot --help\n```\n\n# Run the CLI:\n\n```\npnpm refactor-bot --help\n```\n\nCreate `.env` file in current directory:\n\n```\nOPENAI_API_KEY=\"your-key\"\n```\n\nSupports commands at the moment:\n\n```sh\n➜  pnpm refactor-bot \u003ccommand\u003e\n\nCommands:\n  pnpm refactor-bot prompt      Sends a prompt to the ChatGPT API to generate a\n                                response\n  pnpm refactor-bot refactor    Performs a refactoring using Plan and Execute te\n                                chnique\n  pnpm refactor-bot completion  generate completion script\n\nOptions:\n  --help     Show help                                                 [boolean]\n  --version  Show version number                                       [boolean]\n```\n\n## Refactor\n\n```sh\n➜  pnpm refactor-bot refactor\n\nPerforms a refactoring using Plan and Execute technique\n\nOptions:\n  --help         Show help                                             [boolean]\n  --version      Show version number                                   [boolean]\n  --name         Name of the refactoring to run                         [string]\n  --id           Unique id of the refactoring that was previously run but didn't\n                  finish - use this to start from last successful step  [string]\n  --costs        Whether to print the total costs of OpenAI requests, by default\n                  it's disabled                       [boolean] [default: false]\n  --performance  Whether to print performance metrics, by default it's disabled\n                                                      [boolean] [default: false]\n```\n\nAt first it will create a file for you with description of the refactor. Open\nthe file, edit it in your editor providing as much relevant information as you\nthink is needed, then rerun the command.\n\nFor an example,\n[have a look here](https://github.com/zaripych/gpt-refactor-bot/blob/main/.refactor-bot/refactors/replace-read-file-sync/goal.md?plain=1#L9).\n\nAfter creating the `goal` description file, we can run the CLI again with the\nname of the file to start the process.\n\n```sh\n➜  pnpm refactor-bot refactor --name xx-yy-zz\n```\n\nRefactoring is considered a success if none of the changed files lead to\nTypeScript or eslint issues and all affected tests pass. Changes which fail the\nchecks will be reverted.\n\nAfter refactoring is complete, you will be presented with a report.\n\nRefactoring will not change any files in your local repository and you will be\nasked to merge the changes yourself.\n\nAt the moment the refactoring is performed in a way that doesn't allow module\ninterface to change. This means that the type that represents all exported\nmembers of a file will not change as a result of the refactoring. This is done\nto ensure that the refactoring is not going to break the codebase. This is\nlikely the most valuable use case, as it is more likely to result in a success.\nOther options are being considered.\n\nIt's likely refactoring might fail for one reason or the other. This could\nhappen for following reasons:\n\n-   Pre-requisites and expectations about the repository are not met by the CLI,\n    see expectations section below\n-   The OpenAI model is not capable of performing the refactoring either due to\n    the model limitations or lack of proper description\n-   There is a bug in the refactor-bot\n\nIn any case, the CLI was built in a way that it can reproduce all the successful\nsteps it had done during previous run without starting from scratch, as long as\nwe know the \"refactor-run-id\". So if you run the CLI again with the same `--id`\nit will start from the last successful step.\n\nUse `LOG_LEVEL=debug` environment variable to see more information about what's\nhappening.\n\n![Example output](https://media.githubusercontent.com/media/zaripych/gpt-refactor-bot/main/.refactor-bot/refactors/replace-read-file-sync/example-report.png 'Example output')\n\nFor more information about how refactoring works see\n[./DOCUMENTATION.md](https://github.com/zaripych/gpt-refactor-bot/blob/main/DOCUMENTATION.md).\n\n## Expectations\n\n-   Source code is TypeScript\n-   `git` for version control\n-   `prettier` for code formatting\n-   `VSCode` as editor (optional)\n-   You have `glow` installed and available in your `PATH` for formatting\n    `markdown` in terminals (optional)\n\n## Prompt\n\nThe `prompt` command allows you to test the functions API we provide to the\nChatGPT and see what kind of information it can extract from the codebase.\n\n```sh\n➜  pnpm refactor-bot prompt --watch\n? Select a file where the conversation is going to be stored › - Use arrow-keys. Return to submit.\n❯   example-1\n    example-2\n    New conversation...\n```\n\nSelect a file, and then you will be prompted to enter a message using your\neditor. Save the message with `---` at the end to send it.\n\nSee example conversation at\n[`.refactor-bot/prompts/example-1.md`](https://github.com/zaripych/gpt-refactor-bot/blob/main/.refactor-bot/prompts/example-1.md).\n\n## Roadmap\n\nThe `refactor` command can do a lot of interesting things. It can be improved\nfurther, but there is no way to measure how much we improved it. So the next\nstep is to add a way to measure the quality of the refactor for benchmarking\npurposes.\n\n-   [x] ability to evaluate result of the refactor to benchmark the quality of\n        the refactor, so we can asses how different changes affect the quality\n        and performance of the refactor-bot\n-   [ ] add Chain Of Thoughts to try to recover from failed attempts to fix\n        issues/tests. at the moment, the algorithm might spent some time in a\n        rabbit hole trying to fix eslint issues for changes it could have\n        reverted in the first place\n-   [ ] add evaluation of multiple responses - at the moment we already can\n        introduce extra iterations to the algorithm, so that instead of\n        analyzing just one response from the LLM, we can try to get multiple and\n        assess if one is better than the other - which can be done by running\n        eslint and tsc on the code generated by the LLM\n-   [ ] add self-verification of the refactor-bot - ie it could try to\n        self-reflect if the results produced by the LLM is good enough and\n        attempt to self-review and try to produce a better output/outcome\n-   [ ] add Tree of Thoughts - we can combine self-assessment capabilities with\n        the ability to generate multiple responses from the LLM to create a\n        tree-like structure of possible outcomes and then evaluate each of them\n        to find the best path forward\n-   [ ] make the algorithm more flexible and allow refactoring process to change\n        the codebase in a way that is not limited to the current module\n        interface\n-   [ ] spike for an ability to generate a refactor script by LLM which could be\n        purposefully built and fine-tuned for a particular task - this would\n        allow to perform more complex refactoring tasks with higher level task\n        descriptions - ie \"migrate RxJS from version 6 to version 7\" or \"migrate\n        to Next.js\", etc.\n-   [ ] spike for an ability to debug the code - ie it could then run the users\n        code in a sandbox and answer questions about the behavior of the code\n-   [ ] spike for an ability to generate new code - for example unit tests, or\n        new features\n-   [ ] spike for an ability to review the code in a PR and possibly debug some\n        of it, if it looks sketchy, or suggest improvements (which it would have\n        already tested, linted and debugged for you)\n-   [ ] ability to create pull requests in GitHub for both successful\n        refactoring and discarded commits with issues\n\n## Privacy and Security\n\nIf you are concerned about privacy, consider using \"business\" account with\nOpenAI. Read their license agreement to understand how they can use the data we\nsend there.\n\nThe use of the provided tools here is fully at your own risk. Ensure there are\nno secrets available to the bot in your projects directory or in environment\nvariables so nothing can be leaked accidentally.\n\nJust a minimum precautions have been made so far to safeguard from accidental\nleaks:\n\n-   We create a temporary directory in `$TMPDIR` and run all the code against\n    the copy, the code is copied from your current repository ignoring\n    everything from '.gitignore' file so only the source code should be copied\n    over\n-   We ensure there are no symlinks leading outside of the temporary directory\n\n### How a leak could occur in theory?\n\nWe use `ts-morph` to get access to the source code, which uses `TypeScript`\ncompiler, which can read files in the repository. So if your source code has any\nsecrets directly in code - they might end up being sent to OpenAI API.\n\n### Code interpreter\n\nThe library has capability to run custom code generated by LLM's. At this moment\nit is only allowed to write TypeScript scripts, which are validated by rollup\nbundling procedure and allowed to access only `ts-morph` library. The use case\nfor the interpreter is to allow the LLM to generate code which can perform\nadvanced analytics or aggregation using `ts-morph` API. For an example, see\n[`.refactor-bot/prompts/example-5.md`](https://github.com/zaripych/gpt-refactor-bot/blob/main/.refactor-bot/prompts/example-5.md).\n\nThis capability is experimental and not exposed to the `refactor` command, but\nis available when `prompt` command is used.\n\n### Other external services\n\nWe do not use other external services at the moment other than OpenAI API.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaripych%2Fgpt-refactor-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzaripych%2Fgpt-refactor-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaripych%2Fgpt-refactor-bot/lists"}