scope-capture
A Clojure(Script) library that saves and restores local runtime environments at the REPL for easier debugging and exploration.
What is scope-capture?
Scope-capture is a Clojure and ClojureScript library that helps developers save and restore the local runtime environment of their code at the REPL. It solves the tedious problem of manually recreating variable contexts during debugging by capturing snapshots when code executes, allowing instant replay for investigation.
Clojure and ClojureScript developers who use REPL-driven workflows, particularly those debugging complex functions, onboarding to new projects, or exploring unfamiliar codebases.
Developers choose scope-capture because it automates environment recreation, reducing manual effort and errors. Its unique selling point is enabling context restoration after just one code execution, making debugging more immediate and accessible.
Overview
Project your Clojure(Script) REPL into the same context as your code when it ran
Use Cases
Best For
- Debugging Clojure functions with many local variables
- Exploring unfamiliar codebases without deep project knowledge
- REPL-driven development with breakpoint-like pausing
- Onboarding new developers to Clojure projects
- Running one-off queries in the context of existing code
- Interactive experimentation with captured runtime scopes
Not Ideal For
- Projects that rely solely on graphical debuggers with step-through interfaces and watch windows
- ClojureScript applications with complex, stateful browser REPLs where code site ID management is cumbersome
- Production deployments or shared development environments where global variable pollution from defsc poses risks
- Teams seeking a zero-configuration, drop-in debugging tool without modifying user profiles or local setups
Pros & Cons
Pros
sc.api/spy and sc.api/brk macros automatically save local environments during code execution, eliminating manual variable recreation as shown in the basic usage example.
Offers multiple restoration methods: sc.api/letsc for local bindings and sc.api/defsc for global vars, catering to different REPL workflows and editor integrations.
sc.api/brk pauses execution and allows resumption from the REPL with override values via sc.api/loose-with!, enabling step-through debugging without external tools.
Lowers the barrier for new developers by enabling mechanical environment recreation without deep project knowledge, as emphasized in the rationale section.
Works with both Clojure and ClojureScript, including browser-connected REPLs, though with specific caveats for ClojureScript usage.
Cons
Requires explicit code site IDs in ClojureScript (e.g., sc.api/letsc [7 -3]), which is non-intuitive and error-prone, as admitted in the README's caveats.
Must be added to user profiles (e.g., ~/.lein/profiles.clj) rather than project dependencies, complicating setup and team-wide adoption compared to simple dependency management.
sc.api/defsc overwrites global vars with captured locals, risking conflicts with existing definitions and making it unsuitable for shared or production-like environments.
Dynamic vars require manual declaration for capture (e.g., :sc/dynamic-vars option), adding boilerplate and potential for missed bindings in complex applications.
Frequently Asked Questions
Related Projects
lein-figwheelFigwheel builds your ClojureScript code and hot loads it into the browser as you are coding!
ultraA Leiningen plugin for a superior development environment
prettyLibrary for helping print things prettily, in Clojure - ANSI fonts, formatted exceptions
spyscopeTrace-oriented debugging tools for Clojure
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.