Tag-Teaming Claude Code with an AI Agent via Tmux

Claude Code is an impressive CLI that brings sophisticated AI-assisted coding directly into the terminal. Its TUI (Text User Interface) provides rich feedback through interactive menus, progress bars, and side-by-side diffs. However, long-running tasks present a challenge: if you need to step away from your computer, the session momentum is often lost.

To solve this, I’ve developed a workflow using Tmux as a shared terminal state. This allows me to hand off a live session to my Clawdbot agent and, conversely, take over a session that the agent started. It also provides a mechanism to optionally switch between different account tokens (such as a work account) on the fly.

The Core Concept: Persistence

The strategy relies on Tmux sessions to maintain a persistent terminal state in memory. By using named sessions, both the human and the AI agent can attach to and drive the exact same process. This ensures zero context loss when switching between “manual” and “agent” mode.

Configuration: Storing Account Profiles

To enable the agent to switch accounts, you can store secondary tokens in the coding-agent skill section of clawdbot.json. Using simple shorthand keys makes it easier to request them from a phone.

1
2
3
4
5
6
7
8
9


"skills": {
  "entries": {
    "coding-agent": {
      "env": {
        "CC_ACC2_TOKEN": "your-token-here"
      }
    }
  }
}

Workflow 1: Human to Agent Hand-off

When I am working at my desk and need to step away, I follow these steps:

Start a named Tmux session:
1 2

tmux new -s hiren-claude claude
Pro-Tip: If you want to launch manually with a specific account token, use the env prefix within the Tmux command string to ensure the environment variable is correctly injected into the background session:
1

tmux new -s hiren-claude -d "env CLAUDE_CODE_OAUTH_TOKEN='your-token' claude"
Request Hand-off: From WhatsApp, I tell the agent:

“Take over session hiren-claude. Finish the refactor.”

Environment Inheritance

If I start a session at my desk using export CLAUDE_CODE_OAUTH_TOKEN=..., the agent inherits that environment automatically when it takes over the Tmux pane. Keystrokes sent by the agent will be processed within that authenticated shell.

Workflow 2: Agent to Human Take-over

The hand-off also works in reverse. I can have the agent start a complex task while I am away:

Default Account Example

I can instruct the agent to start a new run using my default CLI login:

“Start a new session hiren-claude and begin refactoring the database schema.”

Behind the scenes, the agent runs tmux new -s hiren-claude -d "claude '...'".

Specific Account Example

If I want the agent to use a specific account profile from the config:

“Start a new session hiren-claude using cc-acc2-token and fix the memory leak.”

The agent then prepends the token to the execution, mapping the CC_ACC2_TOKEN from the config to the CLAUDE_CODE_OAUTH_TOKEN required by the CLI.

Human Take-over

When I return to my computer, I can attach to the session and take full control immediately:

1

tmux attach -t hiren-claude

Because Tmux lives in the background, this works even if the screen is locked, provided the computer remains awake.

Benefits of the Tmux Bridge

Full TUI Support: Standard stdin/stdout redirection often breaks the interactive elements of Claude Code. Using Tmux preserves the full visual experience.
Real-time Monitoring: I can “spectate” the work by attaching to the session via SSH from a mobile device or another terminal.
Zero Friction: No need to re-authenticate or re-explain context when switching between human and AI control.

Execution Reminders

Installation: Ensure tmux is installed via Homebrew (brew install tmux).
Naming: Use consistent session names so the agent knows where to look.
Power Settings: Configure your Mac to stay awake when the display is off to ensure the Tmux server remains active.

By treating the terminal as a shared space, I’ve turned my AI agent into a true tag-team partner. We can hot-swap control of the keyboard and switch accounts on the fly without ever losing the “zone.”