Usage

Directories

Open the current directory:

srcz .

Or another directory:

srcz path/to/markdown

With the desktop app installed, srcz [path] opens the directory in it and exits. Without it, or with --host or --port, it serves in a browser, as srcz browser [path] does. On a machine without a UI (an SSH session, or Linux without a display) it tells you to run srcz [path] --remote, which prints a srcz connect command to run on your computer (Remote hosts).

srcz browser [path] always serves in a browser and takes the same flags. Subcommand names take precedence over directories, so open a directory named browser, walkthrough, or daemon as srcz ./browser, srcz ./walkthrough, or srcz ./daemon.

Serve several directories with a repeatable --path (a positional path is shorthand for one); overlapping directories fail before starting:

srcz --path ~/work --path ~/personal

Projects and worktrees

Source Zero looks for git repositories (including linked worktrees) up to --scan-depth folders deep in each directory (default 10; 0 checks only the served directories) and lists them in the project picker (Cmd/Ctrl+O). It stops descending at a repository and skips hidden, node_modules, and vendor folders. Only one project is read at a time, and every switch reads it from disk. Each switch restores that project's tabs and expanded folders, including after reloads. --depth limits the file tree within a project.

A repository opens whole: its own folders cannot be opened as projects, and Open folder only browses folders outside repositories. A repository with worktrees is one picker entry that opens the last-used worktree; press → (or click its arrow) to choose a worktree by branch. Worktrees of a served repository open wherever they live, even outside the served directories. Repositories are named after their origin remote, else their folder. The explorer header shows the repository and branch; when the repository has worktrees, click the branch to switch. Linked worktrees get a colored fork icon.

Welcome

A project that opens with no tabs to restore shows the Welcome tab: shortcuts to open a project, find a file, and run a command; the project's branch, uncommitted changes, and walkthroughs; every served project (when there is more than one) with a filter and each repository's worktrees; and a short guide in which every entry runs what it describes. Click Source Zero in the status bar, or run Help › Welcome from the command palette, to open it again. Turn it off with Workbench › Show Welcome on Startup in Settings; the project picker then opens on the first launch instead.

With no tab open, the document area names what the current sidebar view offers: a file to choose, a search to run, changes to review, or a walkthrough to start.

Host and port

Without --port, Source Zero uses the first free port from 7971 through 7980. Use --host to bind a specific IP address or --port to select an exact port.

Setting either one always serves in a browser. For parallel agent sessions or worktrees, use a different port for each server, or let the OS select an available port:

srcz . --port 8123 --no-open
srcz . --port 0 --no-open

Use the URL printed at startup. Each server serves its own roots and stops independently. An occupied explicit port fails without stopping another server. Open Source Zero by localhost or an IP address; other hostnames are refused, so websites cannot reach it through DNS rebinding. If the range is full, Source Zero can stop all verified instances after confirmation.

Files

Every file within --depth is served, whatever its type. .git, node_modules, and vendor folders are always skipped, and .git files are always hidden.

The explorer's filename filter accepts comma-separated glob patterns in Go path.Match syntax (*, ?, [...]), matched case-insensitively against each file's base name. It only changes tree visibility, preserving open documents. Global content search covers every served text file regardless of the tree filter. Markdown image dependencies remain available within the served root. Source Control lists and diffs every change and commit in the repository checkout, regardless of --depth and skipped folders.

Daemon

srcz daemon is plumbing for the desktop app: one long-lived Source Zero per user, reachable only through a private Unix socket (macOS and Linux), whose directories are added while it runs and remembered across restarts. Clients start it on demand; it stops after 30 minutes without requests. To check on it or stop it:

srcz daemon status
srcz daemon stop

srcz daemon ensure starts it unless it is running; --json prints status as JSON.

All options

srcz --help
srcz daemon run --help

srcz daemon subcommands take --socket to use another socket path; run and ensure also take --depth, --scan-depth, and --idle-exit (0 never stops).