Session directories and existing or new claude code sessions started outside of agentdock, and multiple agent docks sessions

[nipunarora]

A few questions before I use?

1. How can I start a claude session in a different directory?
2. Does it track new claude sessions being created outside of agentdock?
3. Can I have multiple agentdock instances running in different terminals? Will it recognize each other?

[asheshgoplani]

Hey @nipunarora, great questions! Here's how each works:

1. Starting a session in a different directory

Pass the path as the first argument when adding a session:

agent-deck add ~/work/my-project -t "My Project" -c claude
agent-deck add /path/to/anything -t "Experiment" -c claude

In the TUI, press n to create a new session. The Path field defaults to your current working directory, but you can type any path (tab-completion and ~ expansion are supported).

2. Tracking sessions created outside agent-deck

Press i in the TUI to import existing tmux sessions. This discovers any tmux sessions on your system that agent-deck isn't already tracking, and auto-detects the tool type (Claude, Gemini, etc.) from the session name.

If you start claude in a regular terminal (not inside tmux), there's nothing to import since agent-deck manages sessions through tmux under the hood. The recommended workflow is to create sessions through agent-deck so you get status tracking, MCP management, fork, restart, and the notification bar.

3. Multiple agent-deck instances

Yes! Multiple TUI instances of the same profile are supported and enabled by default. The first instance becomes the "primary" (manages the tmux notification bar), and additional instances run as secondaries. They all share the same sessions.json, so they see the same sessions and stay in sync.

# ~/.agent-deck/config.toml (default behavior)
[instance]
allow_multiple = true    # set to false for strict single-instance

You can also:

• Use different profiles for fully separate session lists: agent-deck -p work in one terminal and agent-deck -p personal in another.
• Use CLI commands alongside the TUI from any terminal: agent-deck list, agent-deck session send <id> "message", etc.