Project setup with .sesh/config.json

Every session on its own branch starts with a fresh copy of the project. Before the agent starts, Sesh copies in files git doesn’t track and runs a setup command. A .sesh/config.json file in your repository says exactly what to do. Commit it so everyone gets the same setup.

Without a config file

Sesh looks at your project and guesses:

It finds	It runs
pnpm-lock.yaml, yarn.lock, bun.lock or package-lock.json	pnpm install, yarn install, bun install or npm install
Package.swift	swift package resolve
Cargo.toml	cargo fetch
go.mod	go mod download
Gemfile	bundle install
uv.lock or poetry.lock	uv sync or poetry install

It also copies .env and .env.* files. The chat says what it guessed, and which tools were missing on the machine.

Write your own

Create .sesh/config.json in the root of the repository:

{
  "setup": "pnpm install && pnpm db:migrate",
  "copy": [".env", ".env.local", "config/*.local.json"],
  "baseBranch": "develop",
  "branchPrefix": "sesh/"
}

Once the file exists, Sesh follows it exactly and stops guessing. An empty {} turns everything off.

Keys

Key	What it does	Default
setup	A shell command run in each new session’s folder before the agent starts	Guessed
copy	Files git doesn’t track to copy into each session, as patterns like * and ?	.env, .env.*
baseBranch	The branch new sessions start from	The remote’s default branch
branchPrefix	What session branch names start with	sesh/
forge	Where the repository is hosted, when Sesh can’t tell. See below.	Detected

The setup command gets these variables:

Variable	Value
SESH_ROOT_PATH	Your main project folder
SESH_WORKTREE_PATH	The session’s folder
SESH_SESSION_NAME	The session’s name
SESH_BRANCH	The session’s branch

Setup output shows in the chat as a Setup card. If it fails, the agent starts anyway.

Self-hosted forges

Create Pull Request needs to know where the repository lives. Sesh recognizes GitHub, GitLab, Bitbucket, Azure DevOps, Codeberg, Gitea, Forgejo, Tangled and SourceHut, including most self-hosted ones. If it can’t tell, set it:

{
  "forge": { "type": "gitlab", "webURL": "https://git.company.com/team/app" }
}

type is one of github, gitlab, bitbucket, azure, gitea, forgejo, codeberg, tangled or sourcehut.

Good to know

• copy patterns don’t support **.
• Setup can’t be cancelled and has no time limit.
• Secret files you add in Sesh are copied into new sessions too. See Secrets and variables.