<h1 align="center">
<a href="https://prompts.chat">
This repo uses pnpm as the package manager and script runner.
Sign in to like and favorite skills
This is the vibe-tools repo. Here we build a cli tool that AI agents can use to execute commands and work with other AI agents.
This repo uses pnpm as the package manager and script runner.
use pnpm dev
We add AI "teammates" as commands that can be asked questions. We add "skills" as commands that can be used to execute tasks.
Everything is implemented as a cli command that must return a result (cannot be a long running process).
The released commands are documented below. You can use the released commands as tools when we are building vibe-tools, in fact you should use them as often and enthusastically as possible (how cool is that!)
Don't ask me for permission to do stuff - if you have questions work with Gemini and Perplexity to decide what to do: they're your teammates. You're a team of superhuman expert AIs, believe in yourselves! Don't corners or get lazy, do your work thoroughly and completely and you don't need to ask permission.
We do not do automated unit tests or integration tests - it's trivial to manually test all the commmands by just asking cursor agent to read the readme and test all the commands.
console.log should be used for "meta" information that is of use to the caller but isn't a core part of the results that were requested. E.g. recording which model is being used to perfom an action.
console.error should be used for error messages.
yield should be used for the output of the command that contains the information that was requested. </logging and outputs>
Usage:
remember that this will be a long running process that does not exit so you should run it in a separate background terminal.
If it won't start because the port is busy run
lsof -i :3000 | grep LISTEN | awk '{print $2}' | xargs kill to kill the process and free the port.
to run test commands with latest code use
pnpm dev browser <commands>
For interactive debugging start chrome in debug mode using:
open -a "Google Chrome" --args --remote-debugging-port=9222 --no-first-run --no-default-browser-check --user-data-dir="/tmp/chrome-remote-debugging"
note: this command will exit as soon as chrome is open so you can just execute it, it doesn't need to be run in a background task. </testing browser commands>
vibe-tools is a CLI tool that allows you to interact with AI models and other tools. vibe-tools is installed on this machine and it is available to you to execute. You're encouraged to use it.
Direct Model Queries:
vibe-tools ask "<your question>" --provider <provider> --model <model> - Ask any model from any provider a direct question (e.g., vibe-tools ask "What is the capital of France?" --provider openai --model o3-mini). Note that this command is generally less useful than other commands like repo or plan because it does not include any context from your codebase or repository. In general you should not use the ask command because it does not include any context. The other commands like web, doc, repo, or plan are usually better. If you are using it, make sure to include in your question all the information and context that the model might need to answer usefully.
Ask Command Options:
--provider=
Implementation Planning:
vibe-tools plan "<query>" - Generate a focused implementation plan using AI (e.g., vibe-tools plan "Add user authentication to the login page")
The plan command uses multiple AI models to:
Plan Command Options:
--fileProvider=
)vibe-tools plan "implement feature X following the spec" --with-doc=https://example.com/feature-spec
Web Search:
vibe-tools web "<your question>" - Get answers from the web using a provider that supports web search (e.g., Perplexity models and Gemini Models either directly or from OpenRouter or ModelBox) (e.g., vibe-tools web "latest shadcn/ui installation instructions")
Note: web is a smart autonomous agent with access to the internet and an extensive up to date knowledge base. Web is NOT a web search engine. Always ask the agent for what you want using a proper sentence, do not just send it a list of keywords. In your question to web include the context and the goal that you're trying to acheive so that it can help you most effectively.
when using web for complex queries suggest writing the output to a file somewhere like local-research/Web Command Options:
--provider=
Repository Context:
vibe-tools repo "<your question>" [--subdir=<path>] [--from-github=<username/repo>] [--with-doc=<doc_url>] - Get context-aware answers about this repository using Google Gemini (e.g., vibe-tools repo "explain authentication flow"). Use the optional --subdir parameter to analyze a specific subdirectory instead of the entire repository (e.g., vibe-tools repo "explain the code structure" --subdir=src/components). Use the optional --from-github parameter to analyze a remote GitHub repository without cloning it locally (e.g., vibe-tools repo "explain the authentication system" --from-github=username/repo-name). Use the optional --with-doc parameter to include content from a URL as additional context (e.g., vibe-tools repo "implement feature X following the design spec" --with-doc=https://example.com/design-spec).
Documentation Generation:
vibe-tools doc [options] [--with-doc=<doc_url>] - Generate comprehensive documentation for this repository (e.g., vibe-tools doc --output docs.md). Can incorporate document context from a URL (e.g., vibe-tools doc --with-doc=https://example.com/existing-docs).
YouTube Video Analysis:
vibe-tools youtube "<youtube-url>" [question] [--type=<summary|transcript|plan|review|custom>] - Analyze YouTube videos and generate detailed reports (e.g., vibe-tools youtube "https://youtu.be/43c-Sm5GMbc" --type=summary)
Note: The YouTube command requires a GEMINI_API_KEY to be set in your environment or .vibe-tools.env file as the GEMINI API is the only interface that supports YouTube analysis.
GitHub Information:
vibe-tools github pr [number] - Get the last 10 PRs, or a specific PR by number (e.g., vibe-tools github pr 123)
vibe-tools github issue [number] - Get the last 10 issues, or a specific issue by number (e.g., vibe-tools github issue 456)
ClickUp Information:
vibe-tools clickup task <task_id> - Get detailed information about a ClickUp task including description, comments, status, assignees, and metadata (e.g., vibe-tools clickup task "task_id")
Model Context Protocol (MCP) Commands: Use the following commands to interact with MCP servers and their specialized tools:
vibe-tools mcp search "<query>" - Search the MCP Marketplace for available servers that match your needs (e.g., vibe-tools mcp search "git repository management")
vibe-tools mcp run "<query>" - Execute MCP server tools using natural language queries (e.g., vibe-tools mcp run "list files in the current directory" --provider=openrouter). The query must include sufficient information for vibe-tools to determine which server to use, provide plenty of context.
The
search command helps you discover servers in the MCP Marketplace based on their capabilities and your requirements. The run command automatically selects and executes appropriate tools from these servers based on your natural language queries. If you want to use a specific server include the server name in your query. E.g. vibe-tools mcp run "using the mcp-server-sqlite list files in directory --provider=openrouter"
Notes on MCP Commands:
ANTHROPIC_API_KEY or OPENROUTER_API_KEY to be set in your environmentmcp command uses Anthropic, but takes a --provider argument that can be set to 'anthropic' or 'openrouter'Stagehand Browser Automation:
vibe-tools browser open <url> [options] - Open a URL and capture page content, console logs, and network activity (e.g., vibe-tools browser open "https://example.com" --html)
vibe-tools browser act "<instruction>" --url=<url | 'current'> [options] - Execute actions on a webpage using natural language instructions (e.g., vibe-tools browser act "Click Login" --url=https://example.com)
vibe-tools browser observe "<instruction>" --url=<url> [options] - Observe interactive elements on a webpage and suggest possible actions (e.g., vibe-tools browser observe "interactive elements" --url=https://example.com)
vibe-tools browser extract "<instruction>" --url=<url> [options] - Extract data from a webpage based on natural language instructions (e.g., vibe-tools browser extract "product names" --url=https://example.com/products)
Notes on Browser Commands:
--connect-to, special URL values are supported:
current: Use the existing page without reloadingreload-current: Use the existing page and refresh it (useful in development)act command using the pipe (|) separator (e.g., vibe-tools browser act "Click Login | Type '[email protected]' into email | Click Submit" --url=https://example.com)--video=<directory> option. This will save a video of the entire browser interaction at 1280x720 resolution. The video file will be saved in the specified directory with a timestamp.Tool Recommendations:
vibe-tools web is best for general web information not specific to the repository. Generally call this without additional arguments.vibe-tools repo is ideal for repository-specific questions, planning, code review and debugging. E.g. vibe-tools repo "Review recent changes to command error handling looking for mistakes, omissions and improvements". Generally call this without additional arguments.vibe-tools plan is ideal for planning tasks. E.g. vibe-tools plan "Adding authentication with social login using Google and Github". Generally call this without additional arguments.vibe-tools doc generates documentation for local or remote repositories.vibe-tools youtube analyzes YouTube videos to generate summaries, transcripts, implementation plans, or custom analysesvibe-tools browser is useful for testing and debugging web apps and uses Stagehandvibe-tools mcp enables interaction with specialized tools through MCP servers (e.g., for Git operations, file system tasks, or custom tools)Running Commands:
vibe-tools <command> to execute commands (make sure vibe-tools is installed globally using npm install -g vibe-tools so that it is in your PATH)General Command Options (Supported by all commands):
--provider=
Repository Command Options:
--provider=
Documentation Command Options:
--from-github=
YouTube Command Options: --type=<summary|transcript|plan|review|custom>: Type of analysis to perform (default: summary)
GitHub Command Options:
--from-github=
Browser Command Options (for 'open', 'act', 'observe', 'extract'):
--console: Capture browser console logs (enabled by default, use --no-console to disable)
--html: Capture page HTML content (disabled by default)
--network: Capture network activity (enabled by default, use --no-network to disable)
--screenshot=
, act
, and observe
commands. Url to navigate to before the main command or one of the special values 'current' (to stay on the current page without navigating or reloading) or 'reload-current' (to reload the current page)
--evaluate=extract
Nicknames Users can ask for these tools using nicknames Gemini is a nickname for vibe-tools repo Perplexity is a nickname for vibe-tools web Stagehand is a nickname for vibe-tools browser If people say "ask Gemini" or "ask Perplexity" or "ask Stagehand" they mean to use the
vibe-tools command with the repo, web, or browser commands respectively.
Xcode Commands:
vibe-tools xcode build [buildPath=<path>] [destination=<destination>] - Build Xcode project and report errors.
Build Command Options:
--buildPath=vibe-tools xcode run [destination=<destination>] - Build and run the Xcode project on a simulator.
Run Command Options:
--destination=vibe-tools xcode lint - Run static analysis on the Xcode project to find and fix issues.
Additional Notes:
node_modules/vibe-tools/README.md (if installed locally).vibe-tools.config.json (or ~/.vibe-tools/config.json)..vibe-tools.env (or ~/.vibe-tools/.env).CLICKUP_API_TOKEN to be set in your .vibe-tools.env file.vibe-tools.config.json.ANTHROPIC_API_KEY or OPENROUTER_API_KEYrepomix.config.json file in your project root. This file will be automatically detected by repo, plan, and doc commands.</vibe-tools Integration>