Sessions and Working directory Guide

Overview

This chapter introduces two closely related core concepts in the CLI: sessions and workspaces (working directories). It applies to the following scenarios:

• Resuming a previously unfinished conversation and continuing with the existing context.
• Switching between multiple projects and having the agent automatically use the corresponding working directory.
• Understanding the difference between /cd and the traditional shell cd.

This chapter covers:

• Sessions
• Workspaces (working directories)
• How sessions and working directories are bound together

Relationships Between the Commands

In the CLI, sessions and working directories are managed together:

• The startup wizard asks about both the session and the working directory.
• When you restore a historical session, its bound working directory is restored automatically.
• Within a session, /session switches sessions and /cd switches the working directory.
• Each session records its most recently used working directory and loads it automatically when the session is later restored.

Sessions

What Is a Session?

A session is an independent conversation context in the CLI, containing:

• The multi-turn conversation history between the user and the agent.
• The working directory bound to the current session.
• The agent’s internal runtime state.

Each session corresponds to a unique session_id.

Whenever the CLI starts a session, the same session_id is reused within the same process.

Choosing a Session in the Startup Wizard

After you run unitarylab, the wizard reaches the “Session” step and offers the following options:

• New session: Create a brand-new conversation context.
• One of the 8 most recent sessions: Restore from history.
• Enter a session_id manually: Restore an older session that does not appear in the recent list.

If the chosen session already has a bound working directory, the subsequent “Working Directory” step is skipped automatically, and the corresponding directory is restored directly.

Viewing and Switching Sessions

If you just want to browse recent work without interrupting your current progress, run /sessions (which shows the five most recent by default) or /sessions 10 to list more historical sessions.

When you decide to switch contexts, run /session at any time during a session.

The CLI also provides several shortcuts for quick switching:

• /session latest: Switch directly to the most recently used session, skipping the selector.
• /session <N>: Quickly restore by list position — for example, /session 1 restores the most recent session.

Interactive selection example:

[agent│deepseek-v4-pro] › /session
? Choose a session:
  ✦ New session
  ○ abc123…  05-06 14:26  1 turn   hello
  ○ def456…  05-05 11:12  12 turns explain Shor's algorithm
  ✎ Enter a session id manually
  Cancel
✓ session    →  abc123…  1 turn  hello
✓ workspace  →  /Users/alice/unitarylab/test

Once the switch is complete, subsequent conversation immediately continues from the new session context.

Session History and Bookmark Management

In a long-running session that contains dozens or hundreds of turns, you may need to revisit a previous derivation or look up a particular snippet of code. The CLI provides a full set of history-review tools:

• Review historical turns: Use /history to quickly browse summaries of the 10 most recent turns. To see the full output of a particular turn, use /show <turn> (for example, /show 12 expands the details of turn 12).
• Full-text search: Within the current session, use /search <keyword> to perform a precise search across all of the session’s history.
• Bookmarks: After solving a tricky bug or reaching an important conclusion, run /bookmark <important progress> to tag the current turn. Later, run /bookmarks to recall all your highlighted moments, which makes managing long-form context far more effective.

Deleting Sessions

The CLI lets you delete sessions you no longer need directly from within a session to keep your history list clean. Before deleting, a summary confirmation is displayed, including the number of turns, history entries, bookmarks, the bound working directory, and the first message summary.

Example deletion confirmation:

[agent│deepseek-v4-pro] › /session delete current
? Confirm deletion of current session?
  Session: abc123…
  Turns: 12
  History entries: 24
  Bookmarks: 2
  Working directory: ~/unitarylab/pde
  First message: Help me solve a 1D heat equation
  Confirm? (y/N)

Deletion cannot be undone. Check with /sessions first to make sure you are targeting the right session.

Workspaces (Working Directories)

What Is a Working Directory?

The working directory is the root directory the agent uses for file read and write operations.

All file-related tools (including reading, writing, and downloading to local disk) resolve paths relative to the current working directory.

The working directory in the CLI is the agent’s logical file root; it is not the same as the shell’s current directory. /cd only affects what files the agent can access — it does not change the actual working directory of your terminal process. After you exit the session, you’ll still be in the directory you launched the CLI from.

/cd <path>

/cd is used to change the current working directory.

Example:

[agent│deepseek-v4-pro] › /cd pde
✓ workspace → /Users/alice/unitarylab/pde

Behavior:

• Relative paths: Resolved against the current workspace.
• ~ expansion: Automatically expands to your home directory.
• Persistent binding: Each /cd binds the new working directory to the current session.
• Takes effect immediately: The new working directory takes effect on the next conversation turn — no process restart is required.

/pwd

Displays the absolute path of the current working directory:

[agent│deepseek-v4-pro] › /pwd
/Users/alice/unitarylab/pde

How Sessions and Working Directories Are Bound

The CLI persists the “session → working directory” binding in the following situations:

• When entering a session (both when creating a new session and when restoring an existing one).
• When you run /cd to change the working directory.
• When you run /session to switch sessions.

The binding is stored in a local database, so you usually don’t need to run /cd repeatedly.

Example:

1. On day one, you launch the CLI in ~/projectA and create session abc123….
2. On day two, you choose abc123… again.
3. The CLI automatically restores the working directory to ~/projectA.

If you then run:

/cd ~/projectB

the next time you restore abc123…, it will automatically enter ~/projectB.

Recommendations

• Create a separate session for each project. We recommend a dedicated session per project so that the working directory switches automatically with the session, avoiding repeated /cd calls.

• Distinguish quick exploration from long-running tasks. Use a new session for ad-hoc experiments; for long-running tasks, stick to a dedicated session so that context can be restored continuously.

• Make good use of bookmarks. For long-running tasks, develop the habit of using /bookmark to record milestones — this will make later reviews and /search queries much smoother.