create-voice-assistant

CLI scaffolder for SmartPersonalAssistant — spin up a niche AI voice assistant in one command.

npx create-voice-assistant my-app

The template repo is private. You need a GitHub token and collaborator access before running this. Read Authentication first.

Authentication

Step 1 — Get added as a collaborator

Ask the repo owner (Makishima09) to add you in: GitHub → Settings → Collaborators & teams → Add people

Accept the invitation email from GitHub.

Step 2 — Generate a Personal Access Token

1. Go to github.com/settings/tokens
2. Click Generate new token (classic)
3. Set scope: repo (full control of private repositories)
4. Set expiration as you prefer (no expiration is convenient; 90 days is safer)
5. Copy the ghp_... value — you only see it once

Step 3 — Export the token and run the CLI

# PowerShell
$env:GITHUB_TOKEN = "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
npx create-voice-assistant my-app

# bash / zsh
GITHUB_TOKEN=ghp_xxxx npx create-voice-assistant my-app

GH_TOKEN is also accepted as a fallback (compatible with the GitHub CLI convention).

If the token is missing or invalid, the CLI prints a clear error and exits without writing anything.

What happens after you run the command

1. Clone

The CLI clones the template into ./my-app/ via HTTPS using your token:

git clone --depth 1 --branch main https://oauth2:[email protected]/Makishima09/SmartPersonalAssistant.git my-app

The token is never logged or stored. Only used for this one request.

2. Strip git history

.git/ is deleted immediately after the clone. Your new project starts with no history — it has no connection to the template repo. You can git init your own repo whenever you want.

3. Interactive generator

The CLI launches scripts/generate.ts, which asks you a series of questions:

Project / assistant name:           FitBot
Primary domain:                     fitbot.com
One-line niche description:         Entrenador personal con IA
Tone hints (optional):              energético, motivador, sin excusas
Response language:                  Spanish / English

--- Brand colors ---
Primary color (hex):                #FF5500
Accent / highlight color (hex):     #FFB300

--- Providers ---
Default STT provider:               OpenAI Whisper / Deepgram
Default TTS provider:               OpenAI / Cartesia / Inworld
OpenAI TTS voice:                   alloy / echo / fable / nova / onyx / shimmer
Default LLM provider:               OpenAI / xAI Grok / Anthropic / Google / Kimi
LLM model name:                     gpt-4o-mini
LLM temperature:                    0.7

--- Feature flags ---
Enable features:                    [x] Text chat  [x] Admin panel
                                    [ ] Stripe payments  [x] Dark mode
                                    [ ] n8n webhook  [ ] Email templates

Use Claude to draft the agent persona? (requires ANTHROPIC_API_KEY)  yes / no

If you answer yes to the last question and have ANTHROPIC_API_KEY set, Claude generates the full 8-block agent persona (identity, conversation phases, protocols, tone rules) from your niche description. Otherwise, sensible defaults are used and you can edit the config manually afterward.

4. Files written

The generator writes three files:

| File | What changes | |---|---| | voice-assistant.config.ts | Full niche config consumed by the frontend and API routes | | voice-assistant.config.json | Mirror of the above, consumed by the Python backend agent | | package.json | name and description updated with your project name |

All other files (frontend code, API routes, Prisma schema, backend agent) are left untouched.

5. Next steps banner

Once the generator finishes, the CLI prints:

✓ Config generated for: FitBot

Next steps:

  cd my-app
  npm install
  cp .env.example .env
  # Fill in: DATABASE_URL, LIVEKIT_*, OPENAI_API_KEY, and any optional keys

  npx prisma migrate dev
  npm run dev

Backend agent (Python):
  cd backend && cp .env.example .env
  pip install -r requirements.txt
  python agent.py dev

From here the project is entirely yours. No link back to the template repo.

What gets published to npm

Only the contents of dist/ (defined in "files": ["dist"]):

dist/index.js       ← the compiled CLI (~150 lines)
dist/index.d.ts
dist/index.js.map
dist/index.d.ts.map

This contains: the prompts for folder name, the token check, the git clone command, the spawn of generate.ts, and the next-steps banner. Nothing from the template (frontend, backend, configs, schema) is included.

The only thing visible in the published package is the repo name Makishima09/SmartPersonalAssistant. Without a valid collaborator token, the clone fails with a 128 authentication error.

Local testing

To test without publishing to npm:

cd create-voice-assistant/
npm install
npm run build
npm link

# From any directory
GITHUB_TOKEN=ghp_xxx create-voice-assistant test-app

# Unlink when done
cd create-voice-assistant/ && npm unlink

Publishing to npm

cd create-voice-assistant/
npm login
npm publish --access public

prepare runs npm run build automatically before publish, so no manual build step needed.

If the package name create-voice-assistant is already taken, use a scoped name:

1. Update "name" in package.json to @makishima09/create-voice-assistant
2. npm publish --access public
3. Users run: npx @makishima09/create-voice-assistant my-app

Updating the template

The CLI always clones main. When the template repo is updated, the next scaffold automatically gets the latest version — no need to republish this CLI.

To pin to a specific release, change the constant in src/index.ts:

const TEMPLATE_BRANCH = 'v1.0.0';

Environment variables

| Variable | Required | Purpose | |---|---|---| | GITHUB_TOKEN or GH_TOKEN | Required | Authenticate the template clone | | ANTHROPIC_API_KEY | Optional | AI-assisted persona generation in the generator |

All other env vars (Neon, LiveKit, Stripe, Resend, etc.) belong in the generated project's .env — not here.