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.jsonchanged since, or anything in.sesh/. Add other files that matter tosetupInputs. - The copy is rebuilt when you change
setuporcopy, 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"
}
- Delete runs it in the session’s folder before the folder is removed. It shows in the chat as a Teardown card.
- If it fails or runs longer than 2 minutes, the session is deleted anyway, and Sesh shows what went wrong.
- 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
copypatterns don’t support**.- Setup can’t be cancelled and has no time limit.
- Teardown reads
.sesh/config.jsonfrom 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.