Sesh Docs
sesh.codes
Guides › Project setup with .sesh/config.json

Project setup with .sesh/config.json

Tell Sesh how to get a fresh copy of your project ready for an agent.

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, or starts from a copy where setup already ran. 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
teardown A shell command run in a session’s folder before it’s deleted None
teardownOnArchive Also run teardown when a session is archived false
ports How many ports each session gets for its servers. 0 for none. 1
sessionSetup A shell command run in every new session’s folder after setup, even when setup was skipped. For anything that’s different in each session. None
preparedCopy false runs setup in every new session instead of starting from a prepared copy true
setupInputs More files whose changes mean setup has to run again, besides lockfiles None

Setup output shows in the chat as a Setup card, and session setup’s as a Session setup card. If either fails, the agent starts anyway.

Starting in seconds

Setup can take minutes. So when a session’s setup works, Sesh keeps a copy of that folder, and the project’s next sessions start from it in a second or two instead of running setup again. The chat says when a session started from the copy.

  • Setup runs again on top of the copy when a lockfile or package.json changed since, or anything in .sesh/. Add other files that matter to setupInputs.
  • The copy is rebuilt when you change setup or copy, and after 7 days.
  • It needs a disk that can clone files: APFS on a Mac, Btrfs or XFS on Linux. Elsewhere setup runs every time.

Because later sessions reuse what setup made, put anything that’s different in each session in sessionSetup, which runs every time:

{
  "setup": "pnpm install",
  "sessionSetup": "echo \"PORT=$SESH_SESSION_PORT\" > .env.local"
}

If setup itself uses a session’s own variables (anything but SESH_ROOT_PATH), Sesh doesn’t keep a copy for it, and the chat says so. If setup does work outside the folder that sessionSetup can’t take over, set "preparedCopy": false.

Session variables and ports

Setup, teardown, the agent and the session’s terminals all get these variables:

Variable Value
SESH_SESSION_ID The session’s ID
SESH_SESSION_NAME The session’s name
SESH_BRANCH The session’s branch
SESH_ROOT_PATH Your main project folder
SESH_WORKTREE_PATH The session’s folder
SESH_SESSION_PORT A port for this session’s server

No two live sessions on a machine get the same port, so dev servers in parallel sessions don’t collide. Tell your server to use it, for example in package.json:

"dev": "vite --port ${SESH_SESSION_PORT:-5173}"

Need more than one? Set "ports": 3 to get SESH_SESSION_PORT, SESH_SESSION_PORT_1 and SESH_SESSION_PORT_2, one after another. A session keeps its ports until it’s archived or deleted. Servers on these ports show in the toolbar like any other.

Tear down

If a session starts things that outlive it, like containers or a scratch database, start them in sessionSetup and undo them in teardown:

{
  "setup": "pnpm install",
  "sessionSetup": "docker compose -p \"$SESH_SESSION_ID\" up -d",
  "teardown": "docker compose -p \"$SESH_SESSION_ID\" down -v"
}
  1. Delete runs it in the session’s folder before the folder is removed. It shows in the chat as a Teardown card.
  2. If it fails or runs longer than 2 minutes, the session is deleted anyway, and Sesh shows what went wrong.
  3. With "teardownOnArchive": true, Archive runs it too. Setup and session setup then run again before the agent next starts.

A session nothing has run in yet has nothing to tear down, so teardown is skipped.

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.
  • Teardown reads .sesh/config.json from your main project folder, not the session’s copy. Sessions with New branch off work in that folder itself, so they get no teardown.
  • To give sessions ports from another range on a machine, start seshd with SESH_PORT_RANGE=30000-30999.
  • Secret files you add in Sesh are copied into new sessions too. See Secrets and variables.