create-snipara

One-command onboarding for Snipara Cloud or self-hosted Snipara Server.

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

For a local or private server, use the same activation flow:

export SNIPARA_LOCAL_API_KEY="your-server-operator-key"
npx create-snipara@latest --self-hosted \
  --server-url http://localhost:8000/mcp/local \
  --api-key "$SNIPARA_LOCAL_API_KEY" \
  --client claude-code

Both modes aim to finish with the same visible proof:

✓ Endpoint connected
✓ Repository README/docs seeded
✓ First project-grounded answer verified
✓ AI client configuration written

create-snipara is the single activation engine for the agent path. It detects or asks where Snipara should run, writes the right MCP config, seeds a small README/docs corpus, and automatically verifies a first project-grounded answer. The default path is Cloud because it is the fastest first experience; the same flow works with an existing self-hosted Snipara Server. It is also the canonical activation engine behind editor setup docs: VS Code can surface activation as a native command, Cursor can pair OpenVSX UI with Hosted MCP, but both paths should land on the same project context.

Use it when the goal is outcome-first agent work: the user asks for judgment, implementation, release, or verification, and the agent handles Snipara context, workflow state, package checks, Git operations, deployment, and smoke checks behind the scenes.

Use it for:

• Snipara Cloud or self-hosted MCP onboarding for Claude Code, Cursor, Kimi Code CLI, Codex, Gemini, Mistral, VS Code/Copilot, Continue, ChatGPT Desktop, Orca-style MCP clients, LM Studio-backed local stacks, and similar clients
• free account signup with reviewed Context + Memory
• local project wiring, doctor, repair, and upgrade
• local source activation without GitHub, plus optional GitHub repository sync and PR Answer Packs approval when the current folder is a GitHub repo
• day-zero proof with a ready-to-ask grounded question, a small hosted README/docs seed sync, and an evidence-linked Project Bootstrap for new projects

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["Cloud auth or self-hosted operator key"]
    CLI --> MCP["Configured MCP endpoint"]
    CLI --> Templates["AGENTS.md, CLAUDE.md, Cursor, Codex, MCP references"]
    MCP --> Agents["Claude Code, Cursor, Codex, Gemini, Mistral, VS Code, ChatGPT, Orca, LM Studio stacks"]
    Templates --> Agents
    Agents --> Context["Snipara context and memory"]

The CLI does not become the runtime brain. After setup, the agent talks to the configured MCP endpoint 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:

• Snipara Cloud or self-hosted Snipara Server for LLM agents, context, and reviewed memory
• HTTP API / SDK for apps, integrators, backends, and pipelines

Advanced flags can wire local helpers 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

Deployment Modes

The deployment mode and install profile are independent:

| Mode | Command | Data boundary | First proof | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------ | | Snipara Cloud | npx create-snipara@latest | Snipara-managed hosted project | Cloud MCP connection, README/docs seed, grounded answer | | Self-hosted Snipara Server | npx create-snipara@latest --self-hosted --server-url http://localhost:8000/mcp/local --api-key "$SNIPARA_LOCAL_API_KEY" | Your server and storage | Server contract, MCP connection, README/docs seed, grounded answer |

Self-hosted runs use the server's X-API-Key operator key, the public snipara-server-oss-v2 contract, and the server's rlm_* compatibility tools. They never open Cloud signup or call the Cloud dashboard automation API.

Every successful live setup writes .snipara/activation/activation-manifest.json with the selected endpoint, seed status, proof tool, and a non-sensitive proof receipt such as answer_pack_chars=.... Raw API keys are never included in the activation report or JSON summary.

Install Profiles

The CLI now works around explicit install profiles:

| Profile | What it installs | Best for | | ------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | hosted-only | Hosted MCP config only | Default: first grounded answer with no local companion, hooks, or sandbox | | hosted-companion | MCP + snipara-companion | Hosted context plus managed local workflow after first value | | 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-only

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, Kimi Code CLI, Codex, Gemini, Mistral, VS Code/Copilot, Continue, ChatGPT Desktop, Orca-style MCP clients, LM Studio-backed local stacks, 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
• can activate the current folder locally through snipara-companion source init after the user opts into Companion
• explains the GitHub PR Answer Packs path for AI-assisted pull request workflows
• installs snipara-companion only with --advanced, --profile hosted-companion, --profile full-stack, or repair --with-companion
• 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 symbol-card, code-impact, and managed workflow guidance within plan capacity
• 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
• generates one opaque correlation session ID and reuses it in .mcp.json, Companion, Codex, and Kimi configuration so served context can be joined to later project outcomes without treating the ID as authentication
• installs local code overlay Git hooks only for explicit companion/full-stack 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

Project Bootstrap: Cold-Start Intelligence

During setup, create-snipara builds a reviewable picture of the repository before the first agent task. It writes both a machine-readable artifact and a human-readable report:

• .snipara/activation/project-bootstrap.json
• .snipara/activation/project-bootstrap.md

The report summarizes eight dynamic sections. Counts come from the current repository; they are not fixed demo numbers:

• architecture patterns
• conventions
• decision candidates
• procedures
• skills and candidate workflows
• recurring failure candidates
• critical code symbols
• verification patterns

The local pass uses bounded evidence from Git history, AGENTS.md, CLAUDE.md, README, docs/, CI configuration, package scripts, test patterns, and release history. Every item links back to its evidence. Directly detected facts can be marked observed; inferred decisions, workflows, and failure patterns remain needs_review and are not promoted to durable project memory automatically.

The artifact also includes a coverage ledger. PR and issue history are marked unavailable until the user explicitly connects a source provider. Critical symbols are marked deferred until Code Graph indexing is available. Snipara does not invent candidates to make these sections look complete.

After setup, start here:

Review what Snipara learned about your project.

The Project Bootstrap summary is also carried into the First Work Brief so the agent begins with the repository's inherited experience and its remaining evidence gaps in view.

Product Boundary

Keep the package roles simple:

• create-snipara = connect the user to Hosted MCP Context + Memory
• snipara-companion source init = automatic local source snapshot, document dry-run, and local code overlay without GitHub
• 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:

• deployment mode when --advanced is used
• a self-hosted MCP endpoint when self-hosted mode is selected
• project slug
• API key path: Cloud key/signup, self-hosted operator key, or add key later
• AI client

By default, this uses the minimal hosted-only setup: configured MCP config and a doctor report, with no local Companion install, hooks, GitHub approval prompt, or sandbox prompt. 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:

• Snipara skill pack under .snipara/templates/skills/
• 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

The generated skill pack includes portable, client-neutral skills for Snipara onboarding, context workflow, safe parallel work, agent security, and proof gates. Clients with native skill support can copy each folder from .snipara/templates/skills/ into the client's skill location. Clients without native skills should keep using AGENTS.md, CLAUDE.md, or project rules as the shared instruction surface.

For Codex, SNIPARA_API_KEY is the only generated bearer token environment variable. If Codex exposes only the lean Snipara MCP surface after restart, that is expected. Use snipara_help(query=...) for routed guidance and snipara_help(list_all=true) to inspect specialist opt-in surfaces. Use snipara-companion recall, snipara-companion query, and snipara-companion task-commit as the reliable local fallback when the simple hosted tools are not callable.

Codex also receives a static X-Snipara-Session-Id HTTP header. This value is opaque, non-secret telemetry generated per workspace; repair and upgrade reuse it when valid. It does not replace the bearer token or grant access.

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.

Enable those local helpers later with:

npx create-snipara repair --with-companion

snipara-companion status
snipara-companion source init .
snipara-companion source sync --json
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 memory invalidate mem_old --reason "obsolete runbook"
snipara-companion memory supersede mem_old mem_new --reason "corrected decision"
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

Local source first

For free users, the first useful source step does not need GitHub approval:

snipara-companion source init .
snipara-companion source status --json

That creates .snipara/source/latest.json, previews supported document sync, and refreshes .snipara/code-overlay/latest.json from local files. GitHub automation is still the canonical hosted repository path for teams, PR Answer Packs, and shared CODE indexing after the user approves the provider.

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

# Self-hosted non-interactive setup; the same command works with any MCP client
SNIPARA_LOCAL_API_KEY=local-operator-key npx create-snipara -y \
  --self-hosted --server-url http://localhost:8000/mcp/local \
  --api-key "$SNIPARA_LOCAL_API_KEY" --slug my-project

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

# Explicitly choose the deployment mode
npx create-snipara -y --deployment hosted --api-key snp-xxx --slug my-project
npx create-snipara -y --deployment self-hosted \
  --server-url http://localhost:8000/mcp/local --api-key local-operator-key

# 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: optional local workflow helper after first value
• 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
• start with the default hosted-only path for the shortest route to a grounded answer
• choose hosted-companion after first value when you want compaction-safe local phase commits
• use local snipara-mcp only for stdio compatibility, development, or tests

Claude Code, Cursor, and Kimi Code CLI can receive generated automation files when that client has a useful local hook surface. Kimi receives a project-local MCP config and a reviewable plugin that must be installed explicitly; its hooks are fail-open. 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 Kimi Code CLI:

npx -y create-snipara@latest init --client kimi --profile hosted-companion --with-hooks
npx -y snipara-companion@latest automations install --client kimi
# Then, in Kimi Code after reviewing the plugin:
/plugins install .kimi-code/snipara-plugin

Export SNIPARA_API_KEY before starting Kimi. The generated .kimi-code/mcp.json stores only bearerTokenEnvVar, never the raw key. It also carries the same non-secret X-Snipara-Session-Id used by the project MCP and Companion configuration so Outcome Loop telemetry remains joinable. Kimi installs plugins per user, so the generated handler is project-neutral and no-ops outside workspaces carrying a Snipara project or Companion marker. 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

Activation evidence is kept separately under .snipara/activation/, including the Project Bootstrap JSON/Markdown pair, First Work Brief, handoff, and memory candidate review artifacts.

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.54.tgz create-snipara -- --help

This avoids npx resolution issues with unpublished tarballs.