Note
If you want to learn about the design of HOTPOT, see the HOTPOT architecture document.
- I like the
brainstormingcapability insuperpowers, but I want it to be triggered proactively instead of through askill. - Whenever code written by
AIhas issues or does not follow conventions, I have to manually updateAGENTS.md, and sometimes I may even forget. I wantAIto remember these things by itself so the same issues do not happen again next time. - Plain
markdownfiles can be tiring to browse. I want more polished task files that can be accessed from a browser without affecting howAIparses them.
- Basic framework capabilities, including brainstorming, code execution, code review, and more.
- Issues from execution and questions raised by users are automatically accumulated. Users decide whether to persist them. During
review, Hotpot retrieves the closest data through scenarios and scoring, up to 5 records, to improve review accuracy. vuepressintegration, allowing more polished task files to be viewed in a browser without amarkdownreader or similar tools. This feature depends onnpmandpnpm.- Two rounds of self-checking and self-repair.
- No external dependencies, unless
vuepressis enabled, which requirespnpm. TDDhit mechanism:TDDis enabled only when Hotpot determines it is needed, but the choice is still yours.AIonly judges, and does not decide.- Subagent failure detection and recovery.
Download the binary archive for your platform from the release page, extract it, and add it to your environment variables.
hotpot can be installed globally via npm. The npm package (@fancyhq/hotpot) is a lightweight wrapper that downloads the platform-specific Rust binary from the corresponding GitHub Release version during installation. Even though the package is scoped under @fancyhq, the installed CLI command remains hotpot.
npm install -g @fancyhq/hotpotAfter installation, the hotpot CLI command is available on your PATH.
Note: The npm installation requires network access to GitHub Releases. If GitHub is not accessible from your network, the installation will fail. In that case, you can download the binary directly from the Releases page.
Note for custom/internal npm registries: If your npm is configured to use a custom registry (e.g., an internal mirror), the
@fancyhq/hotpotpackage may not be available there. You can install it directly from the public npm registry using one of these approaches:
- One-off install:
npm install -g @fancyhq/hotpot --registry https://registry.npmjs.org- Persistent scope configuration:
npm config set @fancyhq:registry https://registry.npmjs.org/The second approach only affects packages under the
@fancyhqscope, leaving your default registry unchanged for all other packages.
If you have Rust installed, you can install hotpot from crates.io:
cargo install hotpot-aiThis compiles hotpot from source. The installed CLI command is still hotpot. Requires the Rust toolchain.
Caution
In general, do not use hotpot init directly. This installs configurations for all agent tools. You should choose the platform you are currently using.
Each project needs to be initialized at least once. If you need to add support for another agent tool, you can use a command like this:
hotpot init --platform opencodeStart your agent, then use the hotpot:new command to create a task.
/hotpot:new <your request>After everything is complete and manually verified, use hotpot:finish-work to finish the task.
/hotpot:finish-workFor a project where hotpot already exists, other collaborators can be added. New users need to run the following command in the project root:
hotpot updateThe git username is used by default. You can also define your own name:
hotpot update --username <your username>- If
vuepressis already enabled for the project (see.hotpot/config.toml) but the.hotpot-hubdirectory is missing, usehotpot vuepress installto re-fetch thevuepressframework. - For a newly pulled project, you can use
hotpot vuepress installto create the corresponding user directory.
Simple project configuration can be done in .hotpot/config.toml. Currently, manually configurable data only includes:
Caution
Do not manually modify the vuepress configuration, such as directly changing the vuepress status to enabled = true, because vuepress also has dependent directories. Manual changes will not take effect.
language: the language used for generated artifacts. You can set different languages according to your needs, such as简体中文/English/日本語/Français, and so on.
There is a lot of discussion about replacing markdown with html, but html inevitably has many shortcomings. It is clearly more complex for AI to parse html than markdown. The benefit of using html is that it is more comfortable for humans to read, but I do not think it should consume more tokens for that. A task file is usually limited in size, so I wanted to find a compromise that makes reading more comfortable for humans without increasing the burden on AI parsing. That led me to documentation services. They usually use markdown or mdx as source files, while offering greater freedom in the page presentation layer. After evaluating options, I chose vuepress. Even without using vue components, it still provides a good reading experience, and the overall framework is also well suited for categorized browsing.
You can choose whether to enable vuepress. After it is enabled, a vuepress directory is created in the current project. You can put this directory directly into git, excluding the node_modules directory, because its data is located through symlinks. The installed size does not grow much: the whole directory is less than 130k, excluding node_modules.
However, this also introduces an extra issue. Since the project is designed with minimal dependencies, enabling vuepress means a node environment is required.