# Command-T for Neovim: a C-backed fuzzy finder and what it costs to build

> Command-T is a Neovim plug-in that ranks files, buffers, tags and commands by a hand-written fuzzy match. It requires a compiled C extension, and that build step is the part to weigh before adopting it.

**wincent/command-t** — ⌨️ Fast file navigation for Neovim and Vim

- Repository: https://github.com/wincent/command-t
- Stars: 2,783 · Forks: 317
- Language: Lua
- License: BSD-2-Clause
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/wincent-command-t

## What Command-T solves, and who it is actually for

Command-T is a Neovim plug-in for reaching a file without typing its path. The README lists four targets: opening files and buffers, jumping to tags and help, and running commands or previous searches and commands. The selection model is fuzzy: you type characters that appear somewhere in the path, and the plug-in decides which candidates match. The README states that ranking gives more weight to characters that appear in certain locations, immediately after a path separator being the example it gives.

The intended user is a Neovim user who already knows roughly where a file lives and wants to spend fewer keystrokes getting there. That is a narrower audience than "Vim users" in general. The README carries an explicit note that this is the Lua-powered rewrite and requires Neovim, and it directs anyone who needs Vim support to the 7-x-release branch, which is the older Ruby-powered version. If your editor is Vim rather than Neovim, this repository is not the one you want, and the README says so before anything else.

## The matching algorithm is C, and the plumbing around it is Lua

The repository splits cleanly along that line. The Lua plug-in code lives under lua/, and the compiled portion lives at lua/wincent/commandt/lib, which is the directory the top-level Makefile targets. Running make build delegates into that directory with $(MAKE) -C $(LUA_DIR), so the C sources and their own build rules sit there rather than at the repository root.

Speed is stated as the primary design goal, and the README attributes it to a combination of a hand-crafted matching algorithm implemented in low-level C, parallelized search, input debouncing, and integration with Watchman. Each of those is a distinct mechanism. Parallel search spreads candidate matching across workers; debouncing means keystrokes arriving in a burst are not each turned into a full search; Watchman integration lets the plug-in learn about filesystem changes rather than rescanning blindly. The README also claims Command-T is "the fastest fuzzy file finder bar none", which is the project's own assertion and not something this article can confirm.

ARCHITECTURE.md exists at the repository root, so the intended design is documented separately from the README. The README itself does not walk through the data flow, and it does not describe how the ranking scores are combined or what happens when Watchman is absent.

## Installing Command-T and running a first search

The README does not contain installation instructions. It points to the documentation at doc/command-t.txt, and the repository layout shows a Makefile plus a bin/ directory holding scripts such as bin/test and the check-format, check-spdx and check-tag helpers. What the README and Makefile do establish is that a build step exists: the plug-in ships C sources that must be compiled before the Lua side can use them.

Assuming the plug-in is on your Neovim runtimepath, compiling is the first real action. This invokes the recursive make into the library directory:

```bash
make build
```

After that completes, the plug-in's commands become usable in Neovim. The README describes opening files and buffers, jumping to tags and help, and running commands or previous searches and commands, but it does not print the command names or default key mappings; doc/command-t.txt is where the project says that detail lives, so read it there rather than guessing at a mapping.

If you want to run the project's own checks before trusting a checkout, the Makefile exposes a single target that cleans, rebuilds, runs the test suite, and then runs the format, SPDX and tag checks:

```bash
make check
```

That target is the maintainer's prerelease gate rather than an end-user command, but it is the clearest signal in the repository about what a working build is expected to satisfy. A clean build with no output from bin/check-format is what you should see.

## The compiled extension is the main operational cost

A plug-in that must be compiled is a different kind of dependency from a pure-Lua one. The top-level Makefile is a thin wrapper: build, check, test and clean all delegate to lua/wincent/commandt/lib, and the root clean target calls the library clean. If the C toolchain on a given machine cannot produce that artifact, the Lua side has nothing to call, and the README does not describe a fallback path.

There is also a version boundary to respect. The README's note is unambiguous that this rewrite requires Neovim and that the Ruby-powered 7-x-release branch is the one that also supports Vim. A user who upgrades to this branch expecting their Vim setup to keep working has crossed a line the README draws deliberately.

The README does not document rollback, does not describe what happens when Watchman is not installed, and does not give a troubleshooting section for a failed build. Those gaps matter more here than they would for a script-only plug-in, because the failure mode is not a misconfigured option but a missing binary. The repository does carry a .watchmanconfig file at the root, which is consistent with Watchman being a supported integration, but the README does not say whether it is required or optional.

## Where Command-T sits against fzf and Telescope

The obvious comparison is fzf, which is not a Neovim plug-in at all but a general-purpose fuzzy finder that runs as a separate process and is wired into the editor by a thin integration layer. That difference in approach is the whole argument. fzf keeps the candidate list in an external program and communicates over a pipe, so it works in any shell and any editor that can spawn a process. Command-T keeps the matching inside the editor as a compiled extension, which is what lets it share the process, read the editor's buffer and tag state directly, and apply the ranking weights the README describes.

Telescope is the other reference point, and it is a Neovim plug-in written in Lua that composes pickers from separate sources and sorters. Its model is extensibility: you assemble a picker from parts. Command-T's model is a fixed set of targets (files, buffers, tags, help, commands, previous searches) with a single matching engine behind them. If you want to add a new kind of picker, Telescope's design is built for that and Command-T's is not described that way.

The trade-off is concrete. Command-T asks for a compile step and a Neovim-only commitment in exchange for a matcher it controls end to end. fzf asks for almost nothing at install time and gives up in-process knowledge of your buffers and tags. Telescope asks for neither a compile step nor a separate binary, and gives up the C-level matching path.

## Maintenance, licence and what a fork inherits

The repository is not archived, and the last push was on 2026-09-23. Releases are tagged and dated: 8.2 on 2026-07-13, 8.1 on 2026-03-19, and 7.0.2 on 2025-11-05. The spacing suggests a project that ships when there is something to ship rather than on a schedule, which is normal for a plug-in maintained by one person and also means you should not expect a fix on demand.

Upgrade cost is dominated by the build. Every release that touches the C sources requires a recompile, and the Makefile's check target shows the maintainer's own sequence: clean, build, test, then the format, SPDX and tag checks. If you vendor the plug-in or package it for a team, that sequence is the one to reproduce.

The licence is BSD-2-Clause, and the source files carry SPDX headers, with the Makefile showing SPDX-FileCopyrightText and SPDX-License-Identifier lines and a bin/check-spdx script enforcing them. BSD-2-Clause is permissive, so redistributing a modified copy is straightforward, but this is a description of what the repository states and not legal advice. If you fork and ship the compiled library, keep the copyright notice and the SPDX identifiers intact, since the project's own tooling treats a missing header as a failure.

## Conclusion

Adopt Command-T if you work in Neovim, value match ordering over plugin count, and are willing to run make build as part of setup. Skip it if you still use Vim, since the README states the Lua rewrite requires Neovim and points Vim users at the 7-x-release branch, or if you cannot compile a C extension on your machines. Before committing, verify that make build succeeds against your Neovim version and that the ranking behaves the way you expect on your own directory tree.

## FAQ

### What is Command-T?

Command-T is a Neovim plug-in that provides fuzzy selection for opening files and buffers, jumping to tags and help, and running commands or previous searches and commands. The README describes it as the Lua-powered rewrite of Command-T and states that it requires Neovim.

### Does Command-T work on Mac?

The README does not list supported operating systems. What it does state is that this version requires Neovim and that the older Ruby-powered 7-x-release branch is the one that also supports Vim, so the deciding factor is your editor rather than your platform.

### How does Command-T compare with command-N style navigation?

The README does not mention command-N or any similar mapping, so the repository gives no basis for a comparison. What it describes instead is a fuzzy matching model where you type characters that appear in a file's path and the ranking weights characters that follow a path separator more heavily.

## Sources

- [Issues](https://github.com/wincent/command-t/issues)
- [License: BSD-2-Clause](https://github.com/wincent/command-t/blob/main/LICENSE)
- [README](https://github.com/wincent/command-t/blob/main/README.md)
- [Releases](https://github.com/wincent/command-t/releases)
- [wincent/command-t on GitHub](https://github.com/wincent/command-t)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wincent-command-t