Linear Integration for Omi

Manage your Linear issues with voice commands through your Omi device. Create issues, track your work, update statuses, and add comments – all hands-free!

🚨 OMI APP STORE - COPY THESE URLs

Current ngrok URL: https://spacious-undiscouragingly-kelle.ngrok-free.dev

App Store Form Fields

Field	Value
App Name	Linear
Category	Productivity
Description	Manage your Linear issues with voice commands. Create issues, track work, update statuses, and add comments – all hands-free through your Omi device.

URLs to Enter in Omi App Store

Field	URL
App Home URL	`https://spacious-undiscouragingly-kelle.ngrok-free.dev/`
Setup Completed URL	`https://spacious-undiscouragingly-kelle.ngrok-free.dev/setup/linear`
Chat Tools Manifest URL	`https://spacious-undiscouragingly-kelle.ngrok-free.dev/.well-known/omi-tools.json`

Linear OAuth Redirect URI (Add to Linear Dashboard)

https://spacious-undiscouragingly-kelle.ngrok-free.dev/auth/linear/callback

Capabilities to Enable

✅ External Integration (required for chat tools)
✅ Chat (for voice command responses)

🎯 Features

➕ Create Issues - Create new issues with title, description, and priority
📋 List My Issues - See all issues assigned to you
🔄 Update Status - Move issues through workflow states (Todo → In Progress → Done)
🔍 Search Issues - Find issues by keyword or topic
📄 Get Issue Details - View full details of any issue
💬 Add Comments - Add comments and updates to issues

🚀 Quick Start

Install the Linear app from the Omi App Store
Click "Connect Linear" to authenticate with your workspace
(Optional) Set a default team for issue creation
Start using voice commands!

🗣️ Voice Commands

Command	Description
"Create an issue: Fix login bug"	Create a new issue
"Create urgent issue: Server is down"	Create with priority
"Show my issues"	List your assigned issues
"Show my in-progress issues"	Filter by status
"Move ENG-123 to Done"	Update issue status
"Mark PROD-456 as In Progress"	Start working on an issue
"Search for authentication issues"	Find issues by keyword
"What's the status of ENG-789?"	Get issue details
"Tell me about PROD-123"	Get full issue information
"Add comment to ENG-456: Fixed the bug"	Add a comment to an issue

📋 Omi App Store Details

App Information

Field	Value
App Name	Linear
Category	Productivity & Work
Description	Manage your Linear issues with voice commands. Create issues, track work, update statuses, and add comments – all hands-free through your Omi device.
Author	Omi Community
Version	1.0.0

Capabilities

✅ External Integration (required for chat tools)
✅ Chat (for voice command responses)

URLs

URL Type	URL
App Home URL	`https://YOUR-APP.up.railway.app/`
Setup Completed URL	`https://YOUR-APP.up.railway.app/setup/linear`
Chat Tools Manifest URL	`https://YOUR-APP.up.railway.app/.well-known/omi-tools.json`

Important: Omi automatically appends ?uid=USER_ID to these URLs. Do NOT include {uid} in the URL.

🔧 Chat Tools

This app exposes a manifest endpoint at /.well-known/omi-tools.json that Omi automatically fetches when the app is created or updated.

Available Tools

Tool	Description
`create_issue`	Create a new issue in Linear
`list_my_issues`	List issues assigned to the user
`update_issue_status`	Update an issue's workflow status
`search_issues`	Search for issues by text
`get_issue`	Get detailed info about an issue
`add_comment`	Add a comment to an existing issue

🔐 Linear Developer Setup

Create OAuth Application

Go to Linear Settings > API
Click "Create OAuth application"
Fill in the details:
- Application name: Omi Integration
- Developer name: Your name
- Developer URL: https://omi.me
- Redirect URI: https://YOUR-APP.up.railway.app/auth/linear/callback
Note your Client ID and Client Secret

Required Scopes

The app requests these Linear permissions:

read - Read access to workspace data
write - Write access to issues
issues:create - Create new issues
comments:create - Add comments to issues

🛠️ Development

Prerequisites

Python 3.8+
Linear workspace with admin access

Local Setup

# Navigate to the plugin directory
cd plugins/linear

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Copy environment file and configure
cp .env.example .env
# Edit .env with your credentials

# Run the server
python main.py

Environment Variables

LINEAR_CLIENT_ID=your_client_id
LINEAR_CLIENT_SECRET=your_client_secret
LINEAR_REDIRECT_URI=https://your-domain.com/auth/linear/callback
PORT=8080
REDIS_URL=  # Optional: for production use

Local Testing with ngrok

# Start ngrok
ngrok http 8080

# Update LINEAR_REDIRECT_URI in .env with ngrok URL
# Update redirect URI in Linear OAuth app settings

🚀 Deploy to Railway

Step 1: Create Railway Project

Go to Railway and sign in
Click "New Project" → "Deploy from GitHub repo"
Select your repository and choose the plugins/linear folder

Step 2: Add Redis Database

In your Railway project, click "+ New" → "Database" → "Add Redis"
Railway automatically creates and connects the Redis instance
The REDIS_URL environment variable is set automatically

Step 3: Configure Environment Variables

Go to your service's Variables tab and add:

Variable	Value
`LINEAR_CLIENT_ID`	Your Linear OAuth Client ID
`LINEAR_CLIENT_SECRET`	Your Linear OAuth Client Secret
`LINEAR_REDIRECT_URI`	`https://YOUR-APP.up.railway.app/auth/linear/callback`

Note: Replace YOUR-APP with your actual Railway app domain (shown in Settings → Domains)

Step 4: Configure Root Directory

If deploying from the main repo, set the Root Directory to plugins/linear:

Go to Settings → Build → Root Directory
Enter: plugins/linear

Step 5: Update Linear OAuth App

Add your Railway URL as a redirect URI in your Linear OAuth application settings:

https://YOUR-APP.up.railway.app/auth/linear/callback

Step 6: Update Omi App Store

Update your app URLs in the Omi App Store:

URL Type	Value
App Home URL	`https://YOUR-APP.up.railway.app/`
Setup Completed URL	`https://YOUR-APP.up.railway.app/setup/linear`
Chat Tools Manifest URL	`https://YOUR-APP.up.railway.app/.well-known/omi-tools.json`

Railway Architecture

┌─────────────────────────────────────────────────┐
│                 Railway Project                  │
├─────────────────────────────────────────────────┤
│  ┌───────────────┐     ┌───────────────────┐   │
│  │  Linear App   │────▶│  Redis Database   │   │
│  │  (FastAPI)    │     │  (Persistent)     │   │
│  │               │     │                   │   │
│  │  - OAuth      │     │  - User tokens    │   │
│  │  - Chat tools │     │  - Settings       │   │
│  │  - GraphQL    │     │  - Default teams  │   │
│  └───────────────┘     └───────────────────┘   │
│         │                                       │
│         ▼                                       │
│  https://YOUR-APP.up.railway.app               │
└─────────────────────────────────────────────────┘

📡 API Endpoints

Endpoint	Method	Description
`/`	GET	Home page / App settings
`/health`	GET	Health check
`/auth/linear`	GET	Start OAuth flow
`/auth/linear/callback`	GET	OAuth callback
`/setup/linear`	GET	Check setup status
`/disconnect`	GET	Disconnect account
`/tools/create_issue`	POST	Chat tool: Create issue
`/tools/list_my_issues`	POST	Chat tool: List my issues
`/tools/update_issue_status`	POST	Chat tool: Update status
`/tools/search_issues`	POST	Chat tool: Search issues
`/tools/get_issue`	POST	Chat tool: Get issue details
`/tools/add_comment`	POST	Chat tool: Add comment

🎨 Priority Levels

When creating issues, you can specify priority:

Priority	Color	Description
🔴 Urgent	Red	Critical issues needing immediate attention
🟠 High	Orange	Important issues to address soon
🟡 Medium	Yellow	Standard priority issues
🔵 Low	Blue	Nice-to-have or backlog items
⚪ None	Gray	No priority set

🐛 Troubleshooting

"User not authenticated"

Complete the Linear OAuth flow by clicking "Connect Linear" in app settings

"No teams found"

Ensure you have access to at least one team in your Linear workspace
Try reconnecting your Linear account

"Could not find issue"

Verify the issue identifier is correct (e.g., "ENG-123")
Ensure the issue exists in a team you have access to

"Failed to update status"

Check that the status name is valid for your team's workflow
Try using standard names: "Backlog", "Todo", "In Progress", "Done"

📄 License

MIT License - feel free to modify and distribute.

🤝 Support

For issues or feature requests, please open an issue on GitHub or contact the Omi community.

Made with ❤️ for Omi

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
templates		templates
.env.example		.env.example
.gitignore		.gitignore
Procfile		Procfile
README.md		README.md
db.py		db.py
main.py		main.py
models.py		models.py
railway.toml		railway.toml
requirements.txt		requirements.txt

BasedHardware/omi-linear-app

Folders and files

Latest commit

History

Repository files navigation