create-snipara

One-command onboarding for Snipara Hosted MCP Context + Memory.

create-snipara connects a local project to Snipara so AI agents can start with project-owned context, reviewed memory, shared guidance, and optional code impact tooling instead of starting cold every session.

npx create-snipara

create-snipara is the simple onboarding package for the agent path. It creates or reuses auth, writes Hosted MCP config, and prepares the local project so an LLM client can use Snipara context and reviewed memory. Install once with create-snipara; continue every session with snipara-companion.

Use it for:

• Hosted MCP onboarding for Claude Code, Cursor, Windsurf, Codex, Gemini, Mistral, VS Code/Copilot, Continue, ChatGPT Desktop, and similar clients
• free account signup with reviewed Context + Memory
• local project wiring, doctor, repair, and upgrade
• GitHub repository sync and PR Answer Packs approval when the current folder is a GitHub repo

Why It Exists

AI clients all have slightly different config formats, but the project need is the same: connect the agent to the same durable project memory. create-snipara normalizes that setup.

flowchart LR
    Project["Local project"] --> CLI["npx create-snipara"]
    CLI --> Auth["Snipara auth and project key"]
    CLI --> MCP["Hosted MCP config"]
    CLI --> Templates["AGENTS.md, CLAUDE.md, Cursor, Codex, MCP references"]
    MCP --> Agents["Claude Code, Cursor, Codex, Gemini, Mistral, VS Code, ChatGPT"]
    Templates --> Agents
    Agents --> Context["Snipara context and memory"]

The CLI does not become the runtime brain. After setup, the agent talks to Hosted MCP and keeps using its own LLM.

Do not use it to choose business documents one by one. For local folders, mounted Drive/SharePoint exports, old offers, or PowerPoints, use snipara-business.

The product surfaces remain:

• Hosted MCP for LLM agents, context, and reviewed memory
• HTTP API / SDK for apps, integrators, backends, and pipelines

The default CLI path wires the local companion around those surfaces:

• snipara-companion for Git-style status, briefs, timelines, phase commits, handoffs, resume, and local workflow commands
• snipara-sandbox for optional local code execution
• snipara-orchestrator only when explicitly requested with --with-orchestrator
• local config, env files, hook scripts, and a project companion pack
• snipara-mcp only for local stdio compatibility, development, or testing

Install Profiles

The CLI now works around explicit install profiles:

| Profile | What it installs | Best for | | ------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | hosted-companion | MCP + snipara-companion | Default: hosted context plus managed local workflow | | hosted-only | Hosted MCP config only | Locked-down or minimal environments | | full-stack | MCP + snipara-companion + snipara-sandbox | Hosted context plus sandboxed local execution. Does not include orchestrator unless --with-orchestrator is passed | | runtime-only | snipara-sandbox only | Local execution without hosted API |

Default profile: hosted-companion

Free Account Fit

Free onboarding is now Context + Memory, not Context-only:

• Context Free: three projects and 1,000 context queries/month
• Memory Free: reviewed hosted memories for continuity across sessions
• Hosted MCP: direct connection for Claude Code, Cursor, Windsurf, Codex, Gemini, Mistral, VS Code/Copilot, Continue, ChatGPT Desktop, and other MCP clients

The CLI opens a browser device-flow login when the user does not already have a key, auto-provisions the free Context + Memory account when needed, then writes the returned API key into the local MCP config.

The Two Approval Paths

create-snipara deliberately splits setup into two user-friendly surfaces:

1. Terminal Connects the agent, writes local config, and prepares the workstation.
2. Browser Handles account login and GitHub approval because those source permissions must be chosen explicitly by the user.

That distinction matters:

• the terminal is for local setup
• the browser is for identity and source approval
• the MCP is for agent usage after setup, not for initial GitHub permission selection

What It Does

• detects local environment and project state
• opens the browser device-flow free Context + Memory account flow when needed
• writes Hosted MCP configuration
• detects a GitHub remote and can open the Snipara GitHub App automation path
• explains the GitHub PR Answer Packs path for AI-assisted pull request workflows
• installs snipara-companion by default for local status, briefs, timelines, phase commits, handoffs, resume, and managed workflows
• installs optional snipara-sandbox
• installs optional snipara-orchestrator for proof gates, drift checks, and htask workflows when requested
• configures .mcp.json
• generates merge-ready AI agent templates in .snipara/templates/, including Pro+ symbol-card, code-impact, and managed workflow guidance for paid Context plans
• creates AGENTS.md and CLAUDE.md when missing, or appends a marked Snipara section when those files already exist
• creates .cursor/rules/snipara.mdc and .codex/config.toml when those files do not already exist
• validates Codex config against Hosted MCP plus bearer_token_env_var = "SNIPARA_API_KEY" and tells users to restart Codex after MCP config changes
• installs local code overlay Git hooks by default for Claude Code and Codex companion setups, unless --skip-hooks is passed
• runs a real hosted MCP tools/list check and warns if the server still advertises legacy rlm_* duplicate tools
• generates Mistral Le Chat, Mistral Vibe, and LangChain ChatMistralAI.bindTools references without embedding secrets
• writes client-specific companion packs such as .snipara/companion/CODEX.md or .snipara/companion/GEMINI.md
• updates .env, .env.local, and .env.example
• generates .snipara/companion/README.md
• generates .snipara/companion/commands.json
• generates .snipara/companion/doctor.json
• optionally installs Claude Code agent hooks and companion local code overlay Git hooks
• supports doctor, repair, upgrade, and print-config

Product Boundary

Keep the package roles simple:

• create-snipara = connect the user to Hosted MCP Context + Memory
• create-snipara --github = connect the current GitHub repository through the browser approval flow for repository sync and PR Answer Packs
• snipara-openclaw-install = OpenClaw-only wrapper for Hosted MCP config plus OpenClaw env and hook setup
• snipara-business = prepare business context from local or mounted folders
• Hosted MCP = the runtime surface the LLM actually uses after setup

This avoids mixing repo sync, business document review, and agent runtime into one unclear workflow.

Quick Start

npx create-snipara

The interactive flow now asks for:

• project slug
• API key path: existing API key, free signup, or add key later
• AI client

By default, this uses the recommended hosted-companion setup: hosted MCP plus the local snipara-companion workflow helper. Add --advanced when you want profile selection, project id entry, hook prompts, GitHub automation prompts, or sandbox provider prompts. Use --with-orchestrator only when you explicitly need the advanced production validation and htask package; it is not part of full-stack by default.

The advanced flow asks for:

• install profile
• optional project id
• whether hooks should be generated
• whether to open GitHub repository automation when a GitHub remote is detected
• optional sandbox provider config when snipara-sandbox is installed

The generated agent templates cover:

• Codex AGENTS.md
• Claude Code CLAUDE.md
• Cursor .cursor/rules/snipara.mdc
• Codex .codex/config.toml snippet
• ChatGPT/OpenAI HTTP MCP snippet
• Mistral Le Chat connector, Vibe config, and LangChain ChatMistralAI.bindTools snippets
• Gemini, VS Code, Continue, and custom HTTP MCP reference snippets

For Codex, SNIPARA_API_KEY is the only generated bearer token environment variable. If Codex lazily exposes only a minimal Snipara MCP surface after restart, force exact discovery for snipara_recall, snipara_context_query, and snipara_settings. Use snipara-companion recall, snipara-companion query, and snipara-companion task-commit as the reliable local fallback while the Codex session reloads or rediscovers tools.

Existing root AGENTS.md and CLAUDE.md files are not replaced. The installer adds or refreshes a marked Snipara section so project-specific instructions stay intact.

When snipara-companion is installed, the companion pack also includes the compaction-safe managed workflow and Git-style agent work commands. Keep the machine plan in JSON for stable phase ids; an optional Markdown file can remain the human-facing contract.

snipara-companion status
snipara-companion brief --task "ship auth hardening" --changed-files src/auth.ts
snipara-companion workflow start --goal "ship auth hardening" --plan-file ./plan.json
snipara-companion workflow phase-start context
snipara-companion workflow run --mode full --include-session-context --query "load auth context"
snipara-companion code impact --changed-files src/auth.ts tests/auth.test.ts --diff-summary "auth hardening"
snipara-companion workflow phase-commit context --summary "Loaded context and mapped impacted files" --files src/auth.ts
snipara-companion timeline
snipara-companion handoff --summary "auth context mapped" --next "implement auth hardening"
snipara-companion workflow resume --include-session-context
snipara-companion workflow phase-start implementation
snipara-companion workflow run --mode full --include-session-context --query "implement auth hardening"
snipara-companion final-commit --summary "Shipped auth hardening and tests" --files src/auth.ts tests/auth.test.ts

Main Commands

Install or initialize

npx create-snipara
npx create-snipara init

Use this when the goal is "connect my LLM client to Snipara."

Inspect local setup

npx create-snipara doctor

Writes .snipara/companion/doctor.json and validates:

• local config files
• companion CLI presence
• Snipara Sandbox CLI presence
• environment files
• hosted MCP reachability when a live API key is available
• exposed Hosted MCP tool aliases (snipara_*)
• client-specific loading gaps that the terminal cannot prove

For Claude-specific support, run:

npx create-snipara doctor --client claude-code

This separates "Snipara config was written" from "Claude actually loaded the MCP server." If Claude uses its cloud/UI MCP configuration instead of local files, the doctor output points the user to Claude Settings -> MCP instead of repeating local file edits.

Repair local setup

npx create-snipara repair

Rebuilds local project wiring:

• .mcp.json
• env files
• companion pack
• hooks when relevant

Upgrade local pieces

npx create-snipara upgrade

Upgrades installed local components and refreshes the companion pack.

Print inferred config

npx create-snipara print-config
npx create-snipara print-config --json

Source Selection Rules

GitHub repositories

For source-code repositories, let the user approve access in the browser:

npx create-snipara --github

The CLI detects the current repo and can prefill:

• owner/repo
• current branch
• optional path filter such as docs/ or README.md

The browser flow is where the user:

• signs in to Snipara if needed
• approves the Snipara GitHub App
• chooses the GitHub account or organization
• chooses which repositories Snipara may read

This is the correct product boundary. Repository access is explicit, auditable, and revocable.

Local business folders

For business documents, do not ask the user to pick files through the MCP setup flow. Instead:

1. connect Hosted MCP with create-snipara
2. materialize the relevant local or mounted folder
3. run snipara-business to build a reviewable manifest

That keeps business truth review separate from agent onboarding.

Common Flags

# Use an explicit install profile
npx create-snipara --profile hosted-companion
npx create-snipara --profile hosted-only
npx create-snipara --profile full-stack
npx create-snipara --advanced

# Sandbox-only local execution
npx create-snipara --runtime-only

# Safer non-interactive setup with an existing API key
SNIPARA_API_KEY=snp-xxx npx create-snipara -y --slug my-project

# Compatibility path; prints a warning because CLI args can leak
npx create-snipara -y --api-key snp-xxx --slug my-project

# Open GitHub automation after setup when a GitHub remote is detected
npx create-snipara --github
npx create-snipara --github-path docs/

# Skip selected layers
npx create-snipara --skip-companion
npx create-snipara --skip-mcp      # Skip local snipara-mcp package if explicitly requested
npx create-snipara --skip-runtime
npx create-snipara --skip-hooks
npx create-snipara --skip-github

# Force extra layers during maintenance
npx create-snipara repair --with-hooks
npx create-snipara repair --with-runtime
npx create-snipara upgrade --with-runtime

When .mcp.json contains a live API key, create-snipara writes it with restrictive permissions (600) where the platform supports it. Do not hardcode keys in checked-in config files; prefer environment variables, the browser auth flow, or the interactive hidden prompt.

Packaging Model

The intended split is:

• create-snipara: Context + Memory onboarding, auth, config, inspect, repair, and upgrade
• snipara-openclaw-install: OpenClaw-only setup wrapper that remains narrower than create-snipara
• snipara-companion: default local workflow helper
• snipara-mcp: local stdio bridge, client-package development, compatibility, and testing
• snipara-sandbox: optional local execution engine

Client Packs

For every selected AI client, keep Hosted MCP as the core path and let companion add workflow ergonomics:

• use Hosted MCP as the core Snipara surface
• use AGENTS.md for project instructions
• use the selected pack under .snipara/companion/, for example CODEX.md, CURSOR.md, or GEMINI.md
• use the default hosted-companion path when you want compaction-safe local phase commits
• choose hosted-only or --skip-companion only in locked-down environments
• use local snipara-mcp only for stdio compatibility, development, or tests

Claude Code, Cursor, and Windsurf can receive generated automation files when that client has a useful local hook surface. Codex, Gemini, VS Code, Continue, Mistral, ChatGPT, and custom clients are treated as MCP-first: they get the hosted MCP configuration/reference and agent instructions, not invented local hooks. For Mistral, request hooks from LangChain are documented as ChatMistralAI request lifecycle hooks (beforeRequestHooks, requestErrorHooks, and responseHooks), not as local agent lifecycle hooks.

OpenClaw is the specialized exception: use snipara-openclaw-install for a single OpenClaw-focused setup command, or use create-snipara plus snipara-openclaw-hooks when you want the explicit base setup path.

This keeps setup and runtime separated while still giving the user one obvious command to start from.

Generated Local Pack

After setup, the project gets a local pack at .snipara/companion/:

• README.md: local usage guidance
• <CLIENT>.md: selected client setup overlay, such as CODEX.md or GEMINI.md
• commands.json: starter commands for the current project
• doctor.json: most recent validation report

This pack is meant to be the local source of truth for machine-level setup. When snipara-companion is installed, it includes business-folder onboarding commands such as:

snipara-companion onboard-folder ./client-export --source-provider local_folder --write-manifest ./snipara-onboard.json
snipara-companion onboard-folder ./client-export --source-provider local_folder --apply

Use this for dashboardless business-context imports after an LLM client has materialized Drive, Notion, Gmail, or local files into a folder. For source-code repositories, use the GitHub OAuth/code onboarding path instead.

GitHub Automation

When run inside a GitHub-backed repository, create-snipara can open the Snipara GitHub App flow with the detected owner/repo and branch already carried through:

npx create-snipara --github

The browser flow lets the user:

• install or update the Snipara GitHub App
• pick the detected repo
• create or reuse the matching Snipara project
• enable push sync
• start the first documentation sync
• enable PR Answer Packs for AI-assisted pull request workflows

Hosted memory stays attached to the same Snipara account.

PR Answer Packs

PR Answer Packs are generated by the hosted Snipara GitHub App, not by a local MCP command. Once the repository is connected, Snipara can attach scoped repository context to pull requests, including impacted symbols, architecture notes, related history, conventions, and linked documentation.

Use this path for GitHub-native coding-agent workflows:

npx create-snipara --github

Keep using snipara-companion for local planning, code impact checks, and memory commits. Keep using Hosted MCP for agent context retrieval. Do not use snipara-mcp as a separate PR Answer Packs setup path unless Snipara exposes a dedicated MCP tool for it.

Recommended explanation to users:

create-snipara connects your LLM from the terminal. GitHub sync and PR Answer Packs are approved in the browser because GitHub requires the user to choose which account, organization, and repositories Snipara can read.

API Key Requirements

Existing manual API keys passed to create-snipara --api-key must start with snp-. When create-snipara provisions a new account through the browser flow, Snipara returns a new snp- key from the current hosted API. Prefer SNIPARA_API_KEY or the interactive prompt over --api-key; CLI arguments can be visible in shell history and process listings.

| Tooling | Snipara API key | LLM API key | | --------------------------------------------------- | -------------------------- | ----------- | | Hosted MCP queries | Required | Not needed | | Memory / planning tools | Required with memory scope | Not needed | | snipara-companion hosted workflows | Optional | Not needed | | snipara-sandbox execute_python MCP | Not needed | Not needed | | snipara-sandbox run / snipara-sandbox agent CLI | Optional for context | Required |

Example Flows

Default managed hosted setup

npx create-snipara

Best when the user wants Hosted MCP Context + Memory plus snipara-companion managed workflows.

Minimal hosted setup

npx create-snipara --profile hosted-only

Best when the user only wants Hosted MCP Context + Memory and cannot install local helper tooling.

Full local stack

npx create-snipara --profile full-stack --advanced

Best when the user also wants sandboxed snipara-sandbox execution.

Full local stack plus production orchestration

npx create-snipara --profile full-stack --with-orchestrator

Best when the user wants Hosted MCP, companion workflows, Sandbox execution, and the explicit snipara-orchestrator package for production gates, drift checks, or htask coordination.

Connect the current repository

npx create-snipara --github

Best when the current folder is a GitHub repository and the user wants code or docs sync through the GitHub App.

PR Answer Packs are part of this hosted GitHub App path. They do not require a separate local MCP package.

Connect the current repository with a path filter

npx create-snipara --github --github-path docs/

Best when the user wants a focused first sync instead of the whole repository.

Continue with business documents

npx create-snipara
npx snipara-business init

Best when the agent connection is done and the next step is business context onboarding from local or mounted folders.

Repair after a broken workstation or new shell

npx create-snipara repair
npx create-snipara doctor

Check what the CLI inferred from this project

npx create-snipara print-config --json

Local Tarball Testing

When testing a locally packed tarball, use npm exec --package instead of npx, for example:

npm exec --package ./create-snipara-1.3.14.tgz create-snipara -- --help

This avoids npx resolution issues with unpublished tarballs.