snipara-companion

snipara-companion is the Git-style continuity CLI for agent work. Use create-snipara to install and connect a project once, then use companion every session to check status, generate a brief, commit phases, write handoffs, and resume without rediscovering the repo.

Git-style command model

Companion gives agents a familiar terminal model for work state. It does not version files; Git still does that. Companion versions the session state around the files: current phase, active goal, open decisions, risks, verification context, handoff notes, and where to resume.

When to use it

• You want a local status, timeline, and handoff layer for agent sessions.
• You want compaction-safe phase commits for multi-step work.
• 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 use it as a replacement for Hosted MCP. Codex still uses hosted MCP config and AGENTS.md for the agent tool surface.
• 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

• Agent work status: snipara-companion status summarizes the current phase, goal, latest phase commit, local risks, open handoffs, and next action.
• Start Work Brief alias: snipara-companion brief is the top-level shortcut for the Project Intelligence brief.
• Timeline: snipara-companion timelinegives the workflow log agents need before resuming someone else's session.
• Handoff artifacts: snipara-companion handoff writes what changed, what was verified, what is risky, what remains, and where to resume.
• 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 lite, --mode standard, --mode full, and --mode orchestrate cover focused work, normal coding work, managed phases, and explicit hosted orchestration. auto remains a compatibility alias for STANDARD behavior.
• Runtime hints: workflow runs suggest Snipara Sandbox for FULL, orchestrated, or execution-heavy work without executing Sandbox jobs themselves.
• Orchestrator handoff hints: companion can detect snipara-orchestrator and point production-gate or htask work to it, but does not install it or spawn workers automatically.
• Local readiness check: snipara-companion doctor reports Snipara auth, Snipara Sandbox CLI, Sandbox MCP config, provider keys, Docker, and optional orchestrator availability.
• Direct code graph access: snipara-companion code callers, imports, neighbors, and shortest-path.
• Local code overlays: snipara-companion code status, sync, upload, hooks, and promote make local commits and dirty working-tree structure visible as non-canonical context while the hosted CODE graph catches up.
• Safe parallel coding: snipara-companion collaboration commands publish presence, create leases, run guard checks, install blocking Git hooks, and keep active leases heartbeated while work is in progress.
• Mini Snipara local bridges: snipara-companion memory local delegates to the open snipara-memory engine, while snipara-companion eval export and eval run create and run localsnipara-evals cases.
• 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.

Local code overlays

Hosted snipara_code_* tools remain canonical and answer from indexed CODE documents. Companion overlays cover the gap before a local commit or dirty working tree has been pushed and reindexed. They are marked canonical: false, have TTL expiry, redact the local absolute repo path before hosted upload, and never replace hosted project truth.

snipara-companion code status --json

snipara-companion code sync --working-tree --json

snipara-companion code upload --ttl-hours 4 --json

snipara-companion code hooks install --json

snipara-companion code promote --pushed-sha HEAD --request-reindex --json

Use code upload when another agent or hosted workflow needs to see the same local overlay. Managed hooks run local sync and push-time promotion in the background by default; use code promote manually after push only when hooks or GitHub auto-sync are unavailable.

Safe parallel coding

Companion can coordinate humans and agents working in the same repository through hosted collaboration state: active sessions, resource leases, guard evaluations, conflict alarms, blocking Git hooks, and IDE-ready status JSON. Use it when overlap would be expensive, such as schema, deployment, auth, billing, package release, or heavily shared route work.

snipara-companion collaboration watch --summary "Refactor auth middleware" --files apps/web/src/lib/auth.ts

snipara-companion collaboration claim --mode EXCLUSIVE --ttl-seconds 600 --resource FILE:apps/web/src/lib/auth.ts

snipara-companion collaboration guard --profile pre-push --enforce

snipara-companion collaboration hooks install

Blocking leases are time-bound. EXCLUSIVE and HARD_BLOCK leases default to a 300 second TTL when no explicit TTL is supplied. Heartbeats renew the expiry, and expired leases stop acting as active blockers. See Safe Parallel Coding for the full contract.

Mini Snipara local bridges

Companion also exposes thin bridges for the local open stack. These commands are useful when a team wants local memory or deterministic Project Intelligence eval cases without turning the hosted code graph into a local package.

snipara-companion memory local -- version

snipara-companion eval export --summary "Implemented auth hardening" --verification "pnpm test" --output .snipara/evals/auth-hardening.json

snipara-companion eval run .snipara/evals/auth-hardening.json --strict

Quick start

snipara-companion status

snipara-companion brief --task "add Jira issue-aware context" --changed-files src/context.ts

snipara-companion timeline

snipara-companion handoff --summary "tests green" --next "run release checks"

npx -y snipara-companion@latest query --query "who calls src.mcp_transport.handle_call_tool" --follow-recommendation

npx -y snipara-companion@latest workflow run --mode standard --query "map the auth callers"

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

snipara-companion workflow run --mode orchestrate --query "map rollout risks"

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 workflow ergonomics. snipara-orchestrator is a Python package for advanced production validation, htasks, and orchestration. Companion should call out the handoff when useful; it should not carry the orchestrator implementation or install it silently.

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 status, briefs, timelines, phase commits, handoffs, code graph routing, or workflow presets are useful.
• Add Snipara Sandbox when the workflow needs local execution, tests, lint, or sandboxed validation. Companion can suggest Sandbox and diagnose local readiness, but Sandbox remains a separate execution layer.
• Reach for snipara-orchestrator only when you need proof-based validation, drift detection, hierarchical tasks, or production gates.

Related guides

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