agent-child

Fork your AI agent session into tmux split panes. Child agents die when the parent exits.

You're deep in a Claude Code (or Gemini CLI, Codex, ...) session and want to hand a task to a second agent with the same context — without losing your main session, and without orphaned processes hanging around afterwards. agent-child gives you a /child command (and a standalone child CLI) that:

• Forks the current session into a new tmux pane — for Claude Code it uses claude --resume <session> --fork-session, so the child starts with your full conversation history.
• Smart 50-50 splits — each new child splits the largest pane in the window, always exactly 50-50, side-by-side when that pane is wide and stacked when it's tall. Repeated /child calls therefore produce a balanced, visually pleasing layout (halves → quadrants → …) instead of ever-thinner slivers. Children live in a dedicated tmux session if the parent isn't running inside tmux.
• Ties child lifetime to the parent — every child pane runs a watchdog on the main agent's PID. When the main agent exits, every child pane (and the tmux session created for them) is killed automatically. No orphans.
• Works with any agent — --agent gemini, --agent codex, or --cmd "anything".

┌─────────────────────────────┬──────────────────┐
│                             │ child #1         │
│   main agent                │ (forked session) │
│   (claude)                  ├──────────────────┤
│                             │ child #2         │
│                             │ (gemini)         │
└─────────────────────────────┴──────────────────┘
        main exits  ──►  all children killed

Install

Requires tmux (brew install tmux / apt install tmux).

One-liner (installs child to ~/.local/bin and the /child command to ~/.claude/commands):

curl -fsSL https://raw.githubusercontent.com/rosehgal/agent-child/main/install.sh | bash

As a Claude Code plugin:

/plugin marketplace add rosehgal/agent-child
/plugin install agent-child@agent-child

From a clone: git clone https://github.com/rosehgal/agent-child && cd agent-child && ./install.sh

Use

Important: tmux can only split a window it owns — it cannot split a plain terminal from the outside. To get child panes appearing in the same window as your main agent, the agent must be started inside tmux.

The installer takes care of this automatically: it adds alias claude='childmux claude' to your shell rc (Claude Code has no native setting for this — its --tmux flag only works with --worktree), so every new claude session transparently starts inside tmux and is splittable. It also enables tmux mouse support (set -g mouse on in ~/.tmux.conf), so you can click a pane to focus it and drag borders to resize. Set CHILD_NO_ALIAS=1 when running the installer to skip the alias.

For other agents, or if you skipped the alias, use childmux directly:

childmux                     # starts claude inside tmux, splittable
childmux claude --continue   # or any agent command
childmux gemini

If you start your agent without tmux, /child still works — children are collected in a background tmux session you can attach to (the attach command is printed) — but the window you're typing in won't visually split.

Navigating panes: click with the mouse (enabled by the installer), or Ctrl+b + arrow keys to move between panes, Ctrl+b z to zoom a pane fullscreen (toggle), Ctrl+b x to kill one, Ctrl+b d to detach.

Shift+Enter: tmux swallows modified keys by default, which breaks Claude Code's Shift+Enter (newline) in every pane. The installer fixes this by enabling extended-keys in ~/.tmux.conf. If you installed while a tmux server was already running, restart it once (tmux kill-server) to pick the fix up. If Shift+Enter still doesn't work, your terminal emulator isn't sending the key — run /terminal-setup once inside Claude Code to configure it.

Updating

On any machine where it's installed:

child --update

That re-downloads the latest scripts and command from GitHub and refreshes the config (all config edits are idempotent). Equivalently, re-run the curl one-liner, or git pull && ./install.sh in a clone. Plugin users: /plugin marketplace update agent-child.

Inside Claude Code:

/child go fix the flaky tests while I keep working here
/child --agent gemini review this diff for security issues

Or from any shell / any agent's bash tool:

child "continue debugging the auth issue"        # fork current claude session
child --agent gemini "summarize recent commits"  # different agent, same pane management
child --cmd "npm run dev"                        # any long-running command
child --no-fork "fresh claude, no shared history"
child --list                                     # live children of this main agent
child --killall                                  # kill them all now

If the main agent is running inside tmux, children appear as splits in the same window and focus stays on the main pane. If it isn't, children are collected in a detached tmux session named child-<main-pid> — attach with tmux attach -t child-<pid> (printed on spawn), or pass --open on macOS to pop a Terminal window automatically.

How it works

1. child walks up its process ancestry to find the main agent process (claude, gemini, codex, cursor-agent, aider, ...). That PID becomes the lifetime anchor. (Override with --main-pid.)

2. For Claude Code it resolves the current session ID (env var, --session, or the newest transcript in ~/.claude/projects/<project-slug>/) and launches claude --resume <id> --fork-session — a true fork: same history, new session ID, fully independent from then on.

3. The child runs inside a tiny wrapper in the tmux pane:

   ( while kill -0 $MAIN_PID; do sleep 2; done
     tmux kill-pane -t "$TMUX_PANE" ) &
   exec <child agent command>

   The agent owns the pane's TTY in the foreground; the watchdog polls the main PID and kills the pane the moment the parent is gone. When the child exits on its own, the pane closes naturally. When the last pane in a dedicated child-<pid> session dies, tmux removes the session too.

Options

Flag	Meaning
--agent <name>	Agent CLI to run (default claude)
--cmd "<command>"	Arbitrary command instead of an agent
--session <uuid>	Claude session ID to fork (default: auto-detect)
--no-fork	Fresh Claude session instead of forking
--main-pid <pid>	Override the lifetime-anchor PID
--open	macOS: open Terminal attached to the child session
--list / --killall	Inspect / kill this parent's children
--update	Update agent-child to the latest version from GitHub

Limitations

• Session forking is Claude Code-specific (it's the only CLI with --resume --fork-session); other agents start fresh sessions in managed panes with the same lifecycle guarantees.
• Forking the currently-live session can race with Claude Code persisting it: right after heavy activity the session isn't resumable yet, and claude --resume fails with "No conversation found". When that happens the child automatically falls back to a fresh session (with your prompt, if any) so the pane still opens instead of vanishing — you just don't inherit the chat history for that one. Retrying a moment later usually forks cleanly.
• The watchdog polls every 2 s, so children outlive the parent by at most ~2 s.
• PID reuse is theoretically possible on very long-lived systems; --killall is your escape hatch.

License

MIT