Skillget

mindswap

mcp
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 6 GitHub stars
Code Fail
  • os.homedir — User home directory access in bin/mindswap.js
  • fs module — File system access in bin/mindswap.js
  • fs module — File system access in src/ask.js
  • child_process — Shell command execution capability in src/build-test.js
  • execSync — Synchronous shell command execution in src/build-test.js
  • process.env — Environment variable access in src/build-test.js
  • fs module — File system access in src/build-test.js
  • fs module — File system access in src/checkpoint.js
  • fs module — File system access in src/conflicts.js
  • fs module — File system access in src/contracts.js
  • fs module — File system access in src/decisions.js
  • process.env — Environment variable access in src/detect-ai.js
  • fs module — File system access in src/detect-ai.js
Permissions Pass
  • Permissions — No dangerous permissions requested
Purpose
This MCP server and CLI acts as a "black box recorder" for AI coding assistants. It captures your project's current state—like git context, dependencies, and architectural decisions—and generates handoff files so you can seamlessly switch between different AI tools (like Cursor, Copilot, or Claude) without losing context.

Security Assessment
Overall risk: Medium. The tool is heavily reliant on local file system access, which is expected given its core function of reading project states and writing context files across multiple directories. However, there are a few security concerns. It accesses the user's home directory and environment variables, and it contains synchronous shell command execution capabilities. Fortunately, the dangerous command execution appears isolated within build and test scripts rather than the core runtime code. No dangerous permissions or hardcoded secrets were detected, and no outbound network requests were flagged.

Quality Assessment
The project is licensed under the standard MIT license and was actively updated recently. However, community trust is currently very low. With only 6 GitHub stars, the tool has extremely low visibility and has not yet been widely vetted by the open-source community.

Verdict
Use with caution: The tool functions largely as intended for local file generation, but its low community adoption and local system access require a thorough code review before integrating it into sensitive environments.
SUMMARY

Your AI's black box recorder. CLI + MCP server for AI handoffs across Claude Code, Cursor, Codex, Copilot, and more.

README.md

mindswap

npm version
License: MIT

Your AI's black box recorder. CLI + MCP server.

One command captures your entire project state. Switch between Claude Code, Cursor, Copilot, Codex — the next AI picks up instantly. Zero re-explaining.

mindswap demo 

npm install mindswap --save-dev
npx mindswap init        # once — auto-detects everything
npx mindswap ask "Why did we choose JWT?"  # answer from project memory with cited matches
npx mindswap             # save state when switching tools
npx mindswap doctor      # diagnose setup, context freshness, and gaps
npx mindswap mcp-install # enable MCP for Claude Code / Cursor

The problem

You're mid-feature in Codex. Tokens run out. You switch to Claude Code. It has zero context — doesn't know your architecture, your decisions, or that you're halfway through implementing auth middleware.

You spend 20 minutes re-explaining. Every. Single. Time.

The solution

Just run mindswap. That's it.

$ npx mindswap

⚡ Saving project state...

  Task:      user auth (auto-detected from branch)
  Branch:    feat/user-auth
  Changed:   4 files
  Tests:     ✓ 12 passed, 0 failed
  Decisions: 2 auto-logged from deps

✓ State saved — ready to switch tools

It auto-detects your task from the branch name, captures git state, logs dependency changes as decisions, and generates context files for every AI tool:

AI Tool Generated File Behavior
Universal HANDOFF.md Full overwrite
Claude Code CLAUDE.md Safe merge
Cursor .cursor/rules/mindswap-context.mdc Own file
GitHub Copilot .github/copilot-instructions.md Safe merge
Codex CODEX.md Safe merge
Gemini CLI GEMINI.md Safe merge
Windsurf .windsurfrules Own file
Cline .cline/mindswap-context.md Own file
Roo Code .roo/rules/mindswap-context.md Own file
Aider CONVENTIONS.md Safe merge
Amp .amp/mindswap-context.md Own file
AGENTS.md AGENTS.md Safe merge

The entire flow

npx mindswap init     # once per project
npx mindswap resume   # get an action-oriented start-of-session briefing
npx mindswap doctor   # sanity-check setup and context health
npx mindswap          # when switching tools
npx mindswap done     # when feature is complete

Everything else is automatic — git hooks track commits, dependencies are auto-logged, branch state is auto-managed.

15 commands

Command Alias What it does
mindswap save THE one command. Auto-detects task, deps, state — generates all context files
mindswap init — Initialize. Auto-detects 30+ frameworks, imports existing AI context files
mindswap switch <tool> sw One-command tool switch — save + generate + open (cursor/claude/copilot/codex/windsurf)
mindswap done [msg] d Mark task complete, archive to history, reset to idle
mindswap log <msg> l Log a memory item. Decisions warn on conflicts; use --type for blockers, assumptions, questions, and resolutions
mindswap status s Current state — task, branch, build/test, conflicts. --stats for charts
mindswap doctor — Diagnose setup, hook health, stale context files, conflicts, and missing continuity signals. --json for automation
mindswap resume — Action-oriented briefing — state, blockers, and the next best move. --compact / --json
mindswap ask <question> — Semantic question answering from project memory and history. --json for machine use
mindswap contracts — Emit machine-readable interface contracts for the current workstream
mindswap sync — Push, pull, or inspect shared hub state. --push, --pull, --force, --hub
mindswap summary sum Full session narrative — task, commits, decisions, conflicts. --json for scripts
mindswap gen --all gen Generate context files for all AI tools. Safe merge — never overwrites
mindswap watch w Background watcher — auto-updates HANDOFF.md, or all context files with --all; --save runs a full save cycle
mindswap reset r Clear task state. Decisions preserved. --full to clear everything

Key features

Auto-everything

  • Task detection — from branch name (feat/user-auth → "user auth") + recent commits
  • Dependency tracking — added Stripe? Auto-logged. Removed Redis? Logged too. Works across JS/TS, Python, Go, Rust, and Ruby manifests.
  • Git hooks — auto-saves state on every commit

Branch-aware state

Each git branch has its own state. Switch to feat/payments — it loads that branch's task and decisions. Switch back to main — your main state is restored.

Team mode

Set MINDSWAP_TEAM=1 to make history author-aware and surface a team handoff section in generated context files.

Native session normalization

mindswap reads recent Claude Code and Codex session files, normalizes them into a structured model, and surfaces the last session's findings, blockers, and edited files in HANDOFF.md and MCP context.

Decision conflict detection

Log "NOT using Redis" then later "using Redis"? mindswap warns you. Also catches reversed choices and package.json contradictions.

Architectural guardrails

When your diff touches code that contradicts a recorded decision, mindswap warns you in save, doctor, generated handoff files, and MCP context. It is a proactive drift check, not just a static conflict log.

Interface contracts

mindswap contracts emits a machine-readable JSON contract for the active workstream, including boundaries, blockers, assumptions, and recent history so another agent can resume without re-reading the whole repo.

Shared sync

mindswap sync can push or pull a local JSON hub file so teams can share continuity state across machines. Conflicts are explicit, and doctor surfaces the sync health.

Structured memory

Not everything is a decision. mindswap now keeps structured memory for blockers, assumptions, open questions, and resolutions in .mindswap/memory.json, while keeping decisions.log for compatibility and conflict checks.

npx mindswap log "Need prod webhook secret" --type blocker
npx mindswap log "Assume single-region rollout for MVP" --type assumption
npx mindswap log "Should we rotate refresh tokens?" --type question
npx mindswap log "Moved to JWT after auth review" --type resolution

Generated context files surface unresolved blockers and questions separately so the next AI does not have to infer them from free-form notes.

Continuity diagnostics

npx mindswap doctor

Checks whether mindswap is initialized correctly, whether generated handoff files are stale, whether git hooks are installed, whether AI-tool-specific context files are missing, and whether conflicts or weak continuity signals need attention.

Semantic ask

npx mindswap ask "Why did we choose JWT?"

Answers natural-language questions against decisions, history, memory, and recent session context, then cites the strongest matching project records.

Safe merge

Already have a CLAUDE.md? mindswap appends its section inside <!-- mindswap:start/end --> markers. Your content is never touched.

Build/test tracking

npx mindswap --check   # runs tests, captures results
# Tests: ✓ 47 passed, 0 failed

The next AI knows "tests were passing" or exactly what's broken.

Auto-sync

mindswap switch records session start/end hooks when configured, and mindswap watch --save --all can run a full save + context refresh loop for deeper IDE/tool integration.

30+ frameworks detected

Next.js, Remix, Astro, SolidJS, Angular, NestJS, Express, Fastify, Hono, Django, FastAPI, Flask, Gin, Echo, GoFr, Fiber, Actix, Axum, Rails, Spring Boot, and more. Plus databases, monorepo tools, CI/CD, and infrastructure.

What lives in .mindswap/

.mindswap/
├── HANDOFF.md       ← any AI reads this
├── state.json       ← machine-readable state
├── decisions.log    ← decision log (kept for compatibility + conflicts)
├── memory.json      ← structured memory: blockers, assumptions, questions, resolutions
├── config.json      ← your preferences
├── branches/        ← per-branch state (auto)
└── history/         ← checkpoint timeline

Commit these (handoff context): state.json, decisions.log, memory.json, config.json, HANDOFF.md

Don't commit (auto-added to .gitignore): history/, branches/

MCP Server

AI tools can query mindswap natively via Model Context Protocol instead of reading static files. 3 tools, stdio transport.

npx mindswap mcp-install   # auto-configures Claude Code, Cursor, VS Code
MCP Tool When AI calls it What it returns
mindswap_get_context Session start — "What do I need to know?" Synthesized briefing: task, decisions, conflicts, tests, recent work, native session findings
mindswap_save_context Session end — "Here's what I did" Persists summary, decisions, next steps, blockers
mindswap_search Mid-session — "What did we decide about auth?" Searches decisions + history + state

Only 3 tools by design. Research shows AI accuracy drops from 82% to 73% past 20 tools. We chose quality over quantity.

Security

All generated context files are scanned for secrets before writing:

  • 25+ patterns: AWS keys, GitHub tokens, Stripe keys, OpenAI keys, DB URLs, private keys, JWT secrets, passwords
  • Auto-redacted — secrets never reach your HANDOFF.md
  • Placeholder-aware — skips YOUR_KEY_HERE patterns

PR Integration

npx mindswap pr   # adds context summary to your GitHub PR

Auto-injects task, decisions, test status into the PR description with safe markers.

FAQ

Will it overwrite my existing CLAUDE.md?
No. Uses <!-- mindswap:start/end --> markers. Your content is preserved.

Does it work with my AI tool?
If it reads markdown files (all of them do), yes.

Does it slow things down?
No. Only runs when you call it. Git hook runs silently on commit.

Multiple branches?
State is auto per-branch. Switch branches, state switches too.

What languages?
JS/TS, Python, Go, Rust, Ruby, Java/Kotlin. Auto-detects from project files.

License

MIT

Reviews (0)

No results found