Skip to main content
This feature is experimental. The API and behavior may change.
Detach from Fresh and reattach later, similar to tmux. Your editor state persists even after closing the terminal.

​
Quick Start

# 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

CommandModeDescription
fresh myfile.txtDirectNo server. Closing quits everything.
fresh -aSessionBackground server. Supports detach/reattach.
Use session mode for long-running tasks or SSH sessions where connection may drop.

​
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

CommandDescription
fresh -aAttach to session for current directory (starts server if needed)
fresh -a <name>Attach to named session
fresh --cmd session listList running sessions
fresh --cmd session new <name>Start a new named session
fresh --cmd session killKill session for current directory
fresh --cmd session kill <name>Kill named session
fresh --cmd session kill --allKill all sessions

​
Named Sessions

For multiple sessions in the same directory: 
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: 
# Open file in current directory session (use "." for session name)
fresh --cmd session open-file . src/main.rs
This is useful for integrating Fresh with file managers or other tools—files open in the existing editor without starting a new terminal session.

​
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
# 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
If no session is running, one is started automatically and the client attaches interactively (--wait is ignored in this case — quit or detach normally).

​
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: 
git config --global core.editor 'fresh --cmd session open-file . --wait'
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.

​
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: 
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: 
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: 
# Code review script
for file in $(git diff --name-only HEAD~1); do
  fresh --cmd session open-file . "$file@\"Review this file\"" --wait
done

​
Detaching

1

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

​
Limitations and Pitfalls

Each session consumes memory for open files, terminal scrollback, and LSP servers. Use fresh --cmd session list periodically to check for forgotten sessions.
When reattaching, terminal size may differ and some applications may not render correctly after resize. Scrollback is preserved but limited by buffer size.
PlatformIPC Mechanism
Linux/macOSUnix domain sockets
WindowsNamed pipes
  1. Stale sockets: If Fresh crashes, socket files may remain. See Socket Locations for cleanup.
  2. Signal handling: Some signals don’t propagate to server terminals.

​
Troubleshooting

Server may have crashed. Run fresh --cmd session kill to clean up, then fresh -a again.
Sessions are keyed by working directory. ~/project and /home/user/project create different sessions—use consistent paths.
Check for forgotten sessions with fresh --cmd session list.

​
Socket Locations

PlatformLocation
Linux$XDG_RUNTIME_DIR/fresh/ or /tmp/fresh-$UID/
macOS/tmp/fresh-$UID/
Windows%LOCALAPPDATA%\fresh\sockets\

Build docs developers (and LLMs) love

Get started for freeTalk to us