Project setup & onboarding

Walk through ADE’s onboarding wizard step by step — detect tools, connect providers, configure GitHub, and get your project ready for agents.

When you open a repository in ADE for the first time, ADE creates a .ade/ directory and launches the project setup wizard. This wizard matches what you see in the app at Settings → General → Open project setup — you can re-run it any time.

If you skip setup, ADE still works. You can configure everything later through Settings. The wizard is a fast path, not a gate.

---

Step 1: Dev tools

ADE checks that your development toolchain is ready.

Check	What ADE looks for	Why it matters
Git	git in PATH, version ≥ 2.20	Lanes use git worktree under the hood
GitHub CLI	gh in PATH and authenticated	PR management, CI status sync
Node.js	node in PATH	Required for ADE CLI and many project workflows

If a tool is missing, ADE shows a direct link to install it. None of these checks block setup — you can proceed and install later.

---

Step 2: AI connections

Connect at least one AI provider so agents can run. ADE supports:

API key providers

Anthropic (Claude), OpenAI (GPT/Codex), OpenRouter. Paste your key and ADE verifies the connection immediately.

CLI-based providers

Claude Code CLI (claude), Codex CLI (codex), Cursor agent. ADE detects installed CLIs and checks their auth status.

ADE runs a health check on each provider. A green indicator means the provider is ready; amber means the CLI is installed but not authenticated; red means the key is invalid or the CLI is missing.

Start with one provider. You can add more any time in Settings → AI. Anthropic (Claude) is recommended for the most complete ADE experience — it works with chat, worker runs, CTO, and automations out of the box.

---

Step 3: Background helpers

Enable optional AI-powered background features:

Feature	What it does	Default
Auto-title sessions	AI generates descriptive names for terminal and chat sessions	On

These features use your configured AI provider and count toward your budget. Disable any you do not want.

---

Step 4: GitHub

Connect your GitHub account for PR management, CI status, and stacked PR workflows.

1. Authenticate with GitHub

   ADE uses a Personal Access Token (PAT) or GitHub CLI auth. If gh is installed and authenticated, ADE detects it automatically.

2. Select repository access

   Confirm which repositories and organizations ADE can access.

3. Set default branch

   ADE detects your default branch (main or master) and uses it as the base for new lanes.

GitHub is optional. ADE works fully without it — you just won’t have PR management, CI sync, or stacked PR features.

---

Step 6: Linear

Connect Linear for bidirectional issue tracking between ADE and your Linear workspace.

Setting	Description
API key	Linear API key (stored in local.secret.yaml)
Sync direction	Bidirectional (default), read-only, or disabled
Default team	Which Linear team receives new issues from ADE

When connected, the CTO agent can read Linear issues, update status, and create new issues. Workers can link to Linear issues for full traceability.

Linear integration is most valuable when paired with the CTO agent. The CTO can ingest new Linear issues and automatically delegate them to worker agents in dedicated lanes.

---

After setup

Once you finish (or skip) the wizard, ADE takes you to the Run tab. From here you can:

Create your first lane

Fork a task into its own isolated worktree.

Start your first agent

Use chat for a quick task or launch a worker run for structured execution.

Set up managed processes

Configure your dev stack so ADE can start everything with one button.

Fine-tune settings

Adjust AI models, budgets, permissions, and notification preferences.

---

Re-running setup

You can re-run the onboarding wizard at any time:

• Settings → General → Open project setup
• Or navigate directly to the onboarding route in the app

Re-running setup does not reset existing configuration. It lets you review and update each step without losing your current settings.