> ## Documentation Index
> Fetch the complete documentation index at: https://kasava.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Connect Linear to sync issues and manage your roadmap from Kasava

Linear is a modern issue tracking platform popular with engineering teams. Kasava's Linear integration enables AI-powered issue management and brings your Linear issues into your product roadmap.

## Capabilities

| Feature             | Description                                                         |
| ------------------- | ------------------------------------------------------------------- |
| AI Issue Management | Create and update Linear issues using natural language in chat      |
| Plans Integration   | Embed live Linear issues directly in your planning documents        |
| Roadmap Integration | View Linear items alongside other platforms in your product roadmap |
| Bi-Directional Sync | Read issues from Linear, write updates back via AI chat             |
| Search & Filter     | Search and filter Linear issues across your workspace               |
| Team Assignment     | Assign issues to team members from Kasava                           |
| Status Tracking     | Track issue status, priority, and progress                          |

## Connecting Linear

<Steps>
  <Step title="Navigate to Settings">
    Go to **Settings** in the sidebar, then select **Integrations**
  </Step>

  <Step title="Find Linear">
    In the Task Management section, locate the Linear integration card
  </Step>

  <Step title="Start Connection">
    Click the Linear card to open the connection page, then click **Connect Linear Account**
  </Step>

  <Step title="Authorize Access">
    You'll be redirected to Linear to authorize Kasava. Review the permissions and click **Authorize**
  </Step>

  <Step title="Complete Setup">
    After authorization, you'll be redirected back to Kasava. The integration status will show as connected
  </Step>
</Steps>

<Note>
  Kasava uses secure OAuth authentication. Your Linear credentials are never stored—only an access token for API calls.
</Note>

## Using Linear in AI Chat

Once connected, you can manage Linear issues using natural language in Kasava's AI chat:

### Example Commands

* "Create a new Linear issue for fixing the login bug"
* "Show me all high priority Linear issues"
* "Assign the authentication issue to Sarah"
* "Update the payment feature status to in progress"
* "Find Linear issues related to the API"

The AI assistant will interact with your Linear workspace to create, update, and search issues based on your requests.

### Personalized with AI Learning

When Kasava analyzes Linear issues, it applies your [AI Learning patterns](/docs/advanced/ai-learning) to provide personalized results:

* **Issue categorization** follows your preferences
* **Priority recommendations** match your team's thresholds
* **Terminology** uses your preferred terms

If you've corrected how Kasava categorizes certain types of issues, those corrections are remembered and applied to future Linear issue analysis.

## Embedding Linear Issues in Plans

You can embed live Linear issues directly into your Plans to keep planning documents connected to implementation work.

### Inserting a Linear Issue

1. Open a Plan in the editor
2. Type `/linear` or click the **+** button and select **Linear Issue**
3. Search for the issue by title, identifier, or description
4. Click to insert the issue block

### Linear Issue Block

The embedded issue displays live data from Linear:

* **Status icon** - Shows current workflow state (Todo, In Progress, Done)
* **Identifier** - Clickable link (e.g., ENG-123) that opens in Linear
* **Title** - The issue title
* **Assignee** - Team member assigned to the issue
* **Priority** - Urgent, High, Medium, or Low badge
* **Labels** - Color-coded labels from Linear

### Keeping Plans in Sync

Embedded Linear issues stay connected to your Linear workspace:

* Issue data refreshes when you view the Plan
* Click the issue identifier to open it directly in Linear
* Changes made in Linear (status, assignee, priority) are reflected in the Plan

<Tip>
  Use embedded Linear issues to connect your PRDs and planning documents to the actual implementation tickets your team is working on.
</Tip>

## Bi-Directional Sync

Kasava supports syncing with Linear to keep your work aligned across platforms.

### From Linear to Kasava (Read)

| What Syncs       | How It Works                                                       |
| ---------------- | ------------------------------------------------------------------ |
| Issues           | Appear in Roadmap view and can be embedded in Plans                |
| Status           | Mapped to Kasava's status system (Planned, In Progress, Completed) |
| Priority         | Mapped to Kasava's priority levels                                 |
| Assignees        | Displayed with names and avatars                                   |
| Labels           | Shown with original colors                                         |
| Teams & Projects | Used for filtering and organization                                |

### From Kasava to Linear (Write)

The AI chat can write back to Linear:

| Action          | What Happens in Linear                               |
| --------------- | ---------------------------------------------------- |
| Create issue    | New issue created in specified team/project          |
| Update issue    | Issue fields modified (title, description, priority) |
| Change assignee | Assignee updated on the issue                        |
| Add comment     | Comment added to the issue thread                    |

### Roadmap Status Updates

When you drag items in the Roadmap Board view:

* Status changes are saved locally in Kasava
* For now, update the issue status directly in Linear for immediate sync

### Best Practices for Sync

1. **Use AI chat for updates** - The most reliable way to push changes back to Linear
2. **Refresh regularly** - Embedded issues and roadmap items fetch latest data on view
3. **Link related items** - Connect Linear issues to roadmap items for better tracking
4. **Keep one source of truth** - For critical status updates, make changes in Linear directly

## Viewing Linear in Roadmap

Linear issues appear in your product's **Roadmap** tab, alongside items from other connected platforms.

### Accessing the Roadmap

1. Navigate to your **Product**
2. Click the **Roadmap** tab
3. Linear items will display with a Linear badge

### Roadmap Views

Switch between three views using the toggle in the header:

| View         | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| **List**     | Sortable list showing all roadmap items with details              |
| **Timeline** | Gantt-style timeline view with date ranges                        |
| **Board**    | Kanban board with columns for Planned, In Progress, and Completed |

### Filtering by Platform

To view only Linear items:

1. Click the **Filters** button
2. Under **Platform**, check **Linear**
3. The view will update to show only Linear-sourced items

You can also filter by status: In Progress, At Risk, Delayed, Planned, or Completed.

### Status Indicators

Linear items display status badges:

| Status      | Indicator       |
| ----------- | --------------- |
| Planned     | Gray badge      |
| In Progress | Blue badge      |
| On Track    | Green checkmark |
| At Risk     | Yellow warning  |
| Delayed     | Red indicator   |
| Completed   | Green badge     |

### Updating Status

Drag items between columns in **Board** view to update their status:

1. Switch to **Board** view
2. Drag an item from one column to another
3. The status updates locally

<Note>
  Status changes made in Kasava are saved locally. For immediate sync, update the issue status directly in Linear.
</Note>

## Field Mapping

| Linear Field | Kasava Display   |
| ------------ | ---------------- |
| Issue title  | Item name        |
| Description  | Item description |
| State        | Status column    |
| Priority     | Priority badge   |
| Labels       | Label chips      |
| Due date     | Target date      |

## Priority Mapping

| Linear Priority | Kasava Priority |
| --------------- | --------------- |
| Urgent          | Critical        |
| High            | High            |
| Medium          | Medium          |
| Low             | Low             |
| No priority     | None            |

## Creating Roadmap Items

You can create new roadmap items directly in Kasava:

1. In the Roadmap tab, click **Add Item**

2. Choose the item type:
   * **Epic** - Large initiative with multiple features
   * **Feature** - Specific functionality to build
   * **Milestone** - Point in time when work must complete
   * **Release** - Version shipping to users
   * **Sprint** - Time-boxed execution period

3. Fill in the details and click **Create**

<Note>
  Items created in Kasava are native Kasava items. To create issues directly in Linear, use the AI chat or the Linear app.
</Note>

## @kasava Commands in Issues

Use `@kasava` mentions in Linear issue comments to trigger AI-powered actions directly from your workflow.

### How It Works

1. Add a comment on any Linear issue with `@kasava` followed by a command
2. Kasava detects the mention via webhooks
3. The AI processes your request using the issue context
4. Results are posted as a reply comment on the issue

### Available Commands

| Command               | Description                           |
| --------------------- | ------------------------------------- |
| `@kasava summarize`   | Summarize the issue discussion        |
| `@kasava document`    | Generate documentation from the issue |
| `@kasava plan`        | Create an implementation plan         |
| `@kasava design-doc`  | Generate a design document            |
| `@kasava prototype`   | Create a prototype spec               |
| `@kasava diagnose`    | Analyze the problem described         |
| `@kasava postmortem`  | Generate a postmortem analysis        |
| `@kasava insights`    | Extract key insights                  |
| `@kasava changelog`   | Generate changelog entries            |
| `@kasava report`      | Create a status report                |
| `@kasava review-prep` | Prepare for a review meeting          |

### Command Arguments

Filter the analysis with natural language:

```
@kasava summarize last 5 comments
@kasava summarize since last week
@kasava summarize by @alice
```

### Custom Commands

Your organization can create custom action types in **Settings > Templates > Action Types** that work in Linear just like built-in commands.

### Authorization

By default, Linear workspace members in your Kasava organization can use commands. Enable external collaborators in **Settings > Integrations > Permissions** if needed.

<Tip>
  Use `@kasava summarize` on lengthy Linear issues to quickly generate a summary of the discussion for stakeholders.
</Tip>

## Disconnecting Linear

To disconnect your Linear workspace:

1. Go to **Settings** → **Integrations**
2. Click on the **Linear** integration
3. Click **Disconnect Linear**
4. Confirm the disconnection

Your existing roadmap data will remain in Kasava, but new syncs will stop.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Linear issues not appearing in roadmap">
    Verify that Linear is connected by checking Settings → Integrations. The connection status should show a green checkmark. If disconnected, reconnect using the OAuth flow.
  </Accordion>

  <Accordion title="Connection failed during OAuth">
    Ensure you have permission to authorize applications in your Linear workspace. If you're not a workspace admin, contact your Linear administrator.
  </Accordion>

  <Accordion title="Chat commands not working">
    Make sure your Linear connection is active. Try disconnecting and reconnecting the integration. The AI assistant requires an active connection to interact with Linear.
  </Accordion>

  <Accordion title="Items showing wrong status">
    Status mapping between Linear and Kasava may differ. Linear's workflow states are mapped to Kasava's status system (Planned, In Progress, Completed). Check the item details for the original Linear state.
  </Accordion>
</AccordionGroup>

## Permissions

Kasava requests the following Linear permissions during OAuth:

| Permission   | Purpose                                 |
| ------------ | --------------------------------------- |
| Read access  | View issues, projects, teams, and users |
| Write access | Create and update issues from AI chat   |

<Note>
  Admin permissions are not required. Kasava only accesses data within the scope you authorize.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Plans" icon="file-text" href="/docs/features/plans">
    Create plans with embedded Linear issues
  </Card>

  <Card title="Products" icon="layer-group" href="/docs/features/products">
    Manage products and view roadmaps
  </Card>

  <Card title="AI Chat" icon="comments" href="/docs/features/ai-chat">
    Use AI to manage Linear issues
  </Card>
</CardGroup>