Create Perstack Experts interactively
npm install create-expertInteractive wizard to create Perstack Experts.
``bashCreate a new Expert project
npx create-expert
$3
For automation and scripting, use the
--headless flag:`bash
Create a new Expert project (headless)
npx create-expert --headless \
--provider anthropic \
--model claude-sonnet-4-5 \
--description "A code reviewer that checks for TypeScript best practices"Improve an existing Expert (headless)
npx create-expert my-expert "Add web search capability" --headless
`CLI Options
| Option | Description | Default |
|--------|-------------|---------|
|
--headless | Run without TUI wizard | false |
| --json | Output raw JSON events (only with --headless) | false |
| --provider | LLM provider (anthropic, openai, google) | anthropic |
| --model | Model name | Provider default |
| --runtime | Execution runtime (default, cursor, claude-code, gemini) | default |
| --description | Expert description (required in headless mode for new projects) | - |
| --cwd | Working directory | Current directory |$3
In headless mode, the default output is human-readable with progress indicators and a final summary. Use
--json for raw JSON event stream (useful for scripting and automation).What it does
$3
1. Detects available LLMs and runtimes
- LLMs: Anthropic, OpenAI, Google (via environment variables)
- Runtimes: Cursor, Claude Code, Gemini CLI
2. Configures your environment (interactive mode only)
- Prompts for API keys if needed
- Creates
.env file with credentials3. Creates project files (only if they don't exist)
-
AGENTS.md - Instructions for AI agents working on this project
- perstack.toml - Expert definitions and runtime config
- If files already exist, they are preserved and reused4. Runs the Expert creation flow
- Interactive: Uses
perstack start with TUI
- Headless: Uses perstack run for non-interactive execution$3
When called with an Expert name:
`bash
Interactive
npx create-expert my-expert "Add web search capability"Headless
npx create-expert my-expert "Add web search capability" --headless
`Skips project setup and goes straight to improvement, using the existing configuration.
Generated Files
$3
Contains:
- Perstack overview
- CLI reference
- perstack.toml format
- Best practices for creating Experts
- MCP Registry usage for finding skills
$3
Initial config with the
create-expert` Expert that:- Node.js >= 22.0.0
- One of:
- LLM API key (Anthropic, OpenAI, or Google)
- External runtime (Cursor, Claude Code, or Gemini CLI)