snipara-companion

snipara-companionis the local runtime for Project Intelligence in agent work. It turns Snipara's hosted memory, local source activation, Code Graph, routing, verification, and outcome capture into terminal workflows your agent can start, inspect, hand off, and resume without rediscovering the repo.

npx create-snipara@latest init --client cursor --starter

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

snipara-companion source sync --json

snipara-companion continue-workspace --include-session-context --json

Project Intelligence loop

Companion is not another way to connect an agent. It is the terminal layer that turns Project Intelligence into a repeatable work loop: load the brief before editing, route or inspect impact, track progress, verify, record the outcome, then resume the next session from the same project state.

Git-style command model

The Git analogy is useful because it makes the runtime easy to operate. Companion 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 the terminal entrypoint for Project Intelligence before and during work.
• You want Start Work Brief, Code Graph impact, verification hints, and outcomes in one local workflow.
• You want compaction-safe phase commits for multi-step work.
• You want a local status, timeline, and handoff layer for agent sessions.
• You want a no-GitHub fallback that snapshots the local folder and refreshes a code overlay.
• You are targeting clients like Claude Code, Cursor, or ZCode with GLM.
• You want the installed snipara-companion command for local automation steps.
• You want automatic routing from natural-language structural queries into snipara_code_* tools.
• You want release policy gates and a Judgment Card before promotion or deployment.

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.
• Local source activation: snipara-companion source init ., source sync --json, and source status --json create a local source snapshot, document sync preview, and code overlay cache for folders with or without Git metadata.
• Release judgment: snipara-companion run --release composes the Project Intelligence brief, collaboration guard, package-surface review, verification plan, policy gates, and final Judgment Card before promotion.
• Agent Readiness Audit: snipara-companion agent-readiness audit creates a local readiness report with proof gaps, target posture, suggested commands, and a service-pack recommendation before work is delegated to Codex, Claude Code, Cursor, Orca, or a custom worker.
• Why/outcome capture preview: snipara-companion outcome-capture preview extracts review-pending decision/outcome candidates from commits, phase commits, handoffs, tests, deploy health, reviews, and explicit feedback without approving memory automatically. Add --emit-decisions to turn those candidates into local decision requests, or --emit-outcome-receipt to emit a typed Outcome Intelligence calibration receipt.
• Coding Intelligence Ledger export: snipara-companion intelligence ledger-export writes structured JSON for replay, review, and proof assets with secret-like content and local repo paths redacted before output.
• Producer Loop artifacts: workflow phase-commit and workflow final-commit emit local Producer Loop artifacts under .snipara/producer-loop/, and workflow producer-report summarizes adoption, reason codes, invalid artifacts, sample size, and calibration caveats before any hard gate.
• Decision requests: workflow producer-triage creates local questions under .snipara/decisions/, workflow decisions gives an LLM client the evidence/options to ask the human, including readable item summaries for batched reviews, and workflow decide records the response receipt. memory reviews --emit-decisions connects the hosted memory review queue, cleanup candidates, and duplicate candidates to the same question channel without mutating hosted memory. run --emit-policy-decisions uses that same agent-first channel for Project Policy require_review and block verdicts, so a human can approve once, require changes, respect the block, request an exception, or mark the cited policy stale. Requests never resolve by timeout/default and never grant producers a new canonical memory write path.
• 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. Add --adapter-pack --target codex to attach a portable ADE Adapter Pack.
• 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. lite runs with zero mandatory hosted calls, and auto routes by task intent.
• Outcome calibration: snipara-companion run can ingest Outcome Intelligence receipt JSON with --outcome-receipts and print local reason-code/task-profile calibration buckets. Hosted projects can also ingest those receipts through the Project Intelligence outcome-receipts API. Thin buckets stay advisory.
• Controlled worker execution: snipara-companion workers execute creates a proof-required Controlled Worker Execution receipt. It defaults to dry-run; --execute requires an approval receipt and blocks high-risk commands before recording any worker output.
• Plan bridge: snipara-companion plan --write-plan-file converts hosted snipara_plan output into managed workflow JSON; --start-workflow can register it immediately.
• 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. Add --emit-orchestrator-handoff on an adaptive routing dry run when the next step should be an explicit orchestrator gate.
• Adaptive Work Routing dry run: snipara-companion workflow run --adaptive-routing-dry-run can attach a provider-neutral routing card. Use --route-local-workers when a strong planner should keep reasoning while a local worker handles scoped implementation.
• 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, shortest-path, and impact use hosted MCP for clean indexed checkouts, select the local overlay for dirty or ahead worktrees, and report sourceSelection.
• 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. Use explicit code local ... commands only when debugging the overlay itself.
• Memory lifecycle correction: snipara-companion memory invalidate and memory supersede let agents mark stale hosted memory obsolete without deleting history.
• 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.

Agent Readiness Audit

snipara-companion agent-readiness audit is a local report for teams adopting AI coding agents. It checks whether a task has enough scope, context, workflow continuity, Team Sync state, proof gates, verification hints, and target-agent posture to be delegated safely.

snipara-companion agent-readiness audit \

--target codex \

--task "ship auth hardening" \

--changed-files apps/web/src/lib/auth.ts \

--proof "pnpm test auth" \

--acceptance "auth tests pass" --json

The audit reads explicit inputs plus local AGENTS.md, workflow, and Team Sync state. It does not validate hosted MCP auth, execute tests, create branches, or launch agents. Its output is a work contract and service-pack recommendation, not an automation claim.

ADE Adapter Pack

snipara-companion handoff --adapter-pack turns the normal handoff artifact into a target-specific contract for Codex, Claude Code, Cursor, Orca, Kimi Code CLI, or a custom worker. It carries target profile, runtimeControl: handoff_only, file scope, context references, conflict posture, proof gates, acceptance criteria, receipt expectations, and a prompt the receiving agent can follow.

snipara-companion handoff \

--summary "auth hardening ready" \

--next "run auth regression tests" \

--files apps/web/src/lib/auth.ts \

--attention proof --adapter-pack --target codex \

--proof "pnpm test auth" --acceptance "auth tests pass"

The Adapter Pack is portable by design. It does not install native hooks, control the target IDE, or launch hidden workers. The receiving agent must return a receipt before the delegated work can be treated as verified.

Release policy gates

snipara-companion run --release is the release-oriented entrypoint. It combines context, local code impact, collaboration state, package-surface review, verification hints, and the Judgment Card into one proceed or stop decision.

Policy gates make release, schema, auth, billing, deploy, and package risks explicit. Review-only guard findings can be acknowledged with the printed action card command; blocking leases, required acknowledgements, and hard policy blocks keep the release non-proceedable.

Project Policy and Decision Consistency add a typed receipt to that gate set. Companion can evaluate approved decision-derived rules against the current task and changed files, then emit allow, warn, require_review, or block. Blocking is reserved for high-confidence reviewed policy that matches a forbidden action; weaker matches stay review-required or advisory.

Add --emit-policy-decisions when the agent should turn those review/block findings into local Decision Requests. The response is resolved through workflow decide, records the human choice as a receipt, and leaves policy edits or stale-memory invalidation as explicit follow-up work instead of silently changing project truth.

Outcome Intelligence is the next calibration input. outcome-capture preview --emit-outcome-receipt can produce a local typed receipt from guard, review, test, deploy, feedback, or workflow evidence, and run --outcome-receipts groups those receipts by reason code, task kind, and risk. The result can rank or explain recommendations; it is not causal proof, global agent trust, canonical memory, or a Project Policy override.

snipara-companion run --release \

--task "ship auth hardening" \

--changed-files apps/web/src/lib/auth.ts \

--diff-summary "timing-safe auth check"

Proof packs and replay assets

Companion can package the same work loop into proof assets for a buyer, reviewer, or implementation team: readiness audit, adapter handoff, release gate, and Coding Intelligence Ledger. The ledger is structured replay data, not approved memory, causal proof, or a raw transcript.

Producer Loop artifacts make that ledger appear during real workflow commits. It is still local review evidence: it does not launch workers, write canonical Project Brain memory, provide server-side attestation, or claim advisor-grade calibrated confidence.

snipara-companion intelligence ledger-export \

--task "ship auth hardening" \

--changed-files apps/web/src/lib/auth.ts tests/auth.test.ts \

--served-context "source-backed Project Intelligence loaded before edit" \

--plan "run auth tests before closure" \

--test "pnpm test auth" --confidence 0.72 --json

For commercial packaging, keep public benchmark claims separate from internal agentic pilots. The proof pack can replay a sanitized workflow, but broad ROI, autonomy, or bug-reduction claims still need their own verified benchmark protocol.

Adaptive Work Routing

Companion can recommend when a task is suitable for a cheaper, cloud, or local worker. The output is a dry-run routing card and optional orchestrator handoff metadata. For bounded local attempts, workers execute can write an explicit execution receipt, but companion still does not launch hidden workers.

snipara-companion workflow run --mode full \

--adaptive-routing-dry-run --route-local-workers \

--emit-orchestrator-handoff \

--routing-worker-role coding --routing-preferred-endpoint local \

--planner-retains-reasoning "Update docs for the new gateway"

The routing contract uses requirements such as worker role, cost, endpoint type, context budget, and write scope. With --emit-orchestrator-handoff, companion writes the handoff metadata an explicit orchestrator gate can consume; execution and proof review still remain supervised. Controlled execution receipts add approval and proof evidence for local worker attempts. Project credentials remain server-side behind the hosted BYOM gateway. See Adaptive Work Routing for the full model.

Project Intelligence inputs 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 on demand: snipara-companion recall asks memory about past decisions and preferences, while snipara-companion session-bootstrap prints a compact pushed brief of durable decisions, learnings, preferences, and optional short-lived carryover. Empty briefs are silent in text mode.
• Commit memory after work: snipara-companion task-commit stores only durable outcomes, not raw specs or copied documents.
• Correct memory explicitly: snipara-companion memory invalidate <memory-id> and snipara-companion memory supersede <old-memory-id> <new-memory-id> call the hosted lifecycle tools when recalled knowledge is stale or replaced.
• 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. The unified snipara-companion code ... commands choose this overlay automatically for dirty or ahead worktrees, so agents do not need to force hosted impact for code the hosted graph cannot see yet.

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 plan --query "plan the auth refactor" --write-plan-file ./plan.json

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
• kimi

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?
• Project Intelligence Inputs
• Orchestrator guide
• OpenClaw guide