codeedit

Structural code edits for coding agents: a better sed that reads the syntax tree.

Install · Usage · Python · Agent skill · Performance

Agents edit code with sed and hand-counted line ranges, and break it. codeedit parses the file with tree-sitter, finds code by symbol or by a pattern written as code, and applies the edit only if it is fresh, does not overlap another edit, and adds no syntax error. Every edit comes back as a unified diff. One Rust core sits behind the codeedit CLI and the codeedit Python package.

Highlights

• Edit by symbol: replace, insert, delete, rename and add-import address Greeter.greet, impl Point or List.Push, with decorators, attributes and doc comments attached.
• Edit by pattern: $E.unwrap() → $E? across a directory; $A matches one node, $$$A any number, where filters by regex or node type.
• Safe by default: stale, overlapping or syntax-breaking edits are rejected; multi-file changes are written all or nothing.
• Syntax tree as JSON: every node with type, field, position, byte range and text; also S-expression, XML and Graphviz.
• Structure beyond code: outlines and key edits for JSON and YAML, sections for Markdown, elements for HTML and XML; Markdown JSON dumps include inline nodes.
• Raw tree-sitter queries when patterns are not enough.
• 13 languages: Rust, Go, Python, TypeScript, TSX, JavaScript/JSX, Zig, Bash, JSON, YAML, XML, HTML, Markdown.

Install

pip install codeedit                                            # Python package, abi3 wheels for 3.13+
cargo install --git https://github.com/4thel00z/codeedit codeedit-cli   # the `codeedit` binary

Prebuilt codeedit binaries for Linux, macOS and Windows are attached to every release.

Usage

codeedit outline src/app.py                          # classes, functions, methods as JSON
codeedit get     src/app.py Greeter.greet            # one symbol and its source
codeedit replace src/app.py Greeter.greet --body -c 'return f"hi {self.name}"'
codeedit insert  src/app.py Greeter.greet --position after -c 'def bye(self): ...'
codeedit delete  src/app.py old_helper
codeedit add-import src/app.py 'from pathlib import Path'
codeedit rename  src --from fetch --to load -n       # -n previews the diff

codeedit find    src -p 'print($$$ARGS)'             # matches and bindings as JSON
codeedit rewrite src -p '$E.unwrap()' -r '$E?'
codeedit query   src -q '(call_expression function: (identifier) @f)'
codeedit parse   src/lib.rs -f json                  # or sexp, xml, dot

Batches go in as JSON and are checked together before anything is written:

codeedit edit - <<'EOF'
[{"op": "replace_body", "file": "a.py", "symbol": "f", "code": "return 1"},
 {"op": "add_import", "file": "a.py", "import": "import os"}]
EOF

Python

import codeedit

tree = codeedit.parse("def f(): return 1", "python")            # syntax tree as dicts
codeedit.outline("src/app.py")                                  # symbols
codeedit.replace_body("src/app.py", "Greeter.greet", "return 'hi'")
codeedit.rewrite("src", "$E.unwrap()", "$E?", dry_run=True)     # list of {file, diff, ...}
change = codeedit.rewrite_source("foo(1)\n", "python", "foo($A)", "bar($A)")

Agent skill

.claude/skills/codeedit/SKILL.md teaches a coding agent every command and its pitfalls. Link it into your agent's skill directory:

ln -s "$PWD/.claude/skills/codeedit" ~/.claude/skills/codeedit

Performance

Release build on an Apple M3 Pro:

Development

uv sync                                  # builds the extension into .venv
uv run pytest
cargo test --workspace --exclude codeedit-python
cargo clippy --workspace --all-targets -- -D warnings

CI runs clippy, tests on Linux and macOS, pytest, a wheel and a binary smoke test. Releases are cut by release-please from conventional commits: merging its release PR tags the version, attaches codeedit binaries, and publishes wheels to PyPI through trusted publishing.

License

MIT. The vendored tree-sitter runtime and all grammars are MIT as well; see vendor/tree-sitter/UPSTREAM for the one local patch.