DEV Community

Daksh Gargas
Daksh Gargas

Posted on

Beyond Sub-Agents: One Claude Orchestrating Another (with tmux)

#ai #claude #agents #tmux

Summary

A detached tmux session can run completely independently of any visible terminal window. You can send keystrokes into it, capture everything displayed on screen, and attach a human observer at any time.

In other words, tmux lets you automate an interactive terminal session.

The Core Idea

Suppose you have a detached tmux session:

tmux new-session -d -s worker
Enter fullscreen mode Exit fullscreen mode

You can send input into it:

tmux send-keys -t worker -l "echo hello"
tmux send-keys -t worker Enter
Enter fullscreen mode Exit fullscreen mode

And you can read what's on screen:

tmux capture-pane -t worker -p
Enter fullscreen mode Exit fullscreen mode

That's essentially it.

Write → Terminal
Read  ← Terminal
Enter fullscreen mode Exit fullscreen mode

Once you can write to a terminal and read from it, the terminal becomes programmable.

Anything that runs inside a terminal can now be controlled programmatically.

One Claude Orchestrating Another

Once you realize a tmux session is programmable, an interesting possibility appears.

Instead of asking Claude to spawn a sub-agent, you can ask it to create and manage an entirely separate Claude Code session.

That worker Claude runs independently in its own terminal, while the primary Claude retains the conversation context, understands the broader objective, and remains responsible for planning and decision-making.

From your perspective, you're still talking to a single Claude.

Behind the scenes, that Claude is coordinating another fully capable Claude.

Your primary Claude can:

  • Create a detached tmux session
  • Launch a worker Claude inside it
  • Send prompts
  • Read responses
  • Review results
  • Decide what to do next

The worker Claude isn't a sub-agent.

It's a completely separate Claude Code process running in its own terminal.

Meanwhile, the primary Claude retains all of the context, planning, and decision-making.

You end up with one Claude orchestrating another.

Why Not Just Use a Sub-Agent?

Sub-agents are great for bounded tasks.

But sometimes what you really want isn't a sub-agent.

You want another fully capable Claude Code session.

The challenge is that you don't want to give up the context, planning, and decision-making already accumulated by your current Claude.

You want your existing Claude to stay in charge while delegating work to a fully capable worker.

A tmux-backed Claude worker gives you exactly that.

The primary Claude remains the orchestrator.

The worker Claude remains fully capable.

Minimal Example 

# Create worker session
tmux new-session -d -s worker

# Launch Claude
tmux send-keys -t worker \
  'env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT -u CLAUDE_CODE_SSE_PORT claude' \
  Enter

# Send prompt
tmux send-keys -t worker -l "Review this repository"
tmux send-keys -t worker Enter

# Read output
tmux capture-pane -t worker -p -S -1000
Enter fullscreen mode Exit fullscreen mode

You're not talking to Claude through an API.

You're automating a terminal exactly like a human would.

Gotcha: Claude Doesn't Launch (and Prompts Don't Submit)

There are two things that will almost certainly trip you up the first time you try this.

#1 Nested Claude Sessions Exit Immediately

If you launch Claude from inside an existing Claude Code session, the child process inherits Claude-specific environment variables and immediately exits.

The fix is to clear the inherited variables before launching the worker:

env -u CLAUDECODE \
    -u CLAUDE_CODE_ENTRYPOINT \
    -u CLAUDE_CODE_SSE_PORT \
    claude
Enter fullscreen mode Exit fullscreen mode

#2 send-keys Doesn't Press Enter

My first attempt looked like this:

tmux send-keys -t worker -l "Review this repository"
Enter fullscreen mode Exit fullscreen mode

Nothing happened.

That's because send-keys only types text into the terminal. It doesn't actually submit the prompt.

You need to explicitly send the Enter key:

tmux send-keys -t worker -l "Review this repository"
tmux send-keys -t worker Enter
Enter fullscreen mode Exit fullscreen mode

Once you realize that, the interaction model becomes surprisingly simple:

  • send-keys -l → type text
  • Enter → submit prompt
  • capture-pane → read output

You're not talking to Claude through an API.

You're automating a terminal exactly like a human would.

Human Observability

A human can attach to the worker at any time:

tmux attach -t worker
Enter fullscreen mode Exit fullscreen mode

The orchestrator and a human can now observe the exact same Claude session simultaneously.

Final Thoughts

The interesting part isn't tmux.

It's realizing that you can ask Claude to create more Claudes, assign them work, review their results, and make decisions based on the outcome.

After that, send-keys and capture-pane are just implementation details.

Top comments (0)