---
title: 'colab v2026.11.15: patterns, a language server in both directions, and an eval suite that prices every change'
url: https://www.grahambrooks.com/post/colab-2026-11-15-agent-refactoring/
date: 2026-11-21T09:00:00-07:00
author: Graham Brooks
description: 'colab v2026.11.15 is 92 commits in thirteen days: code-shape patterns with where constraints, language-server renames, moves and refactorings, Markdown edited by structure, repo-wide fixes and fleet migrations, and an eval suite that prices each change against Read and Edit.'
tags:
- developer-tools
- refactoring
- ai-agents
- rust
- mcp
---

# colab v2026.11.15: patterns, a language server in both directions, and an eval suite that prices every change

*If you give a coding agent a rename across forty files, it reads forty files. This release is mostly about giving it one command instead, and about measuring whether that's actually cheaper.*

**colab** is a scripted, syntax-aware refactoring tool. You hand it a small `.colab` script, or a one-line rule, and it rewrites a repository using tree-sitter syntax trees rather than regular expressions, across twelve languages (C, C++, C#, Go, Java, JavaScript/TypeScript, Kotlin, PHP, Python, Ruby, Rust and Swift), plus TOML, JSON and Markdown. A rule matches syntax, not text, so renaming a call rewrites the call sites and leaves strings and comments alone. It runs the same way from a terminal, in CI, or from an agent over MCP. The argument for why an agent should use it is in [the essay that goes with this release](https://www.grahambrooks.com/post/edits-an-agent-should-not-make-one-at-a-time/); this post is what changed.

v2026.11.15 was tagged on 15 November, thirteen days after v2026.11.3. It has 92 commits and touches 703 files (62,142 insertions, 2,132 deletions). A good share of that is tests, the eval tasks and docs, but most of it is new capability, which the [development plan](https://github.com/grahambrooks/colab/blob/main/docs/completed-milestones.md) tracks as milestones M14 to M35.

## Built to be driven by an agent

`colab agent install` wires colab into whichever agent it finds — Claude Code, Cursor or Codex — as an MCP server, a skill and, for Claude Code, a post-edit hook. `colab agent uninstall` takes it out again.

The MCP tools now follow the jobs agents actually get, not the DSL. `colab.move_import`, `colab.set_config_key` and `colab.rename_symbol` each take plain arguments, generate a one-rule script, run it and return the script alongside the result, so the first call needs no DSL and its answer shows how to write the next one. `colab.test_rule` runs a script against a snippet in memory and says whether the output matched what was expected.

Three smaller things matter more than they sound. Rules can be passed inline (`colab refactor -e 'match …'`), so an agent doesn't have to write a file first. Every command answers `--help-json`. And a rule that matched nothing now says what it saw instead: `colab` samples the files it scanned and reports the nearest names, so an agent that guessed `ParseConfg` is told about `ParseConfig` rather than getting a silent zero.

## Code shapes, and what's allowed to match

`pattern` matches a code shape with metavariables, in every language: `go::pattern 'errors.Wrap($E, $M)'`. `colab find` searches with the same patterns without rewriting anything, and `colab ast` prints the syntax tree when a pattern won't match and you need to see why.

Patterns take `where` constraints: a capture matching a regular expression, a match not inside a test function, neighbour and position conditions, and named patterns that a script can reuse. A rewrite keeps the layout of the code it replaces. Scan phases read across files: a `scan` collects what a pattern binds in every file, read-only, and a later rule edits only where `$X in` that set. Each rule still edits one file at a time.

## The language server, in both directions

colab now talks to each language's own server for the changes syntax can't decide. `colab rename` is the server's scope-aware rename, with whole-word mentions in comments, strings and docs listed separately and applied only when asked. `colab mv` moves a file with `git mv` and the server's reference edits, so the history and the imports both follow. `colab action` runs the server's code actions, such as extract function, and its safe delete, and `where $X type "…"` asks the server for a capture's type.

colab also runs the other way: `colab server` is a language server for `.colab` files, which underlines a broken rule in place, explains modules on hover, jumps to included scripts, and offers a code action that applies a rule to the workspace. Language servers are now kept running between commands by default. On colab's own crates, a references query through a fresh rust-analyzer takes 4.5 seconds, and 115 ms through one that's still running.

Before writing, every run checks for conflicts: a rename whose new name already occurs in the file, which would merge two names, and a template that introduces a qualifier (`fmt.`, `pathlib.`) the file doesn't import. A run with a conflict writes nothing and exits 11. `--verify-lsp` asks the language server for errors after the change and credits each one to the rule that caused it.

## Markdown by structure

Markdown is addressed by structure rather than by text an agent has to quote exactly: a section by its heading path, and table rows, list items, links and code fences within it. `colab mv-section` moves a section to another file. Every run checks the Markdown links it would break and treats each one as a conflict (`colab links` runs the check on its own; its first run on colab's docs found 11 broken links), and code rules can run inside fenced code blocks, so a rename reaches the examples in the README too.

## Repositories, CI and many repositories

A `colab.toml` at the repository root names the packs a repository follows, and `colab fix` runs them. Four idiom packs are built in — `go/1.18-modern`, `java/8-to-21`, `js/esm` and `python/3.12-typing` — and packs can come from git, pinned to a tag and checked against their own test cases before they run. `colab test` checks a repository's own packs the same way.

For CI there's `--format sarif` and `--format github` for annotations, rule ids with `--only`, `--off` and `--severity`, and `--baseline <ref>` to report only findings that are new since a git ref. Release archives now include Windows (`x86_64-pc-windows-msvc`) alongside macOS and Linux.

`colab review` summarises a run's changes rule by rule, and `refactor --split-pr` makes one branch per rule instead of writing (`--stacked` bases each on the one before), so a large migration lands as pull requests a reviewer can take one at a time. `colab fleet` runs one migration across many repositories from a manifest: a canary repository first, then the rest, each on its own branch with a pull request opened by `gh`.

## An eval suite that prices every change

`cargo test -p colab-cli --test evals` runs eight tasks an agent is typically given: rolling out a minimum toolchain, migrating Go from `pkg/errors` to `fmt`, renaming a symbol across code and docs, moving a crate to Rust 2024, and four more. Each is checked for exact output in a temporary git repository, and each fails if colab's cost grows past its budget.

The suite also prices the same change made with `Read` and `Edit`, and here the method matters more than the headline. Neither side is a live agent session. colab's side is the commands that work, run for real, with every byte they print counted. The `Read` + `Edit` side is priced by a model from the finished diff: one search, one 25-line read per file, one edit per hunk. On that basis colab used 73% fewer bytes over the eight tasks (8,161 against 29,882), and one task, extracting a function from a single file, came out 3% worse. Time is modelled too, so I'd treat the 4.5× speed figure as an estimate. Running real agents on these tasks is the next step.

## Upgrading

Scripts are now `.colab` files. `.codemod` files are still read, with a warning. npm and PyPI packages were built and tested during this release and then dropped; Homebrew, `cargo install` and the release archives remain the ways to install it.

```sh
brew tap grahambrooks/colab https://github.com/grahambrooks/colab
brew install colab
colab agent install
```

Since the tag, `main` has moved on by 20 commits: preview and undo in `colab server`, a three-way merge for files that change on disk during a run, OpenTelemetry traces of each run, and performance work that the essay compares against ast-grep. Those will be in the next release.
