--- title: Sessions description: Start, list and message Dray sessions from the command line, with every flag for model, effort, agent, base branch, issues and fast mode. sidebar: order: 2 --- `dray session` starts and manages the same sessions you see in the sidebar. A session made here is an ordinary session: you can open it, read it, stop it or delete it like any other. Run from inside a Dray session, every command knows which session is calling. A new session is nested under the caller and inherits its settings. Run from your own terminal, there is no caller, so the app's defaults apply. ## Start a session ```bash dray session new "Fix the login redirect loop. Steps to reproduce: …" ``` Prints the new session's id, then a line like `Started "Fix login redirect loop" in worktree calm-owl`. It returns at once: the session starts working on its own and nothing waits for it. Write the prompt for someone who has not read your conversation. The new session starts with no context. | Flag | What it does | Default | |---|---|---| | `--project ` | The repo to run in. | The git repo you are in, then the calling session's project. | | `--model ` | A model the agent knows, like `opus`, `sonnet`, `fable` or `haiku` on Claude Code, or a `provider/model` id on pi. | The calling session's model, if the agent is the same. Otherwise the agent's own default. | | `--effort ` | `low`, `medium`, `high`, `xhigh`, `max` or `ultra`. | The calling session's effort, if the agent is the same. Otherwise the model's default. | | `--harness ` | Which agent runs it: `claude_code`, `codex`, `pi`, `fx` or `grok`. | The calling session's agent, else Claude Code. | | `--base ` | Start the worktree from existing work: a session id, a branch, a tag or a commit. Committed work only. | `origin/` | | `--title ` | The session's title. | One generated from the prompt. | | `--issue <ID>` | An issue this work is against, like `DRA-53` or `owner/repo#12`. Repeat for several. | None. | | `--fast` | Run at the agent's faster tier, which uses more of your plan. | The calling session's setting, if the agent is the same. | | `--hidden` | Keep the session out of the sidebar. It shows only in the calling session's crew. Needs a calling session. | Off. | `--from` is an older name for `--base` and still works. ```bash dray session new --harness codex --effort high "Port the retry logic to the Go client" dray session new --model opus --fast "Rename the config keys listed below …" dray session new --issue DRA-53 --title "Add the issue panel" "Build the issue panel described in DRA-53" ``` ### Always a worktree Every session made here gets its own git worktree on its own branch, `worktree-<name>`. There is no flag to turn that off and no flag to pick the name. Sessions started this way run at the same time, and two agents in one checkout overwrite each other. The worktree starts at `origin/<default branch>`, not at the branch you are on. So a plain new session cannot see unpushed work. Pass `--base` to start it from a session's branch or any ref; see [Orchestration](/docs/cli/orchestration#review-with-a-second-model). ### What a new session inherits From the calling session it takes the agent, the model, the effort, fast mode and the permission mode. Each of these but the permission mode can be overridden with a flag. The model, effort and fast mode only carry over when the new session uses the same agent. A Codex session started from a Claude Code one takes Codex's own defaults, since the two have different models and their effort levels do not match. There is no flag for the permission mode. A new session runs under the caller's, or the app's default with no caller. See [Orchestration](/docs/cli/orchestration#permission-prompts). The new session inherits no conversation. Put everything it needs in the prompt. ### How deep it can go A session you start from the composer may create sessions. Those may create sessions too. Their sessions may not. Past that, `dray session new` and `dray draft start` are refused with a message saying so. Start the next batch from a top-level session. ## List sessions ```bash dray session ls ``` One line per session: id, status, title, branch. A session created by another one also says `spawned by <id>`, and a hidden one says `hidden`. | Flag | What it does | |---|---| | `--all` | Every project, not just this one. | | `--project <path>` | List this repo instead of the one you are in. | | `--json` | One JSON array, for scripts. Each entry carries `sessionId`, `title`, `cwd`, `projectPath`, `branch`, `worktreeName`, `status`, `modified`, `parentSessionId` and `hidden`. | Status is `idle`, `in_progress` or `completed`. `completed` means the turn finished and nobody has opened the session since. Settled sessions are not listed. Nothing reports back on its own when a session finishes. To find out, check `dray session ls`, or have the session [message you](#send-a-message). ## Send a message ```bash dray session send 0198f0a2-1c5e-7000-8000-000000000000 "The API moved to /v2. Update the client to match." ``` The message arrives as an ordinary prompt and starts a turn, so it wakes an idle session. If the session is mid-turn, the message is queued and picked up next; `dray` says `Queued — the session is mid-turn and will pick it up.` That is not a failure. Sent from inside a session, the receiving agent is told which session sent it, with its id, so it can reply with `dray session send`. A message never changes the receiving session's model, effort or permission mode. ## Rename, stop, settle ```bash dray session rename <id> "Add retry to the upload client" dray session stop <id> dray session settle <id> dray session settle <id> --delete-worktree dray session unsettle <id> dray session set-aside <id> dray session unset-aside <id> ``` | Command | What it does | |---|---| | `rename <id> <title>` | Renames the session. Your title stays: no generated one replaces it. | | `stop <id>` | Stops the running turn, like the Stop button. | | `settle <id>` | Stops the session and moves it out of the active list. Its worktree stays. Refused while a turn is running. | | `settle <id> --delete-worktree` | Also deletes the worktree and its branch, whatever they hold, uncommitted and unpushed work included. Nothing asks first. | | `unsettle <id>` | Brings a settled session back to the active list. | | `set-aside <id>` | Sinks the session to the bottom of the sidebar: started, not wanted now. | | `unset-aside <id>` | Takes it out of set-aside. | These are the same as the sidebar's buttons. Settling a session also settles the hidden sessions it started. ## Limits - No flag sets the permission mode, the worktree name, or turns the worktree off. - `--fast` can only turn fast mode on. Leaving it off inherits the caller's setting. - `--base` sees committed work only. Changes not yet committed are not in the new worktree. - A model that has no faster tier runs at its normal speed with `--fast`, and nothing says so. - You cannot read a session's transcript from here.