Projects and environments
The repository a thread works in, its worktree, and the setup that runs before the agent starts
A project is the repository a thread works in. Pick it in the new-thread composer, in the same picker as the branch to start from:
- A folder on this Mac: a repository you already have checked out. It's available to threads on this Mac.
- A GitHub repository: any repository your GitHub App installations reach, found by typing its name. A thread on one runs on the device you pick: Keko Cloud, This Mac, or another of your Macs and servers, which clones it, private ones included.
On This Mac, a checkout of the repository you already have comes first: Your checkout works in it, and A fresh
copy clones it into ~/.keko/projects/github/<owner>/<name>. Without one, Link a folder picks a checkout
somewhere else. Settings → Projects lists the copies and the devices they're on.
The worktree
Every thread gets its own git worktree on a new branch, keko/ followed by a short form of the thread's title,
made from the branch you picked. Threads never share a working folder, so several can work on one repository at once.
Before the agent starts, the worktree is set up:
- Dependencies: for npm and yarn projects,
node_modulesfolders are cloned from your checkout using the disk's copy-on-write clones. pnpm and bun already link from their own store, so for them nothing is cloned. - Update: the project's update commands run (below). Without any, the install for the lockfile at the top of the
repository runs:
pnpm install --prefer-offline,bun install,yarn install --prefer-offlineornpm install --prefer-offline --no-audit --no-fund.
While this runs the thread shows "Setting up", with the command and how long it's taken. A failed setup doesn't block the thread: it starts anyway and says what failed.
The setup file
A project can describe its own setup in .keko/setup.json at the top of the repository:
{
"initialize": ["pnpm install", "pnpm build:deps"],
"update_after_checkout": "pnpm install --prefer-offline"
}| Key | When it runs |
|---|---|
update_after_checkout | On every new worktree, on any device, in your login shell. A string or a list of commands |
initialize | Once, when Keko Cloud prepares a ready-made copy of the project for new machines. A string or a list |
On Keko Cloud, each project gets a ready-made copy after its first clone, with initialize already run, so new machines
start with dependencies in place. A copy is made again in the background when the lockfiles or the setup file change.
Credentials are deleted before a copy is saved. The copy is yours alone; another person's threads never start from it.
Startup commands that run on every start, named commands you can run from the work pane, and variables per project, per person and per thread are Coming soon.
Instructions and skills
A project's AGENTS.md, CLAUDE.md and skills are read when a thread starts. See
Skills and instructions.