snipara-companion

snipara-companionis Snipara's local helper CLI for bootstrap, ingestion, query, recall, doctor, managed workflow phases, and task-summary workflows. It sits on top of hosted Snipara; it is not a third product surface.

When to use it

• You want a local helper CLI around hook-oriented workflows.
• You are targeting clients like Claude Code, Cursor, or Windsurf.
• You want the installed snipara-companion command for local automation steps.
• You want automatic routing from natural-language structural queries into snipara_code_* tools.

When not to use it

• Do not install it just to connect an LLM. Use Hosted MCP for that.
• Do not install it by default for Codex. Codex works with mcp.json and AGENTS.md.
• Do not treat it as the same thing as snipara-orchestrator or snipara-openclaw-hooks.

Install

npm install -g snipara-companion

The installed executable is snipara-companion.

What it adds now

• Auto-follow structural recommendations: snipara-companion query --follow-recommendation will execute the recommended snipara_code_* tool when Snipara detects a structural code question.
• Workflow presets: snipara-companion workflow run --mode auto and --mode full combine retrieval, planning, and graph follow-up.
• Runtime hints: workflow runs suggest Snipara Sandbox for FULL, orchestrated, or execution-heavy work without executing Runtime jobs themselves.
• Local readiness check: snipara-companion doctor reports Snipara auth, Snipara Sandbox CLI, Runtime MCP config, provider keys, and Docker.
• Direct code graph access: snipara-companion code callers, imports, neighbors, and shortest-path.
• Project-linked standards on demand: snipara-companion shared-context loads the shared collections linked to the current project instead of preloading every team rule on every session.

Context vs memory in companion

• Use context commands for source truth: snipara-companion query, shared-context, and load-document read documents, parsed business files, and linked guidance.
• Use memory commands for durable state: snipara-companion recall asks memory about past decisions and preferences, while snipara-companion session-bootstrap restores durable decisions, learnings, preferences, and short-lived carryover.
• Commit memory after work: snipara-companion task-commit stores only durable outcomes, not raw specs or copied documents.
• Default rule: context first, memory second, task commit last.

Quick start

snipara-companion init --with-hooks --client claude-code

snipara-companion query --query "who calls src.mcp_transport.handle_call_tool" --follow-recommendation

snipara-companion workflow run --mode full --query "plan the auth refactor"

snipara-companion workflow run --mode full --no-runtime-hint --query "plan the auth refactor"

snipara-companion doctor

snipara-companion code imports --file-path src/snipara_engine.py

snipara-companion shared-context --categories BEST_PRACTICES GUIDELINES

snipara-companion recall --query "What did we decide about auth retries?" --type decision

snipara-companion session-bootstrap --include-session-context --max-context-tokens 1000

snipara-companion task-commit --summary "Captured final RFP response playbook"

Context hierarchy

• Project context first: companion stays scoped to the current workspace and project when it runs retrieval.
• Shared context through the project: team standards are pulled from the shared collections linked to that project, not from every collection in the team.
• No global team preload: reviewed memory and workspace defaults preload at session start; shared/team context is fetched when the task actually asks for standards, conventions, or compliance guidance.
• Memory does not replace retrieval: use memory for durable state, then go back to context when you need the exact source material.

Supported presets today

• claude-code
• cursor
• windsurf

Companion vs other packages

Should companion and orchestrator merge?

No. snipara-companion is a local npm CLI centered on hook workflows and local automation ergonomics. snipara-orchestrator is a Python package for advanced production validation and orchestration. Merging them would make install guidance and product positioning less clear, not more.

Recommended split

• Use Hosted MCP for the LLM agent connection.
• Use API / SDK for product workflows and backend automation.
• Use snipara-companion when local terminal ergonomics, hook automation, code graph routing, or lightweight workflow presets are useful.
• Add Snipara Sandbox when the workflow needs local execution, tests, lint, or sandboxed validation. Companion can suggest Runtime and diagnose local readiness, but Runtime remains a separate execution layer.
• Reach for snipara-orchestrator only when you need proof-based validation, drift detection, or production gates.

Related guides

• Which Package?
• Context vs Memory
• Orchestrator guide
• OpenClaw guide