Skip to main content
This guide walks you through running your first coding agent with Emdash. By the end, you’ll have a working agent task running in an isolated git worktree.
Prerequisites: You should have Emdash installed and at least one coding agent set up. If you haven’t done this yet, start with the Installation guide.

​
Step 1: Launch Emdash

Open Emdash from your Applications folder (macOS), Start Menu (Windows), or application launcher (Linux). On first launch, you’ll see the welcome screen with options to:
  • Add a local project
  • Clone a repository
  • Connect to a remote server via SSH

​
Step 2: Add a project

Let’s add a git repository for Emdash to work with.
If you have a git repository on your machine:
  1. Click Add Project in the sidebar (or the welcome screen)
  2. Click Browse and navigate to your repository’s root directory
  3. Select the folder and click Open
  4. Emdash will detect the repository and add it to your project list
Emdash stores project metadata (name, path, settings) in its local SQLite database at ~/Library/Application Support/emdash/emdash.db (macOS) or equivalent on other platforms.

​
Step 3: Verify agent detection

Before creating a task, confirm Emdash detected your installed agents:
  1. Click Settings (gear icon in the sidebar)
  2. Navigate to Agents in the settings panel
  3. You should see checkmarks next to detected agents
If your agent isn’t detected:
  • Verify it’s installed: run <agent-name> --version in your terminal
  • Click Refresh Agents in Settings
  • Restart Emdash
If no agents are detected, you need to install at least one. See Installation → Install coding agents for quick install commands.

​
Step 4: Create your first task

Now let’s create a task and run an agent.
1

Open the project

Click on your project in the sidebar to open it. You’ll see an empty task list.
2

Click New Task

Click the New Task button in the top-right corner of the interface.
3

Configure the task

In the task creation dialog:
  • Task name: Give it a descriptive name (e.g., “Add health check endpoint”)
  • Provider: Select your installed agent (e.g., Claude Code, Codex, Qwen)
  • Initial prompt: Enter what you want the agent to do
Example prompt:
Add a /health endpoint that returns a JSON response with status: "ok" and timestamp.
4

Create the task

Click Create Task. Emdash will:
  1. Claim a worktree from the pool (or create one if needed) at ../worktrees/<task-name-hash>/
  2. Create a new branch emdash/<task-name-hash>
  3. Copy preserved files (.env, .envrc, etc.) from your main repo
  4. Spawn the agent in a PTY (pseudo-terminal) in the worktree
  5. Pass the initial prompt to the agent (via CLI flag or keystroke injection)
The worktree pool eliminates the typical 3-7 second worktree creation delay. Emdash pre-creates worktrees in the background, so task starts are nearly instant.

​
Step 5: Watch the agent work

Once the task is created, you’ll see the agent’s terminal in real-time.

​
Terminal view

The terminal shows exactly what the agent is doing:
  • Reading files
  • Planning changes
  • Editing code
  • Running tests
  • Asking for approval (if not in auto-approve mode)
Emdash uses xterm.js and node-pty to stream the agent’s output with full terminal emulation. You get colors, cursor movement, and interactive prompts just like a native terminal.

​
Interact with the agent

You can type in the terminal to interact with the agent:
  • Approve or reject changes (if the agent asks)
  • Answer follow-up questions
  • Send additional instructions
  • Use keyboard shortcuts (Ctrl+C, etc.)

​
Switch views

Emdash provides multiple views:
  • Terminal: The agent’s full terminal output
  • Files: Browse the worktree’s file system
  • Changes: See a diff of modified files
  • Chat (for supported providers): Conversation history
Switch between views using the tabs at the top of the task panel.

​
Step 6: Review changes

When the agent finishes (or pauses), review what changed:
  1. Click the Changes tab in the task panel
  2. You’ll see a list of modified files with diff summaries
  3. Click any file to see a side-by-side diff in Monaco editor
The diff view shows:
  • Left pane: Original code (before agent changes)
  • Right pane: Modified code (after agent changes)
  • Line numbers: Aligned for easy comparison
  • Syntax highlighting: Based on file type
Changes are isolated in the worktree. Your main branch is untouched until you explicitly push and merge.

​
Step 7: Test the changes (optional)

Want to test the agent’s work before committing? You can:

​
Option 1: Open the worktree in your editor

The worktree is a real directory on your filesystem: 
# List all worktrees
cd /path/to/your/project
ls ../worktrees/

# Open the worktree in your editor
code ../worktrees/<task-name-hash>/
Make any manual changes you need, and the agent will see them in its terminal.

​
Option 2: Run commands in the Emdash terminal

You can type commands directly in the agent’s terminal: 
# Run tests
npm test

# Start dev server
npm run dev

# Check git status
git status

​
Step 8: Commit and push

Once you’re happy with the changes, commit them:
1

Stage and commit

In the terminal or Changes view, commit the agent’s work:
git add .
git commit -m "Add health check endpoint"
Or use the Commit button in the Changes view (if available in your Emdash version).
2

Push the branch

Push the worktree’s branch to your remote:
git push -u origin emdash/<task-name-hash>
3

Create a pull request

If you have GitHub CLI installed and authenticated:
gh pr create --title "Add health check endpoint" --body "Implemented by Emdash agent"
Or click Create PR in Emdash (if you have GitHub integration enabled).
Emdash can create PRs for you directly from the UI using gh CLI. The PR view shows CI checks, reviews, and lets you merge without leaving Emdash.

​
Step 9: Run another task (parallel execution)

Here’s where Emdash shines — you can run multiple agents in parallel:
  1. Click New Task again (your first task can still be running)
  2. Choose a different prompt or agent
  3. Watch both agents work simultaneously
Each task gets its own isolated worktree and branch. No conflicts. No waiting.
You can run as many tasks in parallel as your system can handle. Each worktree shares the same .git directory, so they all see the same commit history without duplicating repository data.

​
Common workflows

Now that you’ve run your first task, explore these common workflows:

​
Attach a Linear or Jira ticket

Instead of typing a prompt manually:
  1. Click Attach Issue in the task creation dialog
  2. Select Linear, Jira, or GitHub Issues
  3. Paste the issue URL or ID
  4. Emdash fetches the issue details and passes them to the agent
You need to configure API credentials in Settings → Integrations first. See Features → Integrations for setup instructions.

​
Use auto-approve mode

Some agents ask for approval before making changes. To run fully autonomous:
  1. Enable Auto-approve when creating the task
  2. Emdash adds the provider’s auto-approve flag (e.g., --dangerously-skip-permissions for Claude)
  3. The agent runs without interruptions
Auto-approve mode lets the agent make unrestricted changes. Use with caution, especially on production codebases.

​
Resume a previous conversation

For providers that support resuming (Claude, Qwen, Continue):
  1. Open an existing task
  2. Click Resume or New Conversation
  3. Emdash spawns the agent with resume flags (e.g., -c -r for Claude)
  4. The agent continues from where it left off

​
Work on a remote server

To run agents on a remote machine:
  1. Go to Settings → SSH Connections
  2. Add your server details (host, user, auth method)
  3. Add a remote project using the SSH connection
  4. Create tasks as usual — they run on the server
See Features → SSH Remote Development for detailed setup.

​
Troubleshooting

If the agent fails to start:
  1. Check the terminal output for error messages
  2. Verify the agent is installed: <cli> --version
  3. Check your PATH includes the agent’s installation directory
  4. Try running the agent manually in your terminal to isolate the issue
  5. Check Settings → Agents for detection status
If worktree creation fails:
  1. Ensure the project is a valid git repository: git status
  2. Check you don’t have uncommitted changes that conflict
  3. Verify there’s disk space for the worktree
  4. Check the parent directory (../worktrees/) is writable
  5. Try running git worktree list in your main repo to see existing worktrees
If the agent complains about missing API keys or env vars:
  1. Check your .env file is in the project root
  2. Verify .env is listed in .emdash.json preserve patterns (default: preserved automatically)
  3. Restart Emdash to pick up new environment variables
  4. For custom patterns, add to .emdash.json:
.emdash.json
{
  "preservePatterns": [".env", ".env.local", ".envrc"]
}
If the terminal is blank or frozen:
  1. Check the terminal tab is selected
  2. Try resizing the Emdash window (triggers PTY resize)
  3. Restart the task
  4. Check Emdash logs for PTY errors (Help → View Logs)

​
Next steps

You’ve successfully run your first agent task with Emdash. Here’s what to explore next:

Core Concepts

Deep dive into git worktrees, agents, and parallel execution.

Supported Providers

Explore all 22+ supported agents with installation commands and feature matrices.

SSH Remote Development

Run agents on remote servers for more power and flexibility.

Configuration

Customize Emdash settings, branch prefixes, and environment variables.

​
Tips for success

Start small: Test agents with small, well-defined tasks before running them on critical code. Review their work carefully until you trust their behavior.
Use descriptive task names: Task names become part of the branch name (emdash/<task-name-hash>). Clear names make it easier to track what each branch does.
Leverage parallel execution: Don’t wait for one agent to finish before starting another. Run multiple tasks simultaneously to maximize productivity.
Preserve critical files: If your agents need specific config files, add them to .emdash.json preserve patterns so they’re copied to every worktree.
Integrate with your workflow: Use Linear/Jira ticket integration to pass structured requirements directly to agents, and GitHub integration to automate PR creation and CI tracking.

Build docs developers (and LLMs) love

Get started for freeTalk to us