Possibility to add CLI argument to agterm to set starting directory (start if not running, new tab if running)

[vo-va]

I launch terminals from another app and want to specify the starting directory.
iTerm supports this via:

open -a iTerm /tmp

If no iTerm instance is running, it starts one and opens a new tab at the specified path. If an instance is already running, it just opens a new tab there.

Searching the agterm help with Claude Code, the only working combination I found was:

open -a agterm && agtermctl session new --cwd /tmp

Would it be possible to update agterm to accept an argument on the agterm binary itself, so that it opens in a specific directory when it isn't running yet, and opens a new tab when it is already running?

[umputun]

agterm handles this through agtermctl:

agtermctl session new --cwd /path/to/dir

agterm is fully driven by agtermctl - that's the design. Adding a separate shortcut for the same thing (like passing a path directly to the binary) would mean two ways to achieve the same result, which complicates things with no real benefit. agtermctl is the right interface for session control and already covers this case.

for cold start (open -a agterm first, then session new), there is a timing gap: open returns before the socket is ready. The caller needs to wait - a short sleep 0.5, a loop on agtermctl tree 2>/dev/null, or checking that the socket file exists. How to wait is up to the script.

[vo-va]

Yes, I saw that in the docs. But I start terminals not from a script but from another binary program. Dealing with executing 2 binaries is possible, although it requires additional steps like waiting for the socket to become available.

The benefit that I see- I can use it as quick action "open new terminal here {path}" in Finder and other programs as one action and don't check if it is running or not.

Please reconsider this and add support for a starting directory.
As another point, other terminals also support such a format:

open -a kitty /tmp
open -a ghostty /tmp

The difference with them is that they create a new window even if their instance is already running, instead of a tab as iTerm does.

[umputun]

the request makes sense for a Finder-style "open terminal here" action, and you're right that iTerm/kitty/ghostty all take open -a <term> /path. The reason agterm doesn't just do the same isn't only the "two ways to do it" point from my first reply, the bigger issue is that agterm's launch model is different from those terminals, and that's what makes it awkward.

iTerm and kitty treat windows as disposable, agterm doesn't: on launch it restores your full window/workspace/session tree, and the set of windows open at quit reopens next time. That's the core of the app, not an option you turn on.

so the real question is what open -a agterm /path should actually do, and I don't have a clear answer yet:

• already running (the common case for a Finder action while you're working): the app is up and just adds a terminal at that path, though there's still the question of which window it goes into (below).
• not running (cold start): this is where it collides with restore. On a cold launch the OS starts agterm, agterm brings back your whole tree (say your "work" and "personal" windows with all their sessions), and then the /path terminal has to graft on top. You don't get a clean single tab like iTerm gives you, you get your whole restored setup plus the new thing.

there's also the "which window" question, iTerm drops a tab on the front window but agterm windows are named, persisted bundles, so there's no obvious "the window" to drop a /path session into. A new window each time (kitty-style) piles up throwaway windows in your saved set, a session in the frontmost window drops a stray terminal into whatever named window happened to be up front.

the obvious fix for cold start is "skip restore, open one window at the path". That's worse than it looks:

• if the folder-launch skips restore and opens only the path, quitting from there marks your real windows closed, and they don't come back on the next normal launch. You'd lose your curated set until you reopen each by hand.
• avoiding that needs a separate throwaway-window concept that never touches the saved set, which is real machinery for this one feature.
• and it's a surprising result: open a folder from Finder, and none of your restored terminals show up that launch.

so the warm case (agterm already running) is somewhat manageable, but still unclear. Even then it needs a call on what it actually does: add a session to the frontmost window, add a session to the first window, or open a new window with one session at the path. Cold start is the part that's really confusing, since agterm always restores your windows first. Unless we can settle on a clear, predictable, no-surprises mental model for how this behaves, I'd rather skip it.

[vo-va]

I am still using iTerm and it has some capability to restore windows with tabs and the state in which they were closed so they are not fully disposable. I don't have a lot of experience with agterm, so maybe my preference will change later. For today, I will be happy with opening a new session/tab in the last active window/last active workspace. At least iTerm works this way (it does not have workspaces; I mean it uses windows).

For agterm restoration, I guess it works next:
on exit it remembers windows with the sessions in them and remembers the last active window;
on start it restores all windows and activates the last active window.

For my preferences it is fine to add a new session/tab in that last active window.

Another option is to use an additional argument to narrow user choice, if it is not too much to ask. For example, -n, like Sublime Text does. subl /tmp/myfile will open the file in the last active window, subl /tmp/myfile -n will create a new window and open the file in it. And if Sublime was closed at that time it will also return back all the previously existing windows i.e. it will not open just a new window.

Another idea: if a workspace has a default name like "workspace 1/2/3...", then probably it is not intended for something persistent. In that case, find the last active window and the last active workspace with a default name. If there is no workspace with a default name, then create a new workspace. This, I think, will prevent breaking of the existing "stable" workspaces with the new sessions/tabs.

[umputun]

yes, iTerm does restore windows and tabs, so "disposable" was too broad from me. The difference is narrower than I put it, iTerm restores a flat list of windows and agterm restores a named workspace tree.

your first option is the one that works, and it clears up what I was stuck on. The trick is that it doesn't skip restore at all:

open -a agterm /path starts (or activates) agterm normally, restores everything as it does today, then adds a session at that path to the last active window.

that's one rule for both cases, no special cold-start path, nothing suppressed, nothing lost. On a cold start you get your whole restored setup plus the new session, in the window that was going to be activated anyway. It's not the clean single tab iTerm gives you, but it's predictable, which is what I was after.

your read on restore is right btw, agterm already remembers the last active window and brings it up front on launch, so this maps onto what's already there.

on -n: it doesn't translate to open. That flag is already open's own and means "launch a new instance of the app", so you'd get a second agterm process fighting the first over the same state and socket. And app args (--args) only reach a freshly launched instance, a running app just gets the path, so the flag would do nothing in exactly the case you care about. Sublime works because subl is a direct CLI, the equivalent here is agtermctl, which can already put a session where you want it.

on the default-workspace-name idea: I'd skip it. Guessing that a workspace is throwaway because it's still called "workspace 2" is the kind of magic that surprises people. Someone who never renames gets sessions dropped into their real workspace, someone who always renames gets a new workspace every time. Too unpredictable.

so: a new session at the path in the last active window, same behavior whether agterm is running or not. That I can do.

[vo-va]

so: a new session at the path in the last active window, same behavior whether agterm is running or not. That I can do.

I will be happy with such an implementation. Thank you!
As for the ideas, I proposed them as possible ways to keep "preexisting" workspaces in the state in which the user created them, and I don't mind not having them.