Documentation
¶
Overview ¶
Package tmux provides tmux session management for agent orchestration.
Each bc agent runs in an isolated tmux session, allowing for:
- Concurrent agent execution
- Session persistence across restarts
- Direct terminal access for debugging
Basic Usage ¶
Create a session manager:
mgr := tmux.NewWorkspaceManager("bc-", "/path/to/workspace")
Create a session:
err := mgr.CreateSession("eng-01", "/path/to/worktree")
Send commands to a session:
err := mgr.SendKeys("eng-01", "echo hello")
Capture output:
output, err := mgr.CapturePane("eng-01", 100) // last 100 lines
Session Naming ¶
Sessions are prefixed and optionally include a workspace hash for isolation:
// With workspace hash: bc-a1b2c3-eng-01
mgr := tmux.NewWorkspaceManager("bc-", "/path/to/workspace")
// Without hash: bc-eng-01
mgr := tmux.NewManager("bc-")
Caching ¶
The manager caches session existence checks to reduce subprocess calls. Cache is automatically invalidated when sessions are created or destroyed.
Index ¶
- Constants
- type Manager
- func (m *Manager) AttachCmd(ctx context.Context, name string) *exec.Cmd
- func (m *Manager) Capture(ctx context.Context, name string, lines int) (string, error)
- func (m *Manager) CreateSession(ctx context.Context, name, dir string) error
- func (m *Manager) CreateSessionWithCommand(ctx context.Context, name, dir, command string) error
- func (m *Manager) CreateSessionWithEnv(ctx context.Context, name, dir, command string, env map[string]string) error
- func (m *Manager) HasSession(ctx context.Context, name string) bool
- func (m *Manager) IsRunning(ctx context.Context) bool
- func (m *Manager) KillServer(ctx context.Context) error
- func (m *Manager) KillSession(ctx context.Context, name string) error
- func (m *Manager) ListSessions(ctx context.Context) ([]Session, error)
- func (m *Manager) PipePane(ctx context.Context, name, logPath string) error
- func (m *Manager) RenameSession(ctx context.Context, oldName, newName string) error
- func (m *Manager) SendKeys(ctx context.Context, name, keys string) error
- func (m *Manager) SendKeysWithSubmit(ctx context.Context, name, keys, submitKey string) error
- func (m *Manager) SessionName(name string) string
- func (m *Manager) SetEnvironment(ctx context.Context, name, key, value string) error
- func (m *Manager) WithExecCommand(fn func(string, ...string) *exec.Cmd) *Manager
- type Session
Constants ¶
const DefaultCacheTTL = 2 * time.Second
DefaultCacheTTL is the default time-to-live for cached session data.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Manager ¶
type Manager struct {
SessionPrefix string // Prepended to all session names (e.g., "bc-")
// contains filtered or unexported fields
}
Manager handles tmux session operations.
func NewDefaultManager ¶
func NewDefaultManager() *Manager
NewDefaultManager creates a new tmux manager with default prefix "bc-".
func NewManager ¶
NewManager creates a new tmux manager with the given prefix.
func NewWorkspaceManager ¶
NewWorkspaceManager creates a tmux manager scoped to a workspace. Session names include a short hash of the workspace path for isolation.
func (*Manager) AttachCmd ¶
AttachCmd returns an exec.Cmd to attach to a session. The caller should set Stdin/Stdout/Stderr and run it.
func (*Manager) CreateSession ¶
CreateSession creates a new tmux session.
func (*Manager) CreateSessionWithCommand ¶
CreateSessionWithCommand creates a session and runs a command.
func (*Manager) CreateSessionWithEnv ¶
func (m *Manager) CreateSessionWithEnv(ctx context.Context, name, dir, command string, env map[string]string) error
CreateSessionWithEnv creates a session with env vars baked into the shell command. Environment variable keys are validated to prevent shell injection attacks. Keys must match POSIX standards: start with letter/underscore, contain only alphanumerics/underscores.
func (*Manager) HasSession ¶
HasSession checks if a session exists. Results are cached with a short TTL to reduce subprocess calls.
func (*Manager) KillServer ¶
KillServer kills the tmux server (all sessions).
func (*Manager) KillSession ¶
KillSession kills a tmux session.
func (*Manager) ListSessions ¶
ListSessions lists all sessions with our prefix. Results are cached with a short TTL to reduce subprocess calls.
func (*Manager) PipePane ¶
PipePane starts or stops streaming a session's output to a log file. If logPath is non-empty, starts piping output via "cat >> logPath". If logPath is empty, stops any existing pipe.
func (*Manager) RenameSession ¶
RenameSession renames a tmux session.
func (*Manager) SendKeys ¶
SendKeys sends keys to a session with Enter as submit key. This is a convenience wrapper around SendKeysWithSubmit.
func (*Manager) SendKeysWithSubmit ¶
SendKeysWithSubmit sends keys to a session with a specified submit key. For messages longer than 500 chars, uses tmux load-buffer/paste-buffer to avoid truncation. Trailing newlines are trimmed. submitKey specifies what to send after the message: - "Enter" sends the Enter key as a tmux key-name event - "" sends nothing (message is left in input buffer) - Other values are sent as tmux key names (e.g., "C-m" for Ctrl+M)
func (*Manager) SessionName ¶
SessionName returns the full session name with prefix (and workspace hash if set).
func (*Manager) SetEnvironment ¶
SetEnvironment sets an environment variable in a session. Environment variable key is validated to prevent shell injection attacks. Key must match POSIX standards: start with letter/underscore, contain only alphanumerics/underscores.
Source Files