ctx-switch 2.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to cc-continue
+
+Thanks for your interest in contributing!
+
+## Getting Started
+
+1. Fork the repo
+2. Clone your fork:
+   ```bash
+   git clone git@github.com:YOUR_USERNAME/cc-continue.git
+   cd cc-continue
+   ```
+3. Link it locally for testing:
+   ```bash
+   npm link
+   ```
+4. Make your changes
+5. Test by running `cc-continue` in a project directory where you've used Claude Code
+
+## Development
+
+This is a zero-dependency CLI tool built on Node.js built-ins. Keep it dependency-free unless there is a strong reason not to.
+
+### Project Structure
+
+```
+index.js              # CLI entrypoint
+src/                  # Internal modules
+test/                 # Node test suite + fixtures
+package.json
+README.md
+LICENSE
+```
+
+### Testing Your Changes
+
+```bash
+# Run the automated test suite
+npm test
+
+# Smoke test the CLI help
+npm run smoke:help
+
+# Check environment diagnostics
+cc-continue doctor
+
+# Inspect local sessions for the current project
+cc-continue sessions
+```
+
+## Guidelines
+
+- **Zero dependencies** — everything should use Node.js built-ins
+- **Don't break `--raw`** — the raw fallback must always work without a network call
+- **Keep fixtures realistic** — parser changes should be backed by JSONL fixtures from real Claude session shapes
+- **Preserve CLI ergonomics** — help text, error messages, and diagnostics are part of the product
+
+## Submitting a PR
+
+1. Create a branch: `git checkout -b my-feature`
+2. Make your changes
+3. Run `npm test`
+4. Smoke test `cc-continue --raw` in a real Claude project if your change touches parsing or prompt generation
+4. Push and open a PR
+
+## Ideas for Contributions
+
+- Additional provider adapters beyond OpenRouter
+- Session browsing and selection UX
+- Support for other session formats (Cursor, Windsurf, etc.)
+- Better large-session summarization strategies
+- JSON output modes for other automation workflows
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harshit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.cc-continue.md

@@ -0,0 +1,131 @@
+# cc-continue
+
+> **This package is being renamed to [`ctx-switch`](https://www.npmjs.com/package/ctx-switch).** Install `ctx-switch` for the latest version. `cc-continue` will continue to work but will no longer receive updates.
+
+Switch context between AI coding agents. Extract sessions from **Claude Code**, **Codex**, or **OpenCode** and generate a handoff prompt you can paste into any other AI agent to keep going.
+
+## The Problem
+
+You're deep in a coding session — the agent is editing files, running commands, making progress — and then:
+
+> **Usage limit reached. Please wait before sending more messages.**
+
+Your work is half-done. You can't continue. You switch to another AI agent but now you have to explain everything from scratch.
+
+## The Solution
+
+```bash
+npx cc-continue
+```
+
+Pick your source agent, and it reads the session, captures the current git state, and produces a structured continuation prompt that another agent can pick up immediately.
+
+## Features
+
+- **Multi-source**: Extract sessions from Claude Code, Codex, or OpenCode
+- **Interactive picker**: Choose your source agent, or pass `--source claude|codex|opencode`
+- **Smart session discovery**: Finds the latest session for the current project directory
+- Filters noise from user messages (confirmations, short replies, interruptions)
+- Tracks only **unresolved** errors — skips errors that were later fixed
+- Captures recent commits, committed diffs, staged/unstaged changes, and untracked files
+- Extracts key decisions and pivots from the previous agent
+- Produces a priority-ordered prompt: Task → Errors → Decisions → Completed Work → Current State → Instructions
+- Supports target-specific prompts with `--target codex|cursor|chatgpt|generic`
+- Auto-copies to clipboard on macOS, Linux, and Windows
+- Optional LLM refinement via `--refine` (uses OpenRouter)
+- `sessions` command to list recent sessions
+- `doctor` command for diagnostics
+
+## Install
+
+```bash
+# Recommended: use the new package name
+npm i -g ctx-switch
+
+# Or the legacy name (still works)
+npm i -g cc-continue
+npx cc-continue
+```
+
+## Usage
+
+```bash
+cd my-project
+
+# Interactive source picker (choose Claude/Codex/OpenCode)
+cc-continue
+
+# Specify the source directly
+cc-continue --source claude
+cc-continue --source codex
+cc-continue --source opencode
+
+# Target a specific agent for the output prompt
+cc-continue --source claude --target codex
+
+# Refine via OpenRouter LLM (optional)
+cc-continue --refine
+
+# List recent sessions
+cc-continue sessions --source claude --limit 5
+
+# Write to a file
+cc-continue --output ./handoff.md
+
+# Run diagnostics
+cc-continue doctor --source codex
+```
+
+### LLM Refinement (Optional)
+
+If you want the prompt refined by an LLM, use `--refine`. On first use, it'll ask for your OpenRouter API key:
+
+```
+Enter your OpenRouter API key: sk-or-v1-...
+Saved to ~/.ctx-switch.json
+```
+
+Get a free key at [openrouter.ai/keys](https://openrouter.ai/keys). You can also set it via environment variable:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+## Key Flags
+
+- `--source <name>` Session source: `claude`, `codex`, or `opencode` (interactive if omitted)
+- `--target <name>` Tailor the prompt for `generic`, `codex`, `cursor`, or `chatgpt`
+- `--output <file>` Write the prompt to a file
+- `--session <id|path>` Use a specific session
+- `--refine` Refine the prompt via an LLM provider
+- `--provider <name>` Refinement provider (default: `openrouter`)
+- `--model <name>` Override the provider model (default: `openrouter/free`)
+- `--api-key <key>` Override the API key for a single run
+
+## Session Storage
+
+| Source | Storage | Format |
+|--------|---------|--------|
+| Claude Code | `~/.claude/projects/<encoded-cwd>/*.jsonl` | JSONL |
+| Codex | `~/.codex/sessions/<year>/<month>/<day>/*.jsonl` | JSONL |
+| OpenCode | `~/.local/share/opencode/opencode.db` | SQLite |
+
+## Requirements
+
+- **Node.js** >= 18
+- **At least one of**: Claude Code, Codex, or OpenCode (must have been used in the current directory)
+- **sqlite3** (only needed for OpenCode sessions)
+- **OpenRouter API key** (only needed with `--refine`)
+
+## Migrating to ctx-switch
+
+```bash
+npm uninstall -g cc-continue
+npm i -g ctx-switch
+```
+
+Both `ctx-switch` and `cc-continue` commands work after installing either package.
+
+## License
+
+MIT

package/README.ctx-switch.md

@@ -0,0 +1,142 @@
+# ctx-switch
+
+> Formerly `cc-continue` — existing installs still work, just use `ctx-switch` going forward.
+
+Switch context between AI coding agents. Extract sessions from **Claude Code**, **Codex**, or **OpenCode** and generate a handoff prompt you can paste into any other AI agent to keep going.
+
+## The Problem
+
+You're deep in a coding session — the agent is editing files, running commands, making progress — and then:
+
+> **Usage limit reached. Please wait before sending more messages.**
+
+Your work is half-done. You can't continue. You switch to another AI agent but now you have to explain everything from scratch.
+
+## The Solution
+
+```bash
+npx ctx-switch
+```
+
+Pick your source agent, and it reads the session, captures the current git state, and produces a structured continuation prompt that another agent can pick up immediately.
+
+## Features
+
+- **Multi-source**: Extract sessions from Claude Code, Codex, or OpenCode
+- **Interactive picker**: Choose your source agent, or pass `--source claude|codex|opencode`
+- **Smart session discovery**: Finds the latest session for the current project directory
+- Filters noise from user messages (confirmations, short replies, interruptions)
+- Tracks only **unresolved** errors — skips errors that were later fixed
+- Captures recent commits, committed diffs, staged/unstaged changes, and untracked files
+- Extracts key decisions and pivots from the previous agent
+- Produces a priority-ordered prompt: Task → Errors → Decisions → Completed Work → Current State → Instructions
+- Supports target-specific prompts with `--target codex|cursor|chatgpt|generic`
+- Auto-copies to clipboard on macOS, Linux, and Windows
+- Optional LLM refinement via `--refine` (uses OpenRouter)
+- `sessions` command to list recent sessions
+- `doctor` command for diagnostics
+
+## How It Works
+
+1. You pick the source agent (Claude Code, Codex, or OpenCode)
+2. Finds the most recent session for your current project directory
+3. Parses the conversation — user messages, tool calls, errors, and results
+4. Captures the current git state: branch, commits, diffs, untracked files
+5. Builds a structured prompt optimized for agent handoff
+6. Copies to clipboard and prints to stdout
+
+## Install
+
+```bash
+# Run directly (no install needed)
+npx ctx-switch
+
+# Or install globally
+npm i -g ctx-switch
+```
+
+## Usage
+
+```bash
+cd my-project
+
+# Interactive source picker (choose Claude/Codex/OpenCode)
+ctx-switch
+
+# Specify the source directly
+ctx-switch --source claude
+ctx-switch --source codex
+ctx-switch --source opencode
+
+# Target a specific agent for the output prompt
+ctx-switch --source claude --target codex
+
+# Pick a specific session
+ctx-switch --source claude --session 4474da94-50a9-40de-9afe-c6c73acf2401
+
+# Refine via OpenRouter LLM (optional)
+ctx-switch --refine
+
+# List recent sessions
+ctx-switch sessions --source claude --limit 5
+
+# Write to a file
+ctx-switch --output ./handoff.md
+
+# Run diagnostics
+ctx-switch doctor --source codex
+```
+
+### LLM Refinement (Optional)
+
+If you want the prompt refined by an LLM, use `--refine`. On first use, it'll ask for your OpenRouter API key:
+
+```
+Enter your OpenRouter API key: sk-or-v1-...
+Saved to ~/.ctx-switch.json
+```
+
+Get a free key at [openrouter.ai/keys](https://openrouter.ai/keys). You can also set it via environment variable:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+## Key Flags
+
+- `--source <name>` Session source: `claude`, `codex`, or `opencode` (interactive if omitted)
+- `--target <name>` Tailor the prompt for `generic`, `codex`, `cursor`, or `chatgpt`
+- `--output <file>` Write the prompt to a file
+- `--session <id|path>` Use a specific session
+- `--refine` Refine the prompt via an LLM provider
+- `--provider <name>` Refinement provider (default: `openrouter`)
+- `--model <name>` Override the provider model (default: `openrouter/free`)
+- `--api-key <key>` Override the API key for a single run
+
+## Session Storage
+
+| Source | Storage | Format |
+|--------|---------|--------|
+| Claude Code | `~/.claude/projects/<encoded-cwd>/*.jsonl` | JSONL |
+| Codex | `~/.codex/sessions/<year>/<month>/<day>/*.jsonl` | JSONL |
+| OpenCode | `~/.local/share/opencode/opencode.db` | SQLite |
+
+## Requirements
+
+- **Node.js** >= 18
+- **At least one of**: Claude Code, Codex, or OpenCode (must have been used in the current directory)
+- **sqlite3** (only needed for OpenCode sessions)
+- **OpenRouter API key** (only needed with `--refine`)
+
+## Migrating from cc-continue
+
+`cc-continue` still works — it's an alias for `ctx-switch`. You'll see a one-line deprecation notice reminding you to switch. No other changes needed.
+
+```bash
+npm uninstall -g cc-continue
+npm i -g ctx-switch
+```
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,193 @@
+# ctx-switch
+
+> Formerly `cc-continue` — existing installs still work, just use `ctx-switch` going forward.
+
+**Switch coding agents without losing context.**
+Agent handoff for Claude Code, Codex, and OpenCode.
+
+## Why this exists
+
+You're in the middle of a coding session. Things are working. Progress is being made.
+
+And then you need to switch.
+
+- Maybe the session can't continue
+- Maybe something isn't working as expected
+- Maybe you just want to move to another agent
+
+Now you're stuck.
+
+You switch to another agent — but:
+
+- it has no context
+- you have to explain everything again
+- you lose momentum
+
+**Your work shouldn't reset just because you switched tools.**
+
+## What ctx-switch does
+
+```bash
+npx ctx-switch
+```
+
+It captures your current session — code, context, decisions, errors — and generates a clean, structured handoff prompt so another agent can continue immediately.
+
+No re-explaining.
+No rebuilding context.
+No wasted time.
+
+**Just continue where you left off.**
+
+### Core idea
+
+> Switch agents. Don't restart.
+
+## Features
+
+- **Multi-agent support**: Claude Code, Codex, OpenCode
+- **Smart session detection**: Finds the latest session for your current project
+- **Context extraction**:
+  - Filters noise (confirmations, filler)
+  - Keeps only relevant context
+- **Error awareness**:
+  - Includes unresolved errors
+  - Skips already-fixed issues
+- **Codebase state capture**:
+  - Recent commits
+  - Diffs (staged & unstaged)
+  - Untracked files
+- **Decision tracking**:
+  - Extracts key decisions and pivots
+- **Structured output**:
+  - Task → Errors → Decisions → Completed Work → Current State → Instructions
+- **Target-aware prompts**:
+  - `codex`, `cursor`, `chatgpt`, or `generic`
+- **Clipboard ready**: Auto-copy across macOS, Linux, Windows
+- **Optional LLM refinement** (`--refine`)
+- `sessions` command to browse recent sessions
+- `doctor` command for diagnostics
+
+## How it works
+
+1. Select your source agent (Claude / Codex / OpenCode)
+2. `ctx-switch` finds the latest session for your project
+3. Parses:
+   - conversation
+   - tool calls
+   - errors
+4. Captures git state:
+   - branch
+   - commits
+   - diffs
+5. Builds a structured handoff prompt
+6. Copies it to clipboard and prints it
+
+## Install
+
+```bash
+# Run instantly
+npx ctx-switch
+
+# Or install globally
+npm i -g ctx-switch
+```
+
+## Usage
+
+```bash
+cd my-project
+
+# Interactive mode
+ctx-switch
+
+# Specify source
+ctx-switch --source claude
+ctx-switch --source codex
+ctx-switch --source opencode
+
+# Target a specific agent
+ctx-switch --source claude --target codex
+
+# Use a specific session
+ctx-switch --source claude --session <id>
+
+# Refine output with LLM
+ctx-switch --refine
+
+# List sessions
+ctx-switch sessions --source claude --limit 5
+
+# Save to a file
+ctx-switch --output ./handoff.md
+
+# Run diagnostics
+ctx-switch doctor --source codex
+```
+
+## Example use cases
+
+- Continue work in another agent when switching is needed
+- Move a session across tools without re-explaining everything
+- Resume work seamlessly in a different environment
+- Preserve context when changing workflows
+
+## LLM Refinement (Optional)
+
+Use `--refine` to improve the generated prompt via an LLM.
+
+On first use:
+
+```
+Enter your OpenRouter API key: sk-or-v1-...
+Saved to ~/.ctx-switch.json
+```
+
+Get a key: [openrouter.ai/keys](https://openrouter.ai/keys)
+
+Or set manually:
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+## Key Flags
+
+| Flag | Description |
+|------|-------------|
+| `--source <name>` | `claude`, `codex`, `opencode` |
+| `--target <name>` | `generic`, `codex`, `cursor`, `chatgpt` |
+| `--output <file>` | Save prompt |
+| `--session <id\|path>` | Use specific session |
+| `--refine` | Refine prompt via LLM |
+| `--provider` | Refinement provider (default: `openrouter`) |
+| `--model` | Override model |
+| `--api-key` | Override API key |
+
+## Session Storage
+
+| Source | Storage Path | Format |
+|--------|-------------|--------|
+| Claude Code | `~/.claude/projects/<encoded-cwd>/*.jsonl` | JSONL |
+| Codex | `~/.codex/sessions/<year>/<month>/<day>/*.jsonl` | JSONL |
+| OpenCode | `~/.local/share/opencode/opencode.db` | SQLite |
+
+## Requirements
+
+- **Node.js** >= 18
+- **Claude Code, Codex, or OpenCode** (used in current directory)
+- **sqlite3** (only for OpenCode sessions)
+- **OpenRouter API key** (only if using `--refine`)
+
+## Migrating from cc-continue
+
+`cc-continue` still works — it's now an alias for `ctx-switch`.
+
+```bash
+npm uninstall -g cc-continue
+npm i -g ctx-switch
+```
+
+## License
+
+MIT