Project Settings | Emdash Docs

Configure Project Settings in the UI. Settings are scoped to one Emdash project.

What you can configure

Setting	What it does
GitHub account	The account Emdash uses for GitHub issues, pull requests, comments, checks, and repository creation in this project.
Worktree directory	Where Emdash stores task worktrees for this project.
Default branch	The branch new tasks are created from by default.
Base remote	The remote Emdash fetches from, uses for task base branches and pull request targets.
Push remote	The remote Emdash pushes task branches and commits to. Defaults to the base remote.
Tmux	Keeps terminal and TUI-agent processes running across disconnects. See Tmux Sessions.
Agent git credentials	Use the selected GitHub account, system credentials or no credential helper in agent and terminal sessions.
Environment variables	Variables passed to agents, terminals and lifecycle scripts.
Preserve patterns	Copies matching untracked or gitignored files such as .env into new tasks.
Shell setup	Commands that run before terminals, agent sessions and lifecycle scripts.
Lifecycle scripts	Commands for prepare, setup, run and teardown workflows.

Choose the GitHub account Emdash should use for this project. This controls GitHub API features such as issues, pull requests, comments and checks. Select No GitHub account to disable GitHub API features for the project.

GitHub accounts are managed from Settings -> Integrations -> GitHub. See GitHub Accounts for connection methods, defaults and multiple-account behavior.

Personal overrides apply to your project. Preserve patterns, shell setup and lifecycle scripts can also be shared with teammates through .emdash.json in the working directory. For remote projects, commands and paths apply on the remote machine.

{
  "preservePatterns": [".env", ".env.local"],
  "shellSetup": "source ~/.nvm/nvm.sh && nvm use",
  "scripts": {
    "setup": "docker compose up && pnpm install",
    "run": "pnpm dev",
    "teardown": "docker compose down"
  }
}

Use Share with team to write selected settings to .emdash.json in the chosen working directory. This will clear these settings from your local configuration. Commit the .emdash.json and merge it onto the base branch, so teammates and new tasks get the same project defaults.

Setup and run script logs appear in the terminal drawer. Open it with ⌘J to inspect script output.

Terminal drawer showing setup and run script logs

Precedence

Personal overrides take precedence over shared .emdash.json values for scripts and preserve patterns. Clear an override to inherit the shared value again. Shell setup uses the shared value, then the machine default.

The worktree root uses the project override, then the machine default, then ~/emdash/worktrees. Tmux uses the project override, machine default, then app default. Project Settings shows where effective values come from.

Project environment variables

Add environment variables in Project Settings. Emdash applies them to agents, terminals and lifecycle scripts on the project's machine. These are personal settings; don't put credentials in a committed .emdash.json.

Lifecycle scripts

Use prepare before workspace activation, setup to prepare the environment, run to start the app, and teardown for cleanup. Setup and run follow the project's auto-run settings. Commands run on the project's machine, so required tools must be installed there. Check script output when setup or cleanup fails.

Environment variables available to scripts

Task terminals, agent sessions, shell setup and lifecycle scripts receive these environment variables:

Variable	Purpose
`EMDASH_TASK_ID`	Workspace identifier
`EMDASH_TASK_NAME`	Slug derived from the branch or working directory
`EMDASH_TASK_PATH`	Absolute task path
`EMDASH_ROOT_PATH`	Absolute project root path
`EMDASH_DEFAULT_BRANCH`	Default branch name, for example `main`; omitted when unknown
`EMDASH_PORT`	Base port for a 10-port range

Port-aware run script

{
  "scripts": {
    "run": "PORT=$EMDASH_PORT DB_PORT=$((EMDASH_PORT + 1)) pnpm dev"
  }
}

Docker Compose example

services:
  db:
    ports:
      - '${EMDASH_PORT:-5432}:5432'
  app:
    environment:
      - DATABASE_PORT=${EMDASH_PORT:-5432}