File tree in agterm — worth discussing?

[rashpile]

Open a discussion about a file tree in agterm, since it seems like something more than one person wants.

Someone already tried it: PR #195 added a native file-tree panel. It was declined on scope - agterm is a terminal, not a file manager, and things past the defaults belong on the control API. I think that's fair.

So I did it the other way. nvim-tree runs in a right split pane, and clicking a file opens it in an overlay. It's a shell script and a bit of Lua on top of agtermctl.

Why I want a tree at all: I work with agents, and I like seeing the files right next to the agent session. It keeps the mental picture straight that agent isn't operating in a vacuum, it's working on these files, and they're right there. Without the tree I lose that, and the session becomes a chat window that happens to touch a repo somewhere.

That's my reason. Curious if others feel the same, or if popping open yazi in an overlay when you need it is enough — for me it isn't, because the point is having the files always visible, not on demand.

Screenshots of how it looks in my setup:

File Tree

Open preview

[umputun]

this is exactly the intended pattern, so you got it right. Past the defaults, built over the control API, in your own layout. That's the design, not a workaround.

on always-visible vs on-demand: that's just which pane you put it in. Splits and overlays are what agterm gives you, and what runs inside is entirely yours. A persistent split keeps a file browser (yazi/lf/nvim-tree, whatever) in view all the time, an overlay is the on-demand version. Picking the split for persistence makes sense, but that's you using panes, not anything we support on our side.

the built-in panel stays out of scope for the reasons in #195, which you already know. Share your script and the Lua here if you're up for it, others with the same itch can lift it.

as for an official recipe: I'd let demand decide. If a few more people want the same always-visible setup, a tool-neutral example (any file browser in a companion split) could go in the agent-skill recipes. One setup isn't enough to bless yet, but the thread is the right place to find out.

[rashpile]

Here it is: https://github.com/rashpile/agterm-experimental/tree/main/config/agterm-tree

The scripts, the nvim config, and the menu.

Menu is defined in YAML. Entries filter per node (file / directory / extension), nest into submenus, and run either a built-in tree action or any shell command — detached, in an overlay on the current session, or in a new session. So "review this file in revdiff and put the annotations on my clipboard" is a few lines of config, not a patch:

  - name: Review changes
    isDir: false
    run: overlay
    cmd: revdiff --only $REL

There's an AGENT_INSTRUCTION.md next to the README, written for a coding agent rather than a human. Point Claude Code at it and it checks prerequisites, asks before overwriting an existing nvim config / taking a bound chord / changing your terminal theme, drops the menu entries for tools you don't have, then verifies the result. That matters because this is my personal setup — my keybinding, my theme, my helper scripts — and a straight copy would fight anyone else's machine. An agent adapting it beats a dotfiles dump you have to un-pick by hand.