Skip to Content
Keko

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:

  1. Dependencies: for npm and yarn projects, node_modules folders 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.
  2. 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-offline or npm 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"
}
KeyWhen it runs
update_after_checkoutOn every new worktree, on any device, in your login shell. A string or a list of commands
initializeOnce, 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.

On this page