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.

[max-sixty]

this looks v cool @emeren !

Some simplifications from what @worktrunk-bot said:

• I would just support schema v2 only, the new one is better and has been around for a while
• the concern about hitting the network seems very far-fetched; we deliberately don't do network calls without --full. I'm not sure if @worktrunk-bot is saying that because there's some risk that someone passes an additional flag setting extra columns? (@worktrunk-bot does setting columns actually change the json output? should it?)

[worktrunk-bot]

Both questions, verified against 7a2a3e0.

First, a correction to my own framing. I wrote "a forge API call per redraw" — that's wrong, and it made this sound worse than it is. CI status is cached per branch in .git/wt/cache/ci-status/<branch>.json with a 30–60 s TTL, so the actual cost is one gh pr list per branch per ~30–60 s, not one per redraw. With that in view the statusline argument is a lot weaker than I made it.

But the mechanism isn't a flag — it's the user's own config. Not something the plugin passes: a column named in [list] columns enters as ColumnSource::Listed, and a Listed column deliberately overrides the --full preset gate — ColumnKind::CiStatus => listed || gates.show_full (columns.rs#L242). So for a user who has set columns = […, "ci"], plain wt list --format=json with no --full does fetch. In a scratch repo with origin pointed here, -vv shows gh pr list --head … 294 ms on the listed-ci run and no forge call at all on the run without it.

So "we don't do network calls without --full" holds for the default config, and breaks for exactly that one key. Whether a plugin should pin against it is a judgement call — with the cache TTL in view I'd now put it as "avoid surprising a user who never asked their editor to talk to GitHub" rather than as a performance problem.

Does setting columns change the JSON output? Yes — in one direction only. Listing ci flips collected.ci to true and materialises the per-item pr and checks objects. It never narrows: --format json always plans all_columns and only unions in the selection's forced-on columns (collect/mod.rs#L1326), so columns = ["branch"] yields byte-identical items to no setting at all. On a branch with an open PR:

[list] columns	collected.ci	item keys
unset	false	branch, dev_server, display, head, worktree
["branch", "ci"]	true	+ checks, pr

Should it? My read is no, for --format=json specifically. [list] columns is a presentation setting, and JSON already ignores the narrowing half of it on the grounds that a machine consumer wants every field; honouring only the half that adds a network fetch is the asymmetric bit. --full is already the explicit "go get forge data" switch, and it's the one a plugin controls. Today a plugin can't ask for "everything local" without pinning columns, because whether the call touches the network is a property of config it didn't write.

Two counterweights, though, and they're why I'd rather not just open a PR: the current behaviour keeps wt list and wt list --format=json describing the same repo state, which is a real consistency property; and schema 2 does signal it — collected.ci exists precisely so a consumer can tell "no PR" from "didn't look". Schema 1 has no such signal (the ci key is skip_serializing_if = "Option::is_none", so absent-because-no-PR and absent-because-not-fetched are the same shape), but that's an argument about the schema you're deprecating anyway.

If you want it changed, the JSON branch would use full_plan() alone while the picker keeps the union — a few lines in collect, plus tests. Happy to open it; I don't think it should be decided from my side.

Transcript

Scratch repo at /tmp/wtdemo, clean HOME, origin = https://github.com/max-sixty/worktrunk.git, wt built at 7a2a3e0. Checked out docs/issue-3809-alt-x-never-forces (head of open PR #3811) so the branch has real forge data. CI cache cleared before each run.

$ wt --config-set 'list.json-schema=2' -vv list --format=json
# trace.log: no gh/glab invocation beyond the -vv version probes
"collected": { "ci": false, "summary": false }
item keys: branch, dev_server, display, head, worktree

$ wt --config-set 'list.json-schema=2' --config-set 'list.columns=["branch","ci"]' -vv list --format=json
# trace.log:
#   $ gh pr list --head docs/issue-3809-alt-x-never-forces --state open --limit 20 --json …
#   ✓ 294.597ms
"collected": { "ci": true, "summary": false }
"pr":     { "number": 3811, "url": "…/pull/3811", "mergeable": null, "repo": {…} }
"checks": { "status": "passed", "source": "pr", "stale": false }

Narrowing check — items byte-identical between unset and columns = ["branch"].

Schema 1, same branch: with ci listed the item gains a full ci object; without it, has("ci") is false. No collected envelope either way.

Code path: column_renders (columns.rs#L239-L249) gates by ColumnSource; collect picks the plan at collect/mod.rs#L1319-L1329; collected.ci drives pr/checks presence at json_v2.rs#L649. Cache TTL is TTL_BASE_SECS = 30 plus path-hashed jitter up to 30 in ci_status/cache.rs.

Unrelated but adjacent, since it's the other config key that reaches JSON: [list.custom-columns] entries do add fields (an item's display.columns map), and those are user-authored templates.

[max-sixty]

OK, I reckon let's change this so that JSON always emits the same outputs, and list.columns only affects the actual columns

[worktrunk-bot]

Opened as #3812. The JSON branch now plans all_columns alone, so [list] columns reaches --format json in neither direction — it already couldn't narrow the fields, and it no longer forces the ci/summary fetch on either. --full stays the only switch for that data, and the table and picker are unchanged (a listed ci still shows the CI column without --full).

@emeren — once that lands you won't need the columns half of the pin. The json-schema=2 pin is still worth keeping.