Workflow Modes

Snipara offers two workflow modes optimized for different task complexities. Choose LITE for quick fixes, FULL for complex features that need durable memory, automation, and review.

Run With snipara-companion

You can follow the workflow manually through MCP tools, or use the optional snipara-companion npm package as a local workflow shortcut. The installed command is snipara-companion; there is no separate snipara-workflow binary.

npx -y snipara-companion@latest workflow run --mode auto --query "who imports the auth middleware"

npx -y snipara-companion@latest workflow run --mode full --include-session-context --query "plan the billing refactor"

npx -y snipara-companion@latest doctor

auto runs a context query and automatically executes a recommended structural tool when Snipara returns one. full adds durable memory bootstrap, optional session carryover, shared context when relevant, and a hosted execution plan.

For FULL, orchestrated, or execution-heavy tasks, companion prints an Snipara Sandbox hint when local validation would help. Use --no-runtime-hint for scripted output, and use snipara-companion doctor to check Snipara auth, Runtime CLI availability, Runtime MCP wiring, provider keys, and Docker.

Companion does not run Snipara Sandbox by itself. If the workflow needs sandboxed execution via execute_python, install and expose Snipara Sandbox with npx create-snipara repair --with-runtime, the create-snipara full-stack profile, or the Snipara Sandbox MCP server.

API Keys and Runtime Execution

Snipara context and Snipara Sandbox execution use different credentials. Keep them separate:

npx -y snipara-companion@latest task-commit --summary "Implemented the billing refactor and validated checkout tests" --files apps/web/src/lib/billing.ts

Use task-commit at the end of substantial work to persist durable outcomes. For Codex, companion remains optional: hosted MCP plus AGENTS.md is still the primary integration.

Quick Decision

Ask yourself these 4 questions:

Score 0-1 = LITE mode | Score 2+ = FULL mode

LITE Mode (Default)

Use for bug fixes, small features, single-session work, and tasks where you know exactly which files to modify.

LITE MODE WORKFLOW
──────────────────

1. snipara_context_query("your task")     # Get relevant context
2. Read specific files                 # Direct file access
3. Make changes                        # Edit code
4. Run tests locally                   # pnpm test / pytest

Token budget: ~3-5K from Snipara

LITE Mode Example

snipara_context_query(query="fix null check authentication")

# Read the specific file

# Edit to add null check

pnpm test

FULL Mode (Complex Features)

Use for multi-day features, architectural changes, team coordination, and documentation-heavy work that spans multiple sessions.

FULL MODE WORKFLOW
──────────────────

PHASE 1: CONTEXT GATHERING
├── snipara_shared_context()              # Team standards
├── snipara_recall("feature area")        # Past decisions
└── snipara_context_query(max_tokens=8000)# Deep context

PHASE 2: PLANNING
├── snipara_plan("feature description")   # Execution plan
├── snipara_decompose("feature")          # Break into tasks
└── snipara_remember(type="decision")     # Store key choices

PHASE 3: EXECUTION LOOP
├── snipara_inject("current context")     # Session focus
├── snipara_multi_query([...])            # Batch queries
├── execute_python(code)              # Test logic
└── Edit files locally                # Actual changes

PHASE 4: PERSIST DURABLE OUTCOMES
├── snipara_remember_if_novel(...)        # Skip duplicates
├── snipara_end_of_task_commit(...)       # Capture durable task outcome
└── Review inbox in dashboard         # When project policy = INBOX

Token budget: ~8-15K from Snipara

FULL Mode Example

# Phase 1: Context

snipara_shared_context(categories=["BEST_PRACTICES"])

snipara_recall(query="rate limiting decisions")

snipara_context_query(query="API middleware", max_tokens=8000)

# Phase 2: Plan

snipara_plan(query="implement rate limiting for API")

snipara_remember(type="decision", content="Using Redis sliding window")

# Phase 4: Implement

snipara_inject(context="Working on rate limiting, Redis backend")

snipara_multi_query(queries=[{query: "Redis patterns"}, ...])

# Phase 5: Persist durable outcome

snipara_end_of_task_commit(summary="Implemented Redis sliding-window rate limiting and left tests as the next step")

Mode Selection Examples

Session Continuity (FULL Mode)

FULL mode enables work that spans multiple sessions through the memory system.

Starting a New Session

snipara_recall(query="feature-name progress status")

snipara_context_query(query="feature-name")

Ending a Session

snipara_end_of_task_commit(
  summary="Feature X: Completed steps 1-3. Next: implement Y. Blocker: Z",
  outcome="partial",
  persist_types=["decision", "learning", "workflow"]
)

Tools Reference