# clj-surgeon

clj-surgeon is a Babashka CLI for structural reads and refactors in Clojure, ClojureScript, and CLJC files. It parses source with [rewrite-clj](https://github.com/clj-commons/rewrite-clj) and returns EDN. Claude Code and Codex skills teach coding agents the shortest safe commands.

Use clj-surgeon to:

- inspect a namespace without reading the complete file - select one top-level form by name, line, or distinctive text - search and compute over nested Clojure forms - create a reviewed, hash-bound replacement plan and apply it separately - move forms with explicit dependency handling - reorder definitions to remove unnecessary `(declare ...)` forms - rename namespaces or extract forms to new files - inspect or transform reader-conditional code

The project began after a coding agent spent 45 minutes refactoring a 5,000-line `views.clj` file. The agent repeatedly read source to find, move, and order forms. The initial four-hour prototype had 13 operations and about 1,500 lines. The current implementation is larger and requires Babashka and clj-kondo. Those counts describe the prototype, not the current product.

## A structural editor for agents

Clojure source already contains named forms, nested expressions, dependency edges, and reader conditionals. A text-only workflow discards that structure. It searches for text, recovers a line number, prints a range, patches syntax, and rereads the file.

clj-surgeon gives coding agents a composable structural interface. `:ls` inventories a namespace. `:cat` returns one selected form. `:xray` reads or computes over a Clojure path.

`:grep-form` finds syntax instead of textual lookalikes. Dependency operations expose the graph. Write operations separate planning from application.

```text ls / cat / q / grep / deps → plan → apply → receipt ```

A write first produces a hash-bound plan and exact diff. A later command applies only that reviewed artifact. The apply receipt records the write, read-back hash, an