Skip to main content
**Screenshot: The Project Home (Run tab) view — showing a “Backend” process group with postgres (green, running), rails server (green, running), and sidekiq (green, running), a “Frontend” group with a Next.js dev server, the Stack button in the header (green “Stack Running” state), CPU/memory usage indicators next to each process, and a test suite panel on the right side.

​
Overview

Project Home is ADE’s global process management center. It is the first place you look when you sit down to start working on your project — and the place you return to when something is not running correctly. From Project Home you can:
  • Start your entire development stack with a single button
  • Define, start, stop, and monitor managed processes with CPU and memory visibility
  • Run and watch test suites from a built-in test runner panel
  • Edit environment variables with a visual .env editor
  • Monitor CI/CD status synced from GitHub Actions
  • Launch AI coding tool CLIs into your primary lane
Project Home is global to the project — it is not scoped to a single lane. Managed processes belong to the project (though they can be configured to run in a specific lane’s environment). Use the Lane Selector in the header to filter the view to a single lane’s processes and environment.

​
Setting Up Managed Processes

A Managed Process is any command ADE starts, monitors, and can restart on your behalf. Common examples include dev servers, database processes, background workers, and Docker Compose stacks.

​
Adding a Process

1

Open Project Home

Click the Project Home icon in the left sidebar (house icon), or press Cmd+0.
2

Click 'Add Process'

Click the + Add Process button in the top-right of the process list. A configuration drawer slides in from the right.
3

Configure the process

Fill in the process configuration:
FieldDescriptionExample
NameDisplay name for this processRails Server
GroupProcess group (optional)Backend
CommandThe command to runbundle exec rails server -p $PORT
Working DirDirectory to run the command in./apps/api (relative to project root)
LaneWhich lane to run in (default: Primary)primary
Auto-restartRestart automatically on exitOn/Off
Restart limitMax restart attempts before alerting5
Startup orderPriority for Stack Button ordering2
Health checkOptional URL or command to verify startuphttp://localhost:$PORT/health
4

Save and start

Click Save. The process appears in the list in a stopped state. Click the Start button (▶) to launch it, or use the Stack Button to start all processes.

​
AI-Suggested Run Configurations

When you open a project for the first time (or click Detect Processes in the toolbar), ADE analyzes your repository to suggest process configurations automatically:
  • Reads package.json scripts and detects common frameworks (Next.js, Vite, Create React App)
  • Detects Procfile, docker-compose.yml, Makefile targets, and common Gemfiles
  • Reads .env.example to infer environment variable requirements
  • Suggests a complete process list with startup ordering pre-configured
Click Adopt All to add all suggestions at once, or Review to cherry-pick which ones to add. This takes about 5 seconds for most projects.

​
The Stack Button

The Stack Button is the large button at the top-right of Project Home. It starts or stops all managed processes in the correct dependency order based on their configured startup order.

Stack Start

Processes launch in ascending startup order (order 1 first, then 2, etc.). ADE waits for each process’s health check to pass before launching the next group. If a health check fails, the stack halts and shows which process blocked startup.

Stack Stop

Processes are stopped in reverse startup order (frontend first, then API, then database). ADE sends SIGTERM, waits for graceful shutdown, then SIGKILL if a process does not exit within the configured timeout (default: 10 seconds).
The Stack Button shows one of three states:
  • Start Stack (gray): No processes are running
  • Stack Starting… (yellow, animated): Stack is in the process of launching
  • Stack Running (green): All processes are running and healthy
  • Stack Error (red): One or more processes have crashed or failed health checks
Press Cmd+Shift+R to toggle the Stack from the keyboard.
Configure startup ordering carefully — start database and message broker processes at order 1, backend APIs at order 2, and frontend servers at order 3. This ensures each process has its dependencies available when it starts.

​
Process Status and Monitoring

Each managed process in the list displays live status information:
IndicatorDescription
Status dotGreen (running), yellow (starting), red (error/crashed), gray (stopped)
PIDThe operating system process ID
CPU %Current CPU usage (sampled every 2 seconds)
MemoryCurrent resident memory usage in MB
Start timeWhen the process was last started
Restart countHow many times this process has been auto-restarted
Last lineThe last line of stdout/stderr output (expandable)

​
Process Groups

Processes can be organized into groups (e.g., “Backend”, “Frontend”, “Database”). Group headers in the list show aggregate status and provide group-level controls:
  • Start Group: Start all processes in this group
  • Stop Group: Stop all processes in this group
  • Restart Group: Restart all processes in this group
Drag process rows to reorder them within or across groups.

​
Viewing Process Logs

Click any process row to expand its log panel inline, showing a live-streaming view of the process’s stdout and stderr. The log panel is:
  • Color-coded: ADE detects log levels (INFO, WARN, ERROR) and colors accordingly
  • Searchable: Press Cmd+F inside the log panel to search the log buffer
  • Buffered: The last 10,000 lines are kept in memory; older lines are written to disk and still searchable
**Screenshot: A single expanded process log panel — showing the Rails server log with color-coded entries (green INFO lines, yellow WARN lines, red ERROR line), the process metadata row above it (PID, CPU 2.1%, Memory 312 MB, Running for 4m 32s), and a search bar overlaid on the log.

​
Port Conflict Detection

If two managed processes are configured to bind to the same port, ADE detects this at startup (before either process launches) and shows a Port Conflict warning:
Port conflict: Rails Server and API Gateway both use port 3000 Change one process’s port assignment before starting the stack.
ADE also monitors for port conflicts that emerge at runtime (e.g., an external process has already bound to a port). If a managed process fails to bind to its configured port, the error is surfaced in the process’s log panel with a “Port in use” diagnostic and suggestions for resolution.

​
Test Suites

Project Home includes a built-in test runner panel for running and monitoring test suites.

​
Configuring a Test Suite

Click + Add Test Suite in the Test Suites panel. Configure:
FieldDescriptionExample
NameSuite display nameUnit Tests
Run commandCommand to run tests oncepnpm test --reporter=json
Watch commandCommand to run in watch modepnpm test --watch
CI commandCommand used in CI (for comparison)pnpm test --ci --coverage
LaneWhich lane to run tests inprimary
Parse resultsReporter format for structured resultsjest-json / tap / junit-xml

​
Running Tests

1

Select a suite

Click the suite name in the Test Suites panel to select it. The right side of the panel shows the suite configuration and last run results.
2

Run once or enter watch mode

Click Run (▶) to execute the test suite once, or Watch (👁) to start it in watch mode. Press Cmd+Shift+T to run the focused suite from the keyboard.
3

View results

If a structured reporter is configured, results appear as a pass/fail/skip breakdown with individual test names, durations, and failure details expandable inline. If no structured reporter is configured, raw stdout is shown.
The test suite panel shows:
  • Pass / Fail / Skip counts for the last run
  • Duration of the last run
  • Coverage summary (if the test command outputs coverage)
  • Trend: A small sparkline showing pass rates over the last 10 runs
ADE can automatically run your test suite when an agent finishes a task in a lane. Enable this in the lane’s configuration under Settings → Agents → Post-task test run. This is particularly useful in Mission workflows where you want automatic validation after each execution phase.

​
Config Editor (Environment Variables)

The Config Editor is a visual editor for your project’s environment variables, built directly into Project Home.

​
Opening the Config Editor

Click the Config tab at the top of Project Home (or press Cmd+E from within Project Home).

​
Editing Variables

The Config Editor shows all variables from your project’s .env file (and any .env.local, .env.development, etc. files you have configured ADE to manage). For each variable:
  • Key: The variable name (always visible)
  • Value: The current value — secret masking automatically hides values containing common secret patterns (keys, tokens, passwords) behind a •••••• mask. Click the eye icon to reveal.
  • Source: Which .env file this variable comes from
  • Override: Lane-specific overrides appear in a separate column, showing that the lane’s value differs from the project default

​
Adding and Removing Variables

  • Click + Add Variable to insert a new key-value pair. ADE writes the change to the appropriate .env file immediately.
  • Click the trash icon next to any variable to remove it (with confirmation).
  • Drag variable rows to reorder them (order is preserved in the .env file for readability).
The Config Editor writes directly to your .env files on disk. If you have .env files checked into version control, these edits will appear as working-tree modifications in the Files view. ADE does not automatically commit .env changes — you decide when (and whether) to commit them.

​
CI/CD Workflow Sync

ADE reads your GitHub Actions workflows and displays CI run status directly in Project Home.

​
Enabling CI Sync

Connect your GitHub account in Settings → Integrations → GitHub. Once connected, ADE polls GitHub’s API for the most recent workflow runs on your project’s branches.

​
What You See

The CI/CD panel in Project Home shows:
  • The last 5 workflow runs, with status icons (success, failure, in-progress, cancelled)
  • Which branch each run was triggered on
  • Duration and trigger event (push, pull_request, schedule)
  • A link to the full run on GitHub
If a run is failing, ADE highlights it in red and surfaces it at the top of Project Home with a “CI Failing” badge. Clicking the badge opens the run details — including which step failed and a snippet of the failure log — without leaving ADE.
CI status is polled every 60 seconds while Project Home is open, and whenever a new commit is pushed from any lane. You can force a refresh with Cmd+R in the CI/CD panel.

​
AI Tool Launchers

Project Home provides quick launchers for AI coding CLI tools. These launch the selected tool as a managed session in your primary lane.

Claude Code

Launches claude CLI in an interactive session in the primary lane. ADE injects the project’s context pack as an initial system prompt if configured.

OpenAI Codex

Launches codex in an interactive session. Requires codex to be installed globally (npm i -g @openai/codex).

Cursor

Opens the current project in Cursor (if installed). Cursor launches as a separate application window, but the session is linked back to ADE’s primary lane for tracking.

Custom CLI

Configure a custom CLI tool in Settings → Project Home → Custom CLI Launchers. Any command-line tool can be registered with a name, launch command, and icon.
AI tool launchers are tracked as Managed Sessions in the lane. Their output is captured in the session transcript, so you can review what the external tool did even after it exits.

​
Lane Selector

The Lane Selector dropdown in the Project Home header scopes the entire view to a specific lane:
  • All Lanes (default): Shows all managed processes, test suites, and environment configs for the project
  • Specific Lane: Filters to only show processes running in that lane, the lane’s environment variable overlay, and test runs attributed to that lane
Use the lane selector when you have per-lane process configurations (e.g., a staging lane running a different API server than the development lane) and need to see only that lane’s state.

​
Keyboard Shortcuts

ShortcutAction
Cmd+0Open Project Home
Cmd+Shift+RStart/stop the full Stack
Cmd+RRestart the focused process
Cmd+. or Cmd+CStop the focused process
Cmd+Shift+TRun the focused test suite
Cmd+EOpen the Config Editor tab
Cmd+FSearch in the focused log panel

​
Process Troubleshooting

Check the process log panel — ADE captures all stdout/stderr even from very short-lived processes. Common causes:
  • Missing environment variable (check Config Editor)
  • Port already in use (check Port Conflict detection)
  • Missing dependency (check that you have run npm install or equivalent)
  • Wrong working directory (verify the Working Dir field in process config)
If the Stack halts because a health check is failing, the process log usually contains the clue. Common causes:
  • The process is still starting up — try increasing the health check timeout in process config (Settings → Process → Health Check Timeout)
  • The health check URL is wrong — verify the URL and port match the process’s actual bind address
  • The process requires a dependency (e.g., database) that has not started yet — check startup ordering
If Auto-restart is enabled and the process exits repeatedly, ADE will eventually hit the restart limit and stop trying. The process shows a “Restart limit reached” badge in red.Click Reset Restart Count to clear the counter and try again. If the process is still crashing, disable auto-restart temporarily and investigate the log manually.
The Stack Button is only active if at least one process has a Startup order value configured and is in a stopped state. If all processes are already running, the button shows “Stop Stack”. If no processes have a startup order, ADE cannot determine a safe ordering and the Stack Button remains disabled — assign startup orders in each process’s configuration.
**Screenshot: The Project Home Config Editor tab — showing a table of environment variables with key names in the left column, masked values (••••••) in the middle column for sensitive entries like API keys, eye-toggle icons on the right of each row, a ”+ Add Variable” button at the bottom, and a lane-specific override column showing one override in the active lane highlighted in blue.

Terminals

Understand how Managed Sessions in Project Home relate to the terminal session system.

Lanes

Lane configuration, environment isolation, and port allocation.

Automations

Trigger managed process restarts and test suite runs automatically from git events.

Configuration

Full ade.yaml reference including process and environment configuration schemas.