create-expert

Interactive wizard to create Perstack Experts.

Usage

$3

``bash


Create a new Expert project

npx create-expert

Improve an existing Expert

npx create-expert my-expert "Add error handling for edge cases"
`

$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 credentials

3. 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 reused

4. 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:
- Understands Expert design principles
- Creates and tests Experts
- Iterates on improvements

Requirements

- Node.js >= 22.0.0
- One of:
- LLM API key (Anthropic, OpenAI, or Google)
- External runtime (Cursor, Claude Code, or Gemini CLI)