Simple Neovim plugin for wroktrunk

[emeren]

Hey, big fan of Worktrunk, been using it every day. I noticed #1493 was closed without an implementation and since I kept switching between the terminal and Neovim just to manage worktrees, I figured I'd try building something myself. Wrote a simple plugin a few weeks ago and have been using it since: https://github.com/emeren/wt.nvim

Just wraps the wt CLI using --format=json so I don't have to leave the editor. Has a Telescope picker for listing/switching, basic create/remove/merge commands, and a small statusline component showing the current branch. 🔀

Nothing too fancy but it's been working well for my workflow. Do you think it's worth pursuing further? 🙂

Let me know if the name's a problem, happy to change it!

[worktrunk-bot]

Thanks for building this — and for closing the loop on #1493. Worth surfacing that max-sixty replied there with almost exactly this outcome in mind: "my mental model is that someone who does use nvim would make it — I'm happy to make any adjustments on the worktrunk binary side to be helpful."

Two things about the --format=json surface that are easy to miss from the outside and will bite the plugin later. Both come down to the same root issue: a plugin that shells out to wt inherits the user's config, so anything it depends on should be pinned per invocation rather than assumed.

1. The JSON output is mid-migration — pin the schema. With [list] json-schema unset you get schema 1 (bare array) plus a warning on stderr, and a future release flips the default to schema 2 (an envelope: {"schema": 2, "repo": {…}, "collected": {…}, "items": [{…}]}). So a plugin that parses the bare array breaks today for any user who has already set json-schema = 2, and breaks for everyone when the default moves. Pin it:

wt --config-set 'list.json-schema=2' list --format=json

That also suppresses the nag, which would otherwise land in :messages on every call.

2. [list] columns can turn on a network fetch. Plain wt list is local-only, but when the user's [list] columns names ci, the CI status column — and its network round-trip — is forced on without --full (list/mod.rs#L49-L50). For a statusline component that runs on redraw, that's a forge API call per redraw, triggered by config you don't control. --config-set 'list.columns=[…]' pins it for the hot path.

--config-set is repeatable, takes a TOML fragment, and outranks both config files and WORKTRUNK_* env vars (docs) — it's the intended tool for "this call needs this shape regardless of user config".

On the name: that's a maintainer call rather than mine, so I'll just flag it rather than answer it.

One project-side gap this surfaces: there's no community/integrations section in the docs today, so nothing links out to third-party tooling even when it exists. Whether to add one — and whether to link out to a specific plugin — is a maintainer's editorial call; happy to open that PR if it's wanted.

How the above was verified

Built wt at 715af4c and ran against a scratch repo:

$ wt list --format=json
▲ JSON output is schema 1; a future release switches the default to schema 2
↳ To keep this format set [list] json-schema = 1; to adopt the new schema, set json-schema = 2
[
  {
    "branch": "main",
    "path": "/tmp/wtdemo",
...

$ wt --config-set 'list.json-schema=2' list --format=json
{
  "schema": 2,
  "repo": {
    "default_branch": "main"
  },
...

Both list.json-schema=1 and =2 pin the format and silence the warning; --config-set 'list.columns=["branch","status"]' composes with it in the same invocation. Schema 2's shape is documented at worktrunk.dev/list; the resolution and warning logic is resolve_json_schema in list/mod.rs.

I did not review the plugin's source — the notes above are about the wt interfaces it consumes.

A maintainer will weigh in on the broader question of whether to pursue it further.

[emeren]

Wasn't aware of the schema migration and the CI column triggering network calls on every list. Will pin both via --config-set per invocation, should have the fix out in the coming days, probably tomorrow :D Makes sense to keep the plugin isolated from user config that way.

[emeren]

Done! Pinning json-schema=2 and columns via --config-set on list calls now. Schema 1 fallbacks still there for older binaries.

[worktrunk-bot]

Since you're keeping a schema-1 fallback: the version boundaries are worth knowing, because the middle band gives you no signal that the pin didn't take. I ran the pinned invocation against released binaries:

wt version	--config-set 'list.json-schema=2' list --format=json
< v0.61.0	fails at argument parsing — error: unexpected argument '--config-set' found, exit 2, no output
v0.61.0 – v0.65.x	exit 0, schema 1 output, no warning — --config-set exists but the key doesn't, and unknown keys in the CLI-override layer are dropped silently
≥ v0.66.0	schema 2 envelope

The middle band is the one to design for: the pinned call succeeds, so a fallback keyed on "did the pinned invocation work" won't fire, and there's nothing on stderr either. Detect by output shape — bare array vs. object with "schema": 2 — rather than by exit status or by the pin appearing to succeed. Exit status still matters for the < v0.61.0 case, where the whole command dies before list runs, so both checks earn their place.

list.columns has its own floor — it landed in v0.62.0, and below that the pin is the same silent no-op. That one's harmless though: the CI-forcing behaviour it guards against arrived with the key, so there's nothing to guard on older binaries.

Transcript

Ran against a scratch repo with a clean HOME, using the published x86_64-unknown-linux-musl release artifacts:

$ wt --version
wt v0.60.0
$ wt --config-set 'list.json-schema=2' list --format=json
error: unexpected argument '--config-set' found

  tip: a similar argument exists: '--config'

Usage: wt --config <path>
exit=2

$ wt --version
wt v0.65.0
$ wt --config-set 'list.json-schema=2' list --format=json
[
  {
    "branch": "main",
...
exit=0        # no stderr, no warning — the override key is simply unknown

$ wt --version
wt v0.66.0
$ wt --config-set 'list.json-schema=2' list --format=json
{
  "schema": 2,
  "repo": {
    "default_branch": "main"
  },
...

The silent-ignore in the middle band is a property of the override layer rather than a bug: UserConfig doesn't use deny_unknown_fields, and the unknown-field warning pass runs over config files, not the --config-set layer. apply_cli_overrides drops the whole layer with a warning only when a fragment fails to parse, deserialize, or validate — an unrecognized key is none of those.