---
name: new-session
description: Launch a fresh Claude Code or Codex session for a structured handoff or an immediately delegated task.
argument-hint: "[--launch] [-w] [-d DIR] [-m MODEL] [--codex-model MODEL] [-P MODE] [-s STYLE] [--bg] [prompt]"
allowed-tools: Bash(new-session:*), Bash(which new-session), Read, Write
---

# New Session

Open a clean Claude Code session in a new pane by default, or a Codex
session when `-m codex` is requested. Use `-w` only when the user asks
for a new window or tab.

## Modes

- **Handoff (default):** preserve context, but do not begin new work. The
  child reads a handoff, summarizes it, and waits for the user.
- **Launch:** immediately execute a delegated task. Use this only when
  `--launch` is present or the user explicitly says to launch, execute,
  or run something.

When intent is unclear, use handoff mode.

## Workflow

1. Confirm that `new-session` is on `PATH`.
2. Choose the working directory: explicit `-d`, the referenced project,
   or the current directory.
3. Choose handoff or launch mode.
4. Prepare the prompt or handoff document.
5. Run `new-session` with the requested routing and options.
6. Report the mode and the returned pane/PID handle.

## Handoff mode

Create a uniquely named temporary Markdown file with this structure:

```markdown
# Handoff: <topic>

> STOP. Read this handoff, gather any additional read-only context needed,
> then quote the User's Last Instruction, summarize your understanding in
> 2-3 sentences, state what this session will do, and wait for the user.

## User's Last Instruction

> <verbatim user instruction>

## Previous Session Summary

<where the work stands>
```

Add key files, confirmed decisions, or open questions only when useful.
Quote user decisions exactly and never present an unresolved idea as a task.

Launch the child with:

```bash
new-session [-w] [-d DIR] [-m MODEL] [-P MODE] \
  "Read <handoff-file> and follow the instructions at the top."
```

## Launch mode

For a small task, pass a direct execution prompt:

```bash
new-session [-w] [-d DIR] [-m MODEL] [-P MODE] "<task>"
```

For a larger task, write a concise execution brief, then tell the child
to read it and begin with a specific first step. The child executes the
delegated work; the parent does not duplicate it.

## Option routing

- `-m codex` selects Codex; `--codex-model MODEL` optionally pins its model.
- Other `-m MODEL` values select a Claude model.
- `-P MODE` overrides the child permission mode.
- `-s STYLE` selects a Claude Code custom output style.
- `--bg` starts a Claude Code background agent and requires a prompt.
- Do not use Claude-only `-s`, `--bg`, or `--continue` options with Codex.

If launch fails, report the error instead of performing the delegated task
in the parent session.