# Project Settings

Configure how Emdash creates and runs tasks for a project

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

<img
  src="/media/docs/projectconfig.png"
  alt="Project Settings in Emdash"
  style={{
    width: '75%',
    margin: '20px auto',
    display: 'block',
    borderRadius: '8px',
    boxShadow: '0 4px 6px rgba(0, 0, 0, 0.1)',
  }}
/>

## 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](/docs/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. |

## GitHub account

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](/docs/github-accounts) for connection methods, defaults and multiple-account behavior.

## Share settings with your team

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.

```json
{
  "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.

<img
  src="/media/docs/terminal-drawer.png"
  alt="Terminal drawer showing setup and run script logs"
  style={{
    width: '75%',
    margin: '20px auto',
    display: 'block',
    borderRadius: '8px',
    boxShadow: '0 4px 6px rgba(0, 0, 0, 0.1)',
  }}
/>

## 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

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

### Docker Compose example

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