New, resume, rename, delete

What a session is

A session is the persistent conversation for one working directory: your prompts, the assistant’s replies, tool calls, the TODO list, rewind points, and token counts. Matcha CLI gives each one a session ID (a UUIDv7 unless you pass -s when creating a new session) and stores it under ~/.matcha/sessions/. Set MATCHA_HOME to move that home directory.

Launching matcha already starts a session. Use the commands below when you want a second one, or when you want yesterday’s work back.

Start fresh: `/new`

In an open conversation:

/new

Alias: /clear.

This clears the on-screen context and begins a new conversation. The previous session stays on disk unless you delete it. /new does not take arguments.

To leave the conversation and stay in Matcha CLI, use /home (alias /welcome) instead of /new. To quit entirely, use /quit (alias /exit).

Continue the most recent session: `matcha -c`

From the project directory where you last worked:

matcha -c

That is --continue. It reopens the most recent session for the current working directory — TUI if you pass no prompt, or headless if you also pass -p.

matcha -c
matcha -p "What were we doing?" -c

Resume a specific session

In the TUI: `/resume`

/resume

The command takes no arguments. It opens a picker of recent sessions for this workspace.

1. Type to filter by title. The picker also searches conversation content; those hits appear under **Extended search results**.
2. Press Ctrl+/ to search immediately, without the brief pause.
3. Select a row to resume it.

The welcome screen lists the same recent sessions. Pick one there instead of running /resume.

From the shell: `matcha --resume`

matcha --resume
matcha --resume <session-id-or-title>

Short form: -r.

• No value (or matcha --resume alone) resumes the most recent session for this directory, same idea as matcha -c.
• A value that looks like a UUID is always treated as a session ID, never as a title.
• Any other value is matched against titles for this directory, ignoring letter case. Handy after /rename. If several sessions share the title, a single **manually renamed** session wins; otherwise the command errors and lists the matching IDs.

Scripts should pass the session ID. A hidden alias --load <SESSION_ID> exists for the ID path only.

Rename: `/rename`

/rename <title>

Alias: /title. The title is required. There must be an active session.

The new title is what --resume and the picker show. Rename before you leave if you plan to find the session by words instead of by ID.

Delete

This session: `/delete`

/delete

Matcha CLI asks first. On confirm it stops the running turn, background tasks, and sub-assistants, then removes the history. You return to the welcome screen, or to the dashboard if you opened the session from there.

/delete has no arguments and requires an active session.

Another session, from a list

• In /resume or on the welcome session list: press d, then y.
• On the assistant dashboard: Ctrl+X twice, or the [✗] control.

From the shell: `matcha sessions delete`

matcha sessions delete <session-id>

Pass the ID from matcha sessions list. The command looks up the ID across workspaces (it does not require you to be in the original directory).

List and search from the shell

matcha sessions always needs a subcommand:

matcha sessions list
matcha sessions list --limit 50
matcha sessions search "rate limit"

list (default --limit 20) shows sessions for the current working directory, grouped by worktree label. Each row has the session ID, created and updated dates, a source column, and a short summary.

search matches titles and prompts in the local index. Use it to find an ID, then --resume that ID or delete it.

What you should see