gotreesitter ships 206 grammars and 119 hand-written scanners
Pure Go tree-sitter runtime. It cross-compiles to any GOOS/GOARCH target Go supports, including wasip1.
At a glance
- What is it?
- A tree-sitter runtime rewritten in Go with no CGo, so it cross-compiles and lets the race detector see the parser. The page names a release with no tag, and the grammar count is higher than the number of languages whose lexing was hand-written.
- Who is it for?
- Use it if you need tree-sitter in a Go program that must build without a C toolchain, run under the race detector, or compile to WebAssembly. Judge the grammar coverage by the external scanner count rather than the headline: 206 grammars are registered and 119 have hand-written scanners, so the remainder depend on fallback lexing that the project documents separately.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- odvcencio/gotreesitter585 ★ · +42
| Repository | 2026-08-02 | 2026-11-15 |
|---|---|---|
| odvcencio/gotreesitter | 543 | 585 |
42 Stars in the last 105 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The page names v0.56.0 and the newest tag is v0.55.1
The README states that the current release is v0.56.0 and points at `docs/roadmap.md` for release scope and history. The published tags are v0.55.1 on 2026-09-26, v0.55.0 on 2026-09-24 and v0.54.0 on 2026-09-23.
So the page describes a version that has no tag behind it. Two readings are available: v0.56.0 is prepared but untagged, or the page was written ahead of the release. The commit record does not settle it, since the last push is dated 2026-10-01, five days after the newest tag, which is consistent with either.
The cadence itself is notable. Three releases in three days at the end of September suggests a burst of small-version work rather than a slow drip, and it means the gap between two tags may be a single behavioural change.
For anyone depending on this, the practical rule is to pin v0.55.1, since the version named in prose is not something `go get` can resolve to a tag. The project is MIT licensed, defaults to `main`, and its site is hosted on an `m31labs.dev` domain rather than a github.io address.
206 grammars, and 119 hand-written scanners
The feature list gives the count with a qualifier attached: 206 grammars, all producing error-free trees on smoke samples, of which 119 ship a hand-written Go external scanner.
The qualifier matters twice. First, the correctness claim is scoped to smoke samples, which is a small parse of each language rather than a corpus, so it rules out a broken grammar and does not rule out subtle misparses. Second, the gap between 206 and 119 is the more useful number, because an external scanner is where a language's lexing depends on context the parse tables cannot express: indentation rules, heredocs, template delimiters and similar.
So for 87 of the registered languages, lexing is whatever the runtime falls back to, and the project treats that as something to document rather than hide. There is a dedicated page for external scanner certification and fallback, which is where the difference between a certified scanner and a fallback one is spelled out.
The registry is otherwise a single call: `grammars.DetectLanguage("main.go")` resolves a filename to a matching entry, and named constructors such as `grammars.GoLanguage()` return a language directly. A minimal parse looks like this:
lang := grammars.GoLanguage()
parser := gotreesitter.NewParser(lang)
tree, _ := parser.Parse([]byte("package main\n\nfunc main() {}\n"))
fmt.Println(tree.RootNode().SExpr(lang))The result is printed as an S-expression, and the parse error is discarded in the example, which is the right shape for a smoke check and the wrong shape for anything else.
The argument is go install and the race detector, not elegance
The justification for a pure-Go rewrite is three specific consequences of CGo, not a preference for Go.
Each existing Go binding needs a C cross-toolchain per target, so a project that has to build for several platforms carries a C toolchain requirement for each one. It breaks `go install` for downstream users who do not have a C compiler, which is the difference between a library you can depend on and one that needs a compiler installed first. And it hides bugs from `go test -race`, because the C parts of the runtime are outside what the race detector instruments.
Those three are what gotreesitter removes. The parser, lexer, query engine, incremental reparsing, arena allocator, external scanners and tree cursor are all implemented in Go, and the stated consequence is that it cross-compiles to any GOOS and GOARCH target Go supports, including wasip1, so the same source builds for a server, for WebAssembly and for a browser.
The point about the arena allocator is worth pausing on. Hand-written allocators are exactly where use-after-free and buffer overruns live, and the race detector only helps with the Go side of them.
Two dependencies and a Go 1.22 floor
The module file is short enough to read in full. The module path is `github.com/odvcencio/gotreesitter`, the language directive is `go 1.22.0`, and there are exactly two direct requirements: `golang.org/x/sync v0.11.0` and `gopkg.in/yaml.v3 v3.0.1`. Two more appear as indirect, a pretty-printer and a check framework.
For a runtime carrying 206 grammars, an incremental parser, a query engine with the full pattern language and standard predicates, injection parsing for multi-language documents, UTF-16 coordinate handling and source rewriting that emits `InputEdit` records, that is an unusually small dependency surface. It is also the clearest evidence for the CGo claim, since nothing here pulls in a C-backed parser.
The language floor is the other thing to notice. A project whose newest tags are from September 2026 still declares Go 1.22.0, which is a conservative choice: it keeps the library installable on older toolchains at the cost of not using anything newer in the standard library. `x/sync` at 0.11.0 is the only concurrency helper in the graph.
The build-tag mechanism is what keeps the grammar registry from dominating the binary, and it is documented separately with the environment variables that control it.
The repository root is a parity gate rather than a source layout
The top-level listing is the most unusual thing in this repository. A normal Go project has a small root, a source directory and a test directory. This one has a flat root that is almost entirely test files with long names, among them `admission_switch_acceptance_frontier_test.go`, `admission_switch_cap_pressure_test.go`, `admission_route_equality_swift_residual_test.go`, `admission_switch_csharp_materiality_census_contract_test.go`, `admission_switch_erlang_converged_split_probe_test.go`, `admission_switch_kotlin_certification_test.go`, `admission_recover_eof_admission_test.go` and `admission_scorecard_test.go`, plus a small number of non-test files such as `admission_census.go`, `admission_switch.go` and `admission_switch_stub.go`.
The names describe what they check. Route equality for Swift residuals, byte continuity, EOF recovery admission, scanner quiescence, C# materiality, Erlang converged splits, Kotlin certification, capacity pressure. That is a parity suite for parser results, comparing this Go runtime against expected behaviour per language and per failure mode.
The documentation names the mechanism: a result-compatibility tier in `parser_result_*.go` files, with its own page in `docs/compat-tier.md`, and a testing guide covering correctness and parity gates. Two more files at the root support that culture, a `.canopyignore` and a `.git-blame-ignore-revs` for suppressing blame on mechanical changes.
The practical consequence is that a reader looking for the parser will find it in a root full of conformance tests.
Grammar tables are extracted from upstream parser.c
The grammar side is inherited rather than recompiled. gotreesitter loads the same parse-table format that tree-sitter's C runtime uses, and a tool called `ts2go` extracts grammar tables from upstream `parser.c` files, compresses them into binary blobs, and deserializes them on first use.
That settles where risk sits. Grammar definitions, and therefore the parse tables, come from upstream tree-sitter grammars, so a grammar bug is not this project's bug and will not be fixed here. What this project owns is everything between the table and the tree: the lexer, the incremental reparse that reuses unchanged tree content by reference, the no-edit fast path with zero allocations, the query engine, external scanners and the arena.
The lazy deserialization also has a cost worth naming. First use of a grammar pays for decompression, so a program that parses one file with one language pays a startup cost that a program parsing many files amortises.
Around that core sit the features an editor needs: injection parsing for HTML with JavaScript and CSS, Markdown with code fences, and Vue or Svelte; UTF-16 input and editor coordinates so integrations do not hand-convert offsets; typed query code generation through `cmd/tsquery`, which turns `.scm` files into Go structs and match helpers; and highlighting, tagging and file outlines built on the same tags-query captures.
Binary size is a build tag, and the skill lives in another repository
Embedding grammars is a choice rather than a fixed cost. The feature list names build-tag-selected grammar embedding with three modes: external blobs, a curated core set, or a hand-picked subset, all aimed at smaller binaries. The mechanism, the tag names and the environment variables are documented on their own page, so a consumer can decide at build time how much of the 206-language registry ships.
The other thing worth noting is where the agent-facing material lives. The README tells agents working with the runtime to use a `using-gotreesitter` skill, and that skill is not in this repository. Its URL points into a different project, a `m31labs-skills` repository, which matches the project site domain.
So the documentation is split across at least two repositories, and the one in this repository is organised by topic rather than by tutorial: an API guide covering parsing, queries, injections, incremental reparse, UTF-16, cursor, highlighting, tagging and outlines; a runtime architecture page for the parser, lexer, scanners, arena, query engine and grammar loading; pages for build tags, languages, testing and benchmarks; a repository map and a package layout map that assign ownership per subsystem; a page for adding a grammar outside the repository; and a release process page.
Benchmark methodology has its own two files, a root `BENCH.md` and `docs/benchmark-notes.md`, which is a better sign than a benchmark table with no notes.
Editorial conclusion
Use it if you need tree-sitter in a Go program that must build without a C toolchain, run under the race detector, or compile to WebAssembly. Judge the grammar coverage by the external scanner count rather than the headline: 206 grammars are registered and 119 have hand-written scanners, so the remainder depend on fallback lexing that the project documents separately. Also note that the page names v0.56.0 while the newest tag is v0.55.1, so pin a tag rather than trusting the stated current release.
Frequently asked questions
What is gotreesitter?
A pure-Go tree-sitter runtime with no CGo and no C toolchain. The parser, lexer, query engine, incremental reparsing, arena allocator, external scanners and tree cursor are all implemented in Go, and it cross-compiles to any GOOS and GOARCH target Go supports, including wasip1.
How many grammars does gotreesitter ship?
The registry holds 206 grammars, all producing error-free trees on smoke samples, and 119 of them ship a hand-written Go external scanner. The remainder rely on fallback lexing, and the project documents scanner certification and fallback separately.
Which version of gotreesitter is current?
The page states the current release is v0.56.0, while the published tags stop at v0.55.1 from 2026-09-26, after v0.55.0 and v0.54.0 in the same week. The last push is dated 2026-10-01, so pin a tag rather than the version named in prose.
What dependencies does gotreesitter have?
Two direct requirements, golang.org/x/sync and gopkg.in/yaml.v3, plus two indirect ones, and a language directive of go 1.22.0. Nothing in the graph pulls in a C-backed parser, which is the evidence behind the project's no-CGo claim.
How does gotreesitter get its grammar tables?
Through ts2go, which extracts tables from upstream tree-sitter parser.c files, compresses them into binary blobs and deserializes them on first use. The parse-table format is the same one the C runtime uses, so grammar correctness is inherited rather than recompiled here.
Does gotreesitter support incremental reparsing and UTF-16?
Yes on both. Incremental reparsing reuses unchanged tree content by reference and has a no-edit fast path with zero allocations, and UTF-16 input with editor coordinates means integrations do not hand-convert offsets. Source rewriting produces InputEdit records ready for a reparse.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/odvcencio-gotreesitter)Star history chart for your README
[](https://hysenlabs.com/projects/odvcencio-gotreesitter)Was this useful?