Linear and Jira integration

Emdash integrates with Linear and Jira to help you link development tasks to issues, automatically populate context, and maintain traceability from issue to pull request.

Integration overview

When you link a task to a Linear or Jira issue, Emdash:

Fetches issue details: Title, description, status, assignee, labels
Seeds the agent context: Injects issue details as the first message
Tracks the link: Stores the association in the database
Generates branch names: Uses issue key/identifier in branch name
Adds PR footer: Links the PR back to the original issue

You can link a task to Linear, Jira, or GitHub issues — but only one issue per task.

Linear setup

Generate a Linear API key

Open Linear
Go to Settings → Security & access → Personal API keys
Click Create key
Give it a name (e.g., “Emdash”)
Copy the generated API key

Linear API keys grant full access to your workspace. Keep them secure.

Add the API key to Emdash

In Emdash, create a new task (or go to Settings)
Click Advanced settings
Under Issue tracking, click Linear
Click Setup
Paste your API key
Click Connect

Emdash will verify the connection and display a success message.

Link an issue to a task

Create a new task
Click Advanced settings
Under Linear, click the issue selector
Search for an issue by ID, title, or description
Select the issue
Click Create task

The issue details will be injected as the first message in the conversation.

Linear API implementation

Emdash uses the Linear GraphQL API to fetch and search issues.

src/main/ipc/linearIpc.ts

export function registerLinearIpc() {
  ipcMain.handle('linear:saveToken', async (_event, token: string) => {
    return linearService.saveToken(token);
  });

  ipcMain.handle('linear:checkConnection', async () => {
    return linearService.checkConnection();
  });

  ipcMain.handle('linear:searchIssues', async (_event, searchTerm: string, limit?: number) => {
    const issues = await linearService.searchIssues(searchTerm, limit ?? 20);
    return { success: true, issues };
  });
}

Linear issue context injection

When a task is linked to a Linear issue:

src/renderer/lib/taskCreationService.ts

const lines = [`Linked Linear issue: ${issue.identifier} — ${issue.title}`];

if (issue.description) {
  lines.push('', '## Description', issue.description);
}

if (issue.state?.name) {
  lines.push('', `**Status**: ${issue.state.name}`);
}

if (issue.assignee?.name) {
  lines.push(`**Assignee**: ${issue.assignee.name}`);
}

if (issue.labels && issue.labels.length > 0) {
  lines.push(`**Labels**: ${issue.labels.join(', ')}`);
}

const content = lines.join('\n');

This context is injected as the first message, giving the agent full visibility into the issue.

Jira setup

Create a Jira API token

Go to https://id.atlassian.com/manage-profile/security/api-tokens
Click Create API token
Give it a label (e.g., “Emdash”)
Click Create
Copy the token (it won’t be shown again)

Find your Jira site URL

Your Jira site URL is typically:

https://your-company.atlassian.net

You can find it in the browser URL bar when using Jira.

Add Jira credentials to Emdash

In Emdash, create a new task
Click Advanced settings
Under Issue tracking, click Jira
Click Setup
Enter:
- Site URL: Your Jira base URL (e.g., https://company.atlassian.net)
- Email: Your Atlassian account email
- API Token: The token you created
Click Connect

Emdash will verify the connection.

Link a Jira issue to a task

Create a new task
Click Advanced settings
Under Jira, click the issue selector
Search by issue key (e.g., PROJ-123) or summary text
Select the issue
Click Create task

The issue details will be injected into the agent context.

Jira API implementation

Emdash uses the Jira REST API v3 to fetch and search issues.

src/main/ipc/jiraIpc.ts

export function registerJiraIpc() {
  ipcMain.handle(
    'jira:saveCredentials',
    async (_e, args: { siteUrl: string; email: string; token: string }) => {
      const siteUrl = String(args?.siteUrl || '').trim();
      const email = String(args?.email || '').trim();
      const token = String(args?.token || '').trim();
      if (!siteUrl || !email || !token) {
        return { success: false, error: 'Site URL, email, and API token are required.' };
      }
      return jira.saveCredentials(siteUrl, email, token);
    }
  );

  ipcMain.handle('jira:searchIssues', async (_e, searchTerm: string, limit?: number) => {
    const issues = await jira.smartSearchIssues(searchTerm, limit ?? 20);
    return { success: true, issues };
  });
}

Jira issue context injection

Similar to Linear, Jira issue details are injected as context:

src/renderer/lib/taskCreationService.ts

const line = `Linked Jira issue: ${issue.key || ''}${issue.summary ? ` — ${issue.summary}` : ''}`;

if (issue.description) {
  lines.push('', '## Description', issue.description);
}

if (issue.status?.name) {
  lines.push('', `**Status**: ${issue.status.name}`);
}

if (issue.assignee?.displayName) {
  lines.push(`**Assignee**: ${issue.assignee.displayName}`);
}

Task creation workflow with issues

Here’s the complete flow when creating a task with a linked issue:

User selects an issue

In the task creation modal:

User clicks Advanced settings
Selects Linear, Jira, or GitHub
Searches for an issue
Selects one from the results

Emdash fetches issue details

The integration service fetches:

Title/summary
Description
Status/state
Assignee
Labels/tags
URL

Task name is auto-generated

If the user hasn’t entered a custom task name, Emdash generates one from the issue:

src/renderer/lib/branchNameGenerator.ts

export function generateTaskNameFromContext(options: {
  linearIssue?: LinearIssueSummary | null;
  jiraIssue?: JiraIssueSummary | null;
  githubIssue?: GitHubIssueSummary | null;
}): string | null {
  const { linearIssue, jiraIssue, githubIssue } = options;

  if (linearIssue?.title) {
    return `${linearIssue.identifier}: ${linearIssue.title}`;
  }

  if (jiraIssue?.summary) {
    return `${jiraIssue.key}: ${jiraIssue.summary}`;
  }

  if (githubIssue?.title) {
    return `#${githubIssue.number}: ${githubIssue.title}`;
  }

  return null;
}

Branch name includes issue key

The worktree branch is created with the issue identifier:

emdash/lin-123-fix-authentication-bug-a3f
emdash/proj-456-add-export-feature-b7c

Issue context is seeded

Before the user’s initial prompt, the issue details are sent as a system message:

Linked Linear issue: LIN-123 — Fix authentication bug

## Description
Users are unable to log in after the recent update to the auth service.

**Status**: In Progress
**Assignee**: Alice Smith
**Labels**: bug, auth, priority-high

This gives the agent full context before it starts working.

User prompt follows

After the issue context, the user’s initial prompt is delivered:

Fix the login issue by checking the session token validation logic

The agent now has both the issue context and the user’s instructions.

Pull request linking

When you generate a PR from a task with a linked issue, Emdash automatically adds the issue to the PR description footer.

---
Linked issues:
- Linear: https://linear.app/company/issue/LIN-123

For Jira:

---
Linked issues:
- Jira: https://company.atlassian.net/browse/PROJ-456

This creates a traceable link from issue → task → PR → merge.

Issue badges in the UI

Linked issues are displayed as badges in the task list:

src/renderer/components/TaskContextBadges.tsx

{linearIssue && (
  <button
    onClick={() => window.open(linearIssue.url, '_blank')}
    className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-xs"
    aria-label={`Linear issue ${linearIssue.identifier}: ${linearIssue.title}`}
  >
    <img src={linearLogo} alt="Linear" className="h-3.5 w-3.5" />
    <span>{linearIssue.identifier}</span>
  </button>
)}

Clicking the badge opens the issue in your browser.

Credential storage

Linear

Linear API tokens are stored in the Emdash database (encrypted at rest by the OS). Location:

macOS: ~/Library/Application Support/emdash/emdash.db
Linux: ~/.config/emdash/emdash.db
Windows: %APPDATA%\emdash\emdash.db

Jira

Jira credentials (site URL, email, token) are also stored in the database.

The database file contains sensitive credentials. Ensure it has proper file permissions and is excluded from backups or sync tools if needed.

Troubleshooting

Linear connection fails

Symptoms: “Invalid API key” or connection timeoutSolutions:

Verify the API key is correct (re-copy from Linear)
Check you have internet access
Ensure the API key hasn’t been revoked
Try generating a new API key in Linear

Jira connection fails

Symptoms: “Unauthorized” or “Invalid credentials”Solutions:

Verify site URL is correct (e.g., https://company.atlassian.net)
Use your Atlassian account email (not username)
Ensure the API token is valid (regenerate if needed)
Check you have access to the Jira site
Verify your account isn’t locked or suspended

Issue search returns no results

Symptoms: Search doesn’t find known issuesSolutions:

Linear: Search by issue ID (e.g., LIN-123), title keywords, or description
Jira: Try searching by exact issue key first (e.g., PROJ-456)
Check the issue is in a project you have access to
Verify the issue isn’t archived or deleted

Issue context not injected

Symptoms: Agent doesn’t see issue detailsSolutions:

Check the first message in the conversation — it should contain issue details
If missing, the issue metadata may not have saved
Try creating a new task with the issue linked
Check the database for the task’s metadata field

Wrong issue linked to task

Symptoms: Task shows the wrong issue badgeSolutions:

Edit the task metadata to remove the issue link
Recreate the task with the correct issue
Currently, there’s no UI to change the linked issue after creation

PR footer missing issue link

Symptoms: Generated PR doesn’t include issue URLSolutions:

Verify the task has a linked issue (check for badge in task list)
Re-generate the PR
Check the PR description was generated by Emdash (not manually created)

Data types and schema

Linear issue summary

src/renderer/types/linear.ts

export interface LinearIssueSummary {
  identifier: string;    // e.g., "LIN-123"
  title: string;
  description?: string | null;
  url?: string | null;
  state?: LinearStateRef | null;
  team?: LinearTeamRef | null;
  project?: LinearProjectRef | null;
  assignee?: LinearUserRef | null;
}

Jira issue summary

src/renderer/types/jira.ts

export interface JiraIssueSummary {
  key: string;           // e.g., "PROJ-456"
  summary: string;
  description?: string | null;
  url?: string | null;
  status?: JiraStatusRef | null;
  project?: JiraProjectRef | null;
  assignee?: JiraUserRef | null;
}

Database storage

Linked issues are stored in the tasks table’s metadata field:

metadata: JSON.stringify({
  isLinearContext: true,
  linearIssue: {
    identifier: 'LIN-123',
    title: 'Fix auth bug',
    url: 'https://linear.app/company/issue/LIN-123',
    // ...
  }
})

And in the conversations table for the main conversation.

Advanced: Custom issue workflows

You can extend the issue integration by:

Adding new providers: Implement a service for GitHub Issues, Asana, ClickUp, etc.
Custom context formatting: Modify how issue details are injected
Automatic status updates: Use webhooks to update issue status when PRs merge
Bidirectional sync: Update Emdash tasks when issues change

See src/main/services/LinearService.ts and JiraService.ts for implementation examples.

Next steps

Adding providers — Add CLI agents to work on linked issues
SSH connection setup — Work on issues from remote servers
Troubleshooting — Debug common integration issues

Get Started

Core Concepts

Features

Configuration

Guides

Linear and Jira integration

Integration overview

Linear setup

Linear API implementation

Linear issue context injection

Jira setup

Jira API implementation

Jira issue context injection

Task creation workflow with issues

Pull request linking

PR footer format

Issue badges in the UI

Credential storage

Linear

Jira

Troubleshooting

Data types and schema

Linear issue summary

Jira issue summary

Database storage

Advanced: Custom issue workflows

Next steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Configuration

Guides

​Integration overview

​Linear setup

​Linear API implementation

​Linear issue context injection

​Jira setup

​Jira API implementation

​Jira issue context injection

​Task creation workflow with issues

​Pull request linking

​PR footer format

​Issue badges in the UI

​Credential storage

​Linear

​Jira

​Troubleshooting

​Data types and schema

​Linear issue summary

​Jira issue summary

​Database storage

​Advanced: Custom issue workflows

​Next steps

Build docs developers (and LLMs) love

Integration overview

Linear setup

Linear API implementation

Linear issue context injection

Jira setup

Jira API implementation

Jira issue context injection

Task creation workflow with issues

Pull request linking

PR footer format

Issue badges in the UI

Credential storage

Linear

Jira

Troubleshooting

Data types and schema

Linear issue summary

Jira issue summary

Database storage

Advanced: Custom issue workflows

Next steps