ContextSwitch snapshots your entire developer context — git state, open files, running processes, failing tests, and recent TODOs — so you can switch branches fearlessly and pick up exactly where you left off.

✨ The Problem

You're deep in a feature branch. 6 files open, a failing test you're debugging, npm run dev humming in the background. Then someone asks you to review a hotfix on main.

You switch branches, fix the issue, switch back — and now you're staring at a blank slate. What file was I in? What was failing? What was I even doing?

ContextSwitch remembers everything for you.

🚀 Quick Start

# Install globally
npm install -g @abhi5404/contextswitch

# Save your context before switching away
ctx save "debugging auth token refresh"

# Switch branches, do your work...
git checkout main

# Come back and restore everything
git checkout feature/auth
ctx restore

That's it. Your files reopen, your git stash pops, and you get a full summary of where you left off.

📦 Installation

# npm
npm install -g @abhi5404/contextswitch

# npx (no install needed)
npx @abhi5404/contextswitch save "my note"

Requirements: Node.js 16+ and Git

🛠️ Commands

ctx save [note]

Snapshots your full developer context for the current branch.

ctx save                           # save without a note
ctx save "halfway through refactor" # save with a note
ctx save --no-stash                # skip git stash (keep changes unstaged)

What gets captured:

| Layer | Details | |-------|---------| | 🌿 Git | Branch, commit SHA, modified files, untracked files, auto-stash | | 📝 Editor | Open files and cursor positions (VS Code) | | 💻 Terminal | Last 5 commands from shell history | | 🔄 Processes | Running dev servers (node, vite, next, webpack, jest, nodemon…) | | 🧪 Tests | Last failing test from Jest cache | | 📌 TODOs | Recent TODO, FIXME, HACK, XXX comments in your code |

ctx restore [branch]

Restores a previously saved context.

ctx restore                        # restore most recent context
ctx restore feature/auth           # restore a specific branch's context
ctx restore --rebase               # rebase onto main before restoring
ctx restore --no-processes         # skip process restart suggestions

What gets restored:

• ✅ Checks out the branch
• ✅ Pops the saved git stash
• ✅ Reopens files in VS Code at the exact line
• ✅ Lists processes that were running
• ✅ Shows configured restart commands
• ✅ Prints a full "where you left off" summary

ctx where

Shows what you were doing on the current branch — without restoring anything.

  where you left off

  ─────────────────────────────────────
  branch   feature/auth
  saved    23 minutes ago
  note     debugging auth token refresh
  last in  src/auth/refresh.js:47
  last cmd npm test -- --watch
  
  failing test you were working on:
  src/auth/__tests__/refresh.test.js › should retry on 401

  recent TODO you added:
  src/auth/refresh.js:52  handle edge case where token expires mid-request

  uncommitted when you saved:
  • src/auth/refresh.js
  • src/auth/middleware.js
  ─────────────────────────────────────

ctx list

Shows all saved contexts across branches.

  saved contexts

  feature/auth ← current
  23m ago · 6 files open · 1 failing test · "debugging auth token refresh"

  fix/nav-crash (branch deleted)
  2d ago · 3 files open · "quick nav fix"

  feature/dashboard
  5d ago · 8 files open

ctx clean

Removes saved contexts for branches that no longer exist locally.

ctx clean
#  cleaned contexts
#  removed fix/nav-crash
#  removed experiment/old-api

⚙️ Configuration

Create .ctx/config.json in your project root to auto-suggest restart commands when restoring a branch:

{
  "onRestore": {
    "feature/*": ["npm run dev", "npm run db:seed"],
    "fix/*": ["npm run dev"],
    "main": ["npm run build"]
  }
}

Branch patterns support wildcards (*), so feature/* matches feature/auth, feature/dashboard, etc.

🏗️ Architecture

contextswitch/
├── bin/ctx.js              # CLI entry point
├── src/
│   ├── index.js            # Public API
│   ├── store.js            # JSON file storage (.ctx/ directory)
│   ├── cli/
│   │   ├── commands.js     # Commander.js command definitions
│   │   └── flags.js        # Option normalization
│   ├── capturers/          # Context capture modules
│   │   ├── git.js          # Branch, status, stash
│   │   ├── editor.js       # VS Code open files
│   │   ├── terminal.js     # Shell history & running processes
│   │   ├── tests.js        # Jest test results
│   │   └── todos.js        # TODO/FIXME scanner
│   └── restorers/          # Context restore modules
│       ├── git.js          # Checkout, stash pop, rebase
│       ├── editor.js       # Reopen files in VS Code
│       ├── terminal.js     # Process restart suggestions
│       └── summary.js      # "Where you left off" display

How it works

1. Save → Each capturer module collects its slice of context. Everything is serialized to .ctx/<branch-name>.json.
2. Restore → The branch is checked out, stash is popped, files are reopened in your editor, and a full summary is printed.
3. Storage → All data lives in .ctx/ inside your project (auto-added to .gitignore). No cloud, no accounts, no telemetry.

🔒 Privacy

ContextSwitch is 100% local. Your context data never leaves your machine.

• All data stored in .ctx/ inside your project
• Automatically added to .gitignore
• No network requests, no analytics, no telemetry
• No accounts or sign-ups

🐚 Shell Support

| Shell | History Capture | Platform | |-------|----------------|----------| | PowerShell | ✅ PSReadLine history | Windows | | Zsh | ✅ .zsh_history | macOS / Linux | | Bash | ✅ .bash_history | macOS / Linux | | Fish | ✅ fish_history | macOS / Linux |

🤝 Contributing

Contributions are welcome! Feel free to open issues and pull requests.

# Clone the repo
git clone https://github.com/abhi5404/ContextSwitch.git
cd ContextSwitch

# Install dependencies
npm install

# Link for local development
npm link

# Now 'ctx' command is available globally for testing
ctx save "testing my changes"

📄 License

MIT — use it however you want.