> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Persistence

> Detach and reattach to Fresh sessions, similar to tmux, with client-server architecture

<Warning>
  This feature is experimental. The API and behavior may change.
</Warning>

Detach from Fresh and reattach later, similar to tmux. Your editor state persists even after closing the terminal.

## Quick Start

```bash theme={null}
# Start or attach to a session for the current directory
fresh -a

# Detach: press Ctrl+Shift+D (or use Command Palette > "Detach")
# Terminal closes, but Fresh keeps running in the background

# Reattach later from the same directory
fresh -a

# List all running sessions
fresh --cmd session list
```

## Direct vs Session Mode

| Command            | Mode    | Description                                  |
| ------------------ | ------- | -------------------------------------------- |
| `fresh myfile.txt` | Direct  | No server. Closing quits everything.         |
| `fresh -a`         | Session | Background server. Supports detach/reattach. |

<Tip>
  Use session mode for long-running tasks or SSH sessions where connection may drop.
</Tip>

## How It Works

With `-a`, Fresh starts a background server. The terminal is a lightweight client relaying input/output.

```
Terminal (Client)  ←→  Unix Socket  ←→  Fresh Server (Background)
     ↓                                        ↓
  Your keyboard                         Editor state
  Your screen                           Open files
                                        Running terminals
```

Detaching exits only the client; the server keeps running.

## Commands

### Basic Commands

| Command                           | Description                                                       |
| --------------------------------- | ----------------------------------------------------------------- |
| `fresh -a`                        | Attach to session for current directory (starts server if needed) |
| `fresh -a <name>`                 | Attach to named session                                           |
| `fresh --cmd session list`        | List running sessions                                             |
| `fresh --cmd session new <name>`  | Start a new named session                                         |
| `fresh --cmd session kill`        | Kill session for current directory                                |
| `fresh --cmd session kill <name>` | Kill named session                                                |
| `fresh --cmd session kill --all`  | Kill all sessions                                                 |

### Named Sessions

For multiple sessions in the same directory:

```bash theme={null}
fresh --cmd session new feature-work
fresh --cmd session list
fresh -a feature-work
```

## Opening Files in a Session

Open files in an existing session without attaching to it. If no session is running, one is started and the client attaches interactively:

<CodeGroup>
  ```bash Current Directory theme={null}
  # Open file in current directory session (use "." for session name)
  fresh --cmd session open-file . src/main.rs
  ```

  ```bash Specific Line theme={null}
  # Open file at specific line and column
  fresh --cmd session open-file myproject src/lib.rs:42:10
  ```

  ```bash Multiple Files theme={null}
  # Open multiple files
  fresh --cmd session open-file . file1.rs file2.rs
  ```
</CodeGroup>

<Info>
  This is useful for integrating Fresh with file managers or other tools—files open in the existing editor without starting a new terminal session.
</Info>

## Blocking Until Done (`--wait`)

The `--wait` flag keeps the CLI process alive until the user is done with the file. The process exits when:

* The **popup is dismissed** (press Escape) — if the file was opened with an `@"message"`
* The **buffer is closed** — if no message was given

```bash theme={null}
# Open a file and block until the user closes the buffer
fresh --cmd session open-file . src/main.rs --wait

# Open at a line with a popup message — blocks until popup is dismissed
fresh --cmd session open-file . 'src/main.rs:42@"Review this function"' --wait
```

<Note>
  If no session is running, one is started automatically and the client attaches interactively (`--wait` is ignored in this case — quit or detach normally).
</Note>

### Use as Git's Editor

Set Fresh as git's editor so `git commit`, `git rebase -i`, etc. open in your running session and block until you close the buffer:

```bash theme={null}
git config --global core.editor 'fresh --cmd session open-file . --wait'
```

<Info>
  Git appends the filename, so the final command becomes e.g. `fresh --cmd session open-file . --wait .git/COMMIT_EDITMSG`. The `--wait` flag can appear anywhere after the session name — files after it are collected normally.
</Info>

### Annotated Code Walkthroughs

Combine `--wait` with range selection and popup messages to walk a user through code one location at a time. Each command blocks until the user presses Escape, then the next location opens:

```bash theme={null}
fresh --cmd session open-file . 'src/parse.rs:10-25@"Step 1: The parser entry point"' --wait
fresh --cmd session open-file . 'src/eval.rs:80-95@"Step 2: Expression evaluation"' --wait
fresh --cmd session open-file . 'src/emit.rs:5@"Step 3: Code generation starts here"' --wait
```

Popup messages support markdown. Use `$'...'` quoting for multi-line messages:

```bash theme={null}
fresh --cmd session open-file . \
  $'src/main.rs:1-15@"**Overview**\n\nThis is the entry point.\nNote the error handling on line 12."' --wait
```

### Programmatic Integration

The `--wait` blocking behavior makes `session open-file` composable with any tool that needs to present files to a user and wait for acknowledgement:

<CodeGroup>
  ```bash Code Review Script theme={null}
  # Code review script
  for file in $(git diff --name-only HEAD~1); do
    fresh --cmd session open-file . "$file@\"Review this file\"" --wait
  done
  ```

  ```bash Step Through Grep Matches theme={null}
  # Step through grep matches
  grep -rn "TODO" src/ | while IFS=: read -r file line _; do
    fresh --cmd session open-file . "$file:$line@\"TODO found here\"" --wait
  done
  ```
</CodeGroup>

## Detaching

<Steps>
  <Step title="Detach vs Quit">
    * **Detach** (`Ctrl+Shift+D` or Command Palette → "Detach" or File → Detach Session): Client exits, server keeps running
    * **Quit** (`Ctrl+Q`): Both client and server exit
  </Step>
</Steps>

## Limitations and Pitfalls

<AccordionGroup>
  <Accordion title="Resource Usage">
    Each session consumes memory for open files, terminal scrollback, and LSP servers. Use `fresh --cmd session list` periodically to check for forgotten sessions.
  </Accordion>

  <Accordion title="Terminal State">
    When reattaching, terminal size may differ and some applications may not render correctly after resize. Scrollback is preserved but limited by buffer size.
  </Accordion>

  <Accordion title="Platform Differences">
    | Platform    | IPC Mechanism       |
    | ----------- | ------------------- |
    | Linux/macOS | Unix domain sockets |
    | Windows     | Named pipes         |
  </Accordion>

  <Accordion title="Known Issues">
    1. **Stale sockets**: If Fresh crashes, socket files may remain. See [Socket Locations](#socket-locations) for cleanup.
    2. **Signal handling**: Some signals don't propagate to server terminals.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection refused">
    Server may have crashed. Run `fresh --cmd session kill` to clean up, then `fresh -a` again.
  </Accordion>

  <Accordion title="Session not in list">
    Sessions are keyed by working directory. `~/project` and `/home/user/project` create different sessions—use consistent paths.
  </Accordion>

  <Accordion title="High memory usage">
    Check for forgotten sessions with `fresh --cmd session list`.
  </Accordion>
</AccordionGroup>

## Socket Locations

| Platform | Location                                        |
| -------- | ----------------------------------------------- |
| Linux    | `$XDG_RUNTIME_DIR/fresh/` or `/tmp/fresh-$UID/` |
| macOS    | `/tmp/fresh-$UID/`                              |
| Windows  | `%LOCALAPPDATA%\fresh\sockets\`                 |