Frontmatter:
title: Environment and Setup
description: Configure Kepler's environment settings — including your repos directory, worktree paths, custom startup commands, and embedded terminals.
taxonomy:
category: kepler
Purpose: Guide for the environment settings that need to be in place before Tasks will work reliably, plus embedded terminal usage.
Sections to include:
Default Repositories Folder (Settings → General)
What it is: the default directory for cloned repositories. Everything else depends on it.
How to set it: Settings → General → Default Repositories Folder. Browse button available.
What happens if it is not set.
Default Worktrees Folder (Settings → General)
What it is: the default directory for new worktrees.
How to set it: Settings → General → Default Worktrees Folder. Browse button available.
Path placeholders: the Worktrees Folder path supports placeholders to create predictable, dynamic paths:
<REPOSITORY_PATH> — main repo folder
<REPOSITORY_NAME> — repo name
<SOURCE_PATH> — where files come from (main repo, or source worktree when forking)
<WORKTREE_PATH> — the new worktree folder
Example: show a sample path using placeholders so worktrees land in the same location for every repo.
Custom commands per repository (Settings → Repositories)
What they are: commands that run when a worktree is created for a specific repo — install deps, run builds, start watchers. The worktree comes up ready, not half-configured.
Where to configure: Settings → Repositories → click the "No commands >" row for a repo.
How to add commands, when they run, and how to verify they succeeded.
Troubleshooting: what happens if a custom command fails at worktree creation.
Setup order
Set the Repositories Folder first, then the Worktrees Folder, then custom commands per repo.
Embedded terminals
What they are: a terminal inside Kepler scoped to any worktree.
When to use: run commands, debug, or inspect files outside the agent without leaving Kepler.
How to open a terminal for a specific worktree.
Scope: the terminal opens in that worktree's directory.
Any limitations relative to a standalone terminal.
Frontmatter:
title: Environment and Setup
description: Configure Kepler's environment settings — including your repos directory, worktree paths, custom startup commands, and embedded terminals.
taxonomy:
category: kepler
Purpose: Guide for the environment settings that need to be in place before Tasks will work reliably, plus embedded terminal usage.
Sections to include:
Default Repositories Folder (Settings → General)
What it is: the default directory for cloned repositories. Everything else depends on it.
How to set it: Settings → General → Default Repositories Folder. Browse button available.
What happens if it is not set.
Default Worktrees Folder (Settings → General)
What it is: the default directory for new worktrees.
How to set it: Settings → General → Default Worktrees Folder. Browse button available.
Path placeholders: the Worktrees Folder path supports placeholders to create predictable, dynamic paths:
<REPOSITORY_PATH> — main repo folder
<REPOSITORY_NAME> — repo name
<SOURCE_PATH> — where files come from (main repo, or source worktree when forking)
<WORKTREE_PATH> — the new worktree folder
Example: show a sample path using placeholders so worktrees land in the same location for every repo.
Custom commands per repository (Settings → Repositories)
What they are: commands that run when a worktree is created for a specific repo — install deps, run builds, start watchers. The worktree comes up ready, not half-configured.
Where to configure: Settings → Repositories → click the "No commands >" row for a repo.
How to add commands, when they run, and how to verify they succeeded.
Troubleshooting: what happens if a custom command fails at worktree creation.
Setup order
Set the Repositories Folder first, then the Worktrees Folder, then custom commands per repo.
Embedded terminals
What they are: a terminal inside Kepler scoped to any worktree.
When to use: run commands, debug, or inspect files outside the agent without leaving Kepler.
How to open a terminal for a specific worktree.
Scope: the terminal opens in that worktree's directory.
Any limitations relative to a standalone terminal.