UI Potion Logo UI Potion
Home / Potion Kit

Potion Kit

CLI to build static sites with Harold and UI Potion: Handlebars, Markdown, and SCSS only. Chat with the AI to design and build your site; the model uses the UI Potion catalog and potion-kit project conventions, can only suggest components from real specs, can safely inspect or move allowed project directories, can delete empty allowed project directories, can safely move or delete allowed project files inside the current working directory, and can optionally search current web topics with Tavily-backed web research or read a public URL as plain text.

Note: Potion Kit is actively vibe coded — we're improving and optimizing it over time. For the best experience we recommend the newest OpenAI or Anthropic models; they handle the outcome quality best. For a good cheaper option, use Kimi K2.5. Extensive use consumes API tokens and costs depend on your provider's pricing. By using the tool you accept it as-is; only you decide whether and how much to use it. We hope you enjoy building with it.

Commands

  • potion-kit init <directory> — Scaffold a new static site project with pages, partials, SCSS, and a sample post.
  • potion-kit chat — Interactive chat.
  • potion-kit chat "message" — Send one message and exit (one-shot).
  • potion-kit doctor — Validate LLM configuration, provider connectivity, project structure, remote dependencies, and optional Tavily web research when configured.
  • potion-kit clear — Clear chat state for this project (history, summary cache, and event trace ledger).
  • potion-kit or potion-kit --help — Show usage and available commands. Unknown commands (for example potion-kit clean) also show help and do not call the API.

Install & Run

Use Potion Kit as an installed CLI from any directory where you have a .env with your LLM API key. No need to clone the repo.

Install

Option A — npx (no install):

npx potion-kit chat

Option B — global install:

npm install -g potion-kit
potion-kit chat

Start a New Project

  1. Scaffold a site with init:
npx potion-kit init my-site
cd my-site

This creates a ready-to-build project with pages, partials, SCSS, a sample post, and package scripts.

  1. Create a .env file in that directory with your LLM provider and API key. Minimal contents:
POTION_KIT_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here

For Anthropic use POTION_KIT_PROVIDER=anthropic and ANTHROPIC_API_KEY=.... For Kimi (by Moonshot) use POTION_KIT_PROVIDER=moonshot and MOONSHOT_API_KEY=.... See the Potion Kit README for all options and security notes.

  1. Check your setup (optional but recommended):
npx potion-kit doctor
  1. Start chatting from that same directory:
npx potion-kit chat
# or, if installed globally:
potion-kit chat

The tool reads .env from the current working directory, so always run potion-kit from the directory that contains your .env and where you want the AI to read and write files.

You can also run potion-kit chat in any existing project directory or empty folder; init is optional.

Usage Examples

Interactive chat (recommended):

cd my-project
npx potion-kit chat

Type your message at the You: prompt, press Enter; the model replies. Type exit, quit, or q (or Ctrl+C) to quit. Your conversation is saved for the next run.

One-shot (single message then exit):

npx potion-kit chat "I want a blog with a header and footer"
npx potion-kit chat "Add the navbar potion to the layout"

Scaffold and go:

npx potion-kit init my-blog
cd my-blog
# add .env with your provider + key
npx potion-kit chat "Add a navbar and about page"

Start a new conversation:

npx potion-kit clear
npx potion-kit chat "Let's build a docs site"

Check configuration before chatting:

npx potion-kit doctor

Current Web Research (Optional)

If you set TAVILY_API_KEY, chat can search the public web for current information and then read selected pages as plain text. Even without Tavily, chat can still read a public URL that you provide directly.

Example prompts:

npx potion-kit chat "Research the latest CSS nesting support and summarize the sources"
npx potion-kit chat "Read https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_nesting and summarize the key points"

The web reader is text-only: it does not execute page JavaScript, does not download binary files, and blocks localhost, private IPs, and other internal-only addresses.

Project File and Directory Operations

Chat can safely work with project files and directories inside the current working directory.

  • File operations — search, read, write, targeted edit, move, and delete allowed project files.
  • Directory operations — inspect directory trees, move allowed directories, and delete empty allowed directories.
  • Destructive safety — file delete/move requires a fresh file hash from read_project_file; directory move/delete requires a fresh treeHash from inspect_project_directory.
  • Directory limits in v1 — recursive directory delete is not supported, destination overwrite is not supported, and empty-directory delete is the only delete mode for directories.

Example prompts:

npx potion-kit chat "Rename src/components to src/ui/components"
npx potion-kit chat "Inspect src/sections and tell me whether it is safe to move"
npx potion-kit chat "Delete the empty src/tmp directory"
npx potion-kit chat "Move src/posts/draft.md to src/posts/archive/draft.md"

Config & .env

Config precedence (highest to lowest):

  1. Environment variables already present in your shell or process
  2. .env in the current working directory (loaded only for variables not already set)
  3. ./config.json in the current working directory — provider, model, optional maxHistoryMessages, maxToolSteps, maxOutputTokens, and optional Tavily web-research defaults under webSearch; do not put API keys there.

Key variables: POTION_KIT_PROVIDER (required: openai, anthropic, or moonshot), one of OPENAI_API_KEY, ANTHROPIC_API_KEY, or MOONSHOT_API_KEY, and optionally POTION_KIT_MODEL (defaults: gpt-5.2 / claude-sonnet-4-5 / kimi-k2.5), POTION_KIT_API_KEY, POTION_KIT_BASE_URL, POTION_KIT_MAX_HISTORY_MESSAGES, POTION_KIT_MAX_TOOL_STEPS, POTION_KIT_MAX_OUTPUT_TOKENS. For optional web research: TAVILY_API_KEY, POTION_KIT_WEB_SEARCH_MAX_RESULTS, POTION_KIT_WEB_SEARCH_COUNTRY. See the README for full details.

Minimal .env:

POTION_KIT_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here

With an optional model override:

POTION_KIT_PROVIDER=openai
POTION_KIT_MODEL=gpt-5.2
OPENAI_API_KEY=sk-your-key-here

With optional web search:

POTION_KIT_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here
TAVILY_API_KEY=tvly-your-key-here
POTION_KIT_WEB_SEARCH_COUNTRY=united states

Example config.json:

{
  "provider": "openai",
  "model": "gpt-5.2",
  "maxHistoryMessages": 10,
  "maxToolSteps": 16,
  "maxOutputTokens": 16384,
  "webSearch": {
    "maxResults": 5,
    "country": "united states"
  }
}

Security: Potion Kit never sends .env or API keys to the model. Never commit .env; add it to .gitignore. Never put API keys in ./config.json. Never paste API keys in chat, logs, or issues. Keep one .env in the directory from which you run potion-kit, usually your project root. Project file and directory tools are limited to the current working directory and reject sensitive or generated paths. Web research is GET-only, text-only, and blocks localhost and private addresses.

Chat History

Conversation is stored under .potion-kit/ in the directory where you run potion-kit chat: chat-history.json (messages), chat-summary.json (cached summary for long conversations), and chat-events.json (per-turn tool traces). Each request keeps the first user message, may include a condensed summary of the middle conversation when history gets long, and sends the most recent messages (default 10). When a turn records verified file reads or changes, the CLI prints a small turn-result footer from the same trace instead of relying on reply wording alone.

  • chat-history.json — Raw conversation in order as { role, content } entries.
  • chat-summary.json — Cached rolling summary state for long conversations.
  • chat-events.json — Per-turn trace metadata, including tool activity, web-tool metadata, directory metadata such as entryCount and treeHash, and whether the turn had a verified project mutation (file or directory write, edit, move, or delete).

Set POTION_KIT_MAX_HISTORY_MESSAGES, POTION_KIT_MAX_TOOL_STEPS, or POTION_KIT_MAX_OUTPUT_TOKENS (or maxHistoryMessages, maxToolSteps, maxOutputTokens in ./config.json) to tune behavior. Add .potion-kit/ to .gitignore if you do not want to commit chat state. Use potion-kit clear to reset history, summary cache, and event traces for that project.

Legal

Potion Kit uses UI Potion specifications and catalog. By using Potion Kit you are using UI Potion's service and agree to the UI Potion legal disclaimer and privacy policy. That page covers disclaimers on AI-generated code, liability, and user responsibility. Please read it before use.

AI providers and your data: You choose the model and provider (for example OpenAI, Anthropic, or Kimi/Moonshot). By using a provider you agree to that provider's terms of service, acceptable use rules, and data policies. Potion Kit does not control how providers retain, process, or review your prompts and responses.

Sensitive data and cloud LLM risk: If your prompts include proprietary code, secrets, customer data, financials, or internal docs, the main risk is that you are voluntarily sending sensitive material to a third party. The exact risk depends on the provider's retention, access controls, internal review practices, and breach likelihood, so consider what you send and which provider you use.

Links

Get Started

Browse UI Potion Install Potion Kit (npm)