SaveContext (CLI)

Save decisions, track progress, and maintain continuity across coding sessions using the sc command-line tool.

All commands use the sc binary. Add --json for structured JSON output.

Critical Rules

NEVER use sc session start when the user says "resume". The word "resume" (or "continue session", "pick up where I left off") ALWAYS means:

• sc session list --search "<topic>" to find the session

• sc session resume <session_id> to resume it

sc session start creates NEW sessions. Using it to "resume" almost always creates duplicates.

Quick Actions

User Says Do This

"save this decision" sc save "key" "value" -c decision -p high

"remember this" sc save "key" "value" -c note

"checkpoint" sc checkpoint create "name"

"wrap up" See WrapUp workflow

"resume [topic]" MUST sc session list --search "topic" then sc session resume <id>

"start session" sc session start "name" -d "description" (new sessions only)

"what went wrong" Check the error hint — includes suggestions, similar IDs

Error Handling

Errors include hints and suggestions. If an ID is not found, check the hint for similar IDs. When no session is active, the error lists recent resumable sessions.

Structured JSON errors are automatic when piped. See cli/AGENTS.md for error codes.

Command Cheatsheet

Sessions

sc session start "name" -d "description" # Start new session sc session list --search "query" # Find sessions sc session resume <id> # Resume paused session sc session pause # Pause current session sc session end # End session sc status # Current session + stats

Context Items

sc save "key" "value" -c decision -p high # Save context sc get -s "search query" # Smart semantic search (auto-decomposes) sc get -s "auth" --search-all-sessions # Search all sessions sc get -k "exact-key" # Get by key sc get -c decision -P high # Filter by category/priority sc update "key" --value "new value" # Update item sc delete "key" # Delete item

Search tips: Single keywords work best (sc get -s "auth"

sc get -s "authentication login session token handling" ). Smart search auto-decomposes multi-word queries, adapts thresholds, and expands scope when no results found.

Issues

sc issue create "title" -t task -p 2 # Create issue sc issue create "title" -t epic -p 3 # Create epic (container) sc issue create "subtask" --parent SC-xxxx # Create subtask under epic sc issue batch --json-input '{"issues":[...]}' # Batch with hierarchy sc issue list -s open # List open issues sc issue list --parent SC-xxxx # List subtasks of an epic sc issue claim <id> # Claim for work sc issue complete <id> # Mark complete sc issue complete <id> --reason "Done" # Complete with reason sc issue update <id> -s in_progress # Update status sc issue count # Count by status sc issue count --group-by type # Count by type/priority/assignee sc issue stale # Stale issues (7+ days default) sc issue stale --days 3 # Stale 3+ days sc issue blocked # Blocked issues + blockers sc issue dep tree <id> # Dependency tree sc issue dep tree # Trees for all epics

Checkpoints

sc checkpoint create "name" --include-git # Create checkpoint sc checkpoint list -s "query" # Find checkpoints sc checkpoint show <id> # Get details sc checkpoint restore <id> # Restore

Memory (persistent across sessions)

sc memory save "key" "value" -c command # Save memory sc memory get "key" # Get memory sc memory list # List all

Plans

sc plan create "title" --content "markdown" # Create plan sc plan list # List plans sc plan show <id> # Get plan details sc plan capture # Import plan from AI agent's plan file sc plan capture --agent claude --max-age 60 # Specific agent, 60min max age sc plan capture --file /path/to/plan.md # Explicit file path

Prime (full context)

sc prime # Full context aggregation sc prime --compact # Markdown for agent injection sc prime --smart --compact # Relevance-ranked within token budget sc prime --smart --compact --query "auth" # Semantic boost for topic sc prime --smart --compact --budget 2000 # Custom token budget sc prime --transcript # Include session transcripts

Workflow Routing

Workflow Trigger File

QuickSave "save", "remember", "note this" Workflows/QuickSave.md

SessionStart Starting work, "begin session" Workflows/SessionStart.md

WrapUp "wrap up", "end of day" Workflows/WrapUp.md

Resume "resume", "continue" Workflows/Resume.md

Compaction "prepare for compaction" Workflows/Compaction.md

IssueTracking "create issue", "track this bug" Workflows/IssueTracking.md

Planning "plan this feature" Workflows/Planning.md

FeatureLifecycle "implement", "build this", "plan and execute" Workflows/FeatureLifecycle.md

Prime "what's the full context", conversation start Workflows/Prime.md

Advanced Multi-day projects, multi-agent, branch switching, subagents Workflows/AdvancedWorkflows.md

Examples

Example 1: Quick save during work

User: "remember that we chose JWT over sessions for auth"

sc save "auth-decision" "Chose JWT over sessions for stateless scaling" -c decision -p high

Example 2: Starting a work session

User: "let's work on the payment feature"

sc session start "payment-feature" -d "Implementing Stripe integration"

Example 3: Wrapping up

User: "wrap up for today"

sc save "wrapup-2025-01-30" "Completed login flow. Next: rate limiting" -c progress sc checkpoint create "wrapup-2025-01-30" --include-git sc session pause

Do NOT Automatically

• Start sessions for quick saves (just save the item)

• Run multiple commands when one suffices

• Load full reference docs unless user asks how something works

Reference

Full CLI reference: Workflows/Reference.md