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:

1. sc session list --search "<topic>" to find the session
2. sc session resume <session_id> to resume it

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

Quick Actions

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"                       # Semantic search
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

Issues

sc issue create "title" -t feature -p 2        # Create issue
sc issue list -s open                          # List issues
sc issue claim <id>                            # Claim for work
sc issue complete <id>                         # Mark complete
sc issue update <id> -s in_progress            # Update status

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

Prime (full context)

sc prime                                       # Full context aggregation
sc prime --compact                             # Markdown for agent injection
sc prime --transcript                          # Include session transcripts

Workflow Routing

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