gitlin 🤖

AI-powered GitHub bot that creates Linear issues from code reviews, PRs, and commits.

Stop manually copying tasks from code reviews into Linear. Just comment /create-issues and let Claude do the work.

Features

✨ AI-Powered Extraction - Uses Claude to intelligently parse comments, reviews, and PRs
📋 Smart Issue Creation - Automatically populates title, description, priority, effort, labels, and assignees
🔗 Dependency Management - Links related issues automatically
👀 Visual Feedback - Emoji reactions show processing status (eyes → rocket on success)
⚡ Zero Configuration - Works out of the box with sensible defaults
🎯 Context-Aware - Understands PR context, commit history, and review feedback
🔐 Secure - Auto-fetches Linear team UUID, validates origins, minimal permissions
🚀 Fast - Docker-based execution with 87% faster cold start (19s vs 152s)
🎯 Smart Filtering - Automatically skips resolved comment threads to prevent duplicates
🏷️ Intelligent Labels - AI receives Linear's available labels for accurate suggestions, automatic tagging
🔄 Duplicate Detection - Tracks processed comments to prevent creating duplicate issues on multiple runs
🔍 Automatic Comment Gathering - Fetches and analyzes all unresolved PR comments in one operation
🖥️ Interactive TUI - Terminal interface for browsing, selecting, and editing issues before creation

Quick Start

Option 1: Automatic Setup (Recommended)

Clone this repo into your project and run the interactive setup:

cd your-project
git clone https://github.com/paperdiamond/gitlin.git .gitlin
cd .gitlin
pnpm install
pnpm run setup

The setup wizard will:

Install the GitHub Action workflow
Automatically fetch your Linear teams and let you select one (no manual UUID lookup!)
Add required secrets to your repository (via GitHub CLI)
Verify everything is configured correctly

Option 2: Manual Setup

If you prefer to set things up manually:

1. Add the GitHub Action workflow

Create .github/workflows/gitlin.yml:

name: Gitlin - Create Linear Issues
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  create-issues:
    if: contains(github.event.comment.body, '/create-issues')
    uses: paperdiamond/gitlin/.github/workflows/gitlin-bot.yml@main
    secrets:
      LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
      LINEAR_TEAM_ID: ${{ secrets.LINEAR_TEAM_ID }}
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

2. Add Secrets

Go to your repository's Settings → Secrets → Actions and add:

LINEAR_API_KEY - Get from https://linear.app/settings/api
LINEAR_TEAM_ID - Your Linear team UUID (get it by running node scripts/get-team-id.js in the gitlin directory)
ANTHROPIC_API_KEY - Get from https://console.anthropic.com/

Interactive TUI Mode

For a more hands-on experience, use the interactive Terminal User Interface:

cd .gitlin
pnpm tui

Requirements: The TUI requires a .env file with your API keys:

cp .env.example .env
# Edit .env and add your LINEAR_API_KEY, LINEAR_TEAM_ID, and ANTHROPIC_API_KEY

TUI Workflow

Select Repository - Auto-detects current repo from git, or choose from your recent GitHub repos
Select PR - Browse open PRs or enter a PR number manually
Select Comments - View all unresolved comments, with existing Linear tickets marked (🎫)
AI Analysis - Claude parses selected comments and extracts actionable issues
Review & Edit - Toggle issues on/off, edit title/description/priority/effort/labels
Confirm & Create - Preview final issues before creating them in Linear
Results - See created issues with direct links to Linear

TUI Features

📂 Smart Repo Detection - Auto-detects current repo from git remote
📋 PR Browser - Lists open PRs with author info, or enter PR # manually
🎫 Duplicate Detection - Comments with existing Linear tickets are marked
✏️ Full Issue Editor - Edit all fields: title, description, priority, effort, labels
🏷️ Label Picker - Multi-select from your Linear team's available labels
☑️ Selective Creation - Toggle individual issues on/off before creating

Keyboard Shortcuts

Screen	Key	Action
All	`↑/↓` or `j/k`	Navigate up/down
All	`Esc`	Go back to previous screen
All	`q`	Quit (except when editing)
All	`Ctrl+C`	Force quit
Comments	`Space`	Toggle comment selection
Comments	`a`	Select all comments
Comments	`n`	Deselect all comments
Comments	`Enter`	Continue to AI analysis
Issues	`Space` or `t`	Toggle issue enabled/disabled
Issues	`Enter` or `e`	Edit selected issue
Issues	`c`	Continue to confirmation
Editor	`Enter` or `e`	Edit current field
Editor	`s`	Save and return
Results	`r`	Create more issues (restart)
Error	`r`	Retry from beginning

Use It (GitHub Action)

Comment /create-issues on any PR or issue, and the bot will:

Automatically fetch all unresolved comments on the PR (both issue comments and review comments)
Filter out resolved review threads to prevent duplicate issues
Parse all comments and extract actionable items using AI
Create Linear issues with full details
Reply with links to the created issues

Note: On PRs, the bot analyzes ALL unresolved comments, not just the one containing /create-issues. This means you can add multiple comments throughout a code review, then trigger issue creation with a single /create-issues command.

Examples

From Code Review Feedback

GitHub Comment:

Great work on the feature! A few things to address:

1. Add input validation for user email addresses
2. Extract the authentication logic into a reusable service
3. Consider adding rate limiting to the API endpoints

The security changes look good though!

/create-issues

gitlin creates:

✅ Created 3 Linear issues:

- [PROJ-123](https://linear.app/team/issue/PROJ-123) Add input validation for user email addresses
  Priority: High | Effort: Small | Assignee: [email protected]

- [PROJ-124](https://linear.app/team/issue/PROJ-124) Extract authentication logic into reusable service
  Priority: Medium | Effort: Medium | Assignee: [email protected]

- [PROJ-125](https://linear.app/team/issue/PROJ-125) Add rate limiting to API endpoints
  Priority: Low | Effort: Large | Assignee: Unassigned

From Commit Messages

The bot can also parse commit messages with follow-up items:

feat: Add user authentication with OAuth

## Follow-up Items

1. Add comprehensive error handling for auth failures (High priority, 3 points, [email protected])
   - Display user-friendly error messages for common auth failures
   - Log authentication errors to monitoring service
   - Add retry mechanism for transient failures

2. Implement session refresh token rotation (Medium priority, 5 points, [email protected])
   - Automatically refresh access tokens before expiration
   - Handle refresh token expiration gracefully
   - Add security audit logging for token refresh events

3. Add multi-factor authentication support (Low priority, 8 points, Unassigned)
   - Research MFA provider options (Authy, Google Authenticator)
   - Design user enrollment flow
   - Implement backup codes for account recovery

/create-issues

How It Works

graph LR
    A[Comment on GitHub] --> B[Trigger GitHub Action]
    B --> C[Extract Context]
    C --> D[AI Parser Claude]
    D --> E[Create Linear Issues]
    E --> F[Post Results]

Trigger: User comments /create-issues
Fetch: Bot automatically fetches all unresolved comments on the PR
Filter: Resolved review comment threads are skipped
Context: Bot gathers PR title, description, and all comment text
AI Parse: Claude analyzes content and extracts structured issues
Validation: Zod validates the parsed data structure
Creation: Linear SDK creates issues with all fields
Response: Bot replies with links to created issues

Configuration

Create .github/gitlin.json to customize behavior:

{
  "defaultPriority": "medium",
  "labelMapping": {
    "security": ["security", "vulnerability"],
    "performance": ["performance", "optimization"],
    "ui": ["frontend", "design"]
  },
  "effortMapping": {
    "small": 1,
    "medium": 3,
    "large": 5
  },
  "gitlinAutoTag": "gitlin-created",
  "skipResolvedComments": true
}

Configuration Options

labelMapping: Map AI-suggested labels to multiple Linear labels
gitlinAutoTag: Custom tag added to all created issues (default: "gitlin-created")
skipResolvedComments: Skip creating issues from resolved comment threads (default: true)
defaultPriority: Default priority if AI can't determine it
effortMapping: Map effort estimates to Linear points

Development

Setup

git clone https://github.com/yourusername/gitlin.git
cd gitlin
pnpm install
cp .env.example .env  # Add your API keys

Run Locally

pnpm run dev

Test

pnpm test              # Run tests once
pnpm test:watch        # Run tests in watch mode
pnpm lint              # Check for lint errors
pnpm format:check      # Check formatting

CI/CD: All PRs run automated tests via GitHub Actions. Tests must pass before merging.

Build

pnpm run build

API

Programmatic Usage

import { Gitlin } from "gitlin";

const bot = new Gitlin({
  linearApiKey: "lin_api_...",
  linearTeamId: "abc123",
  anthropicApiKey: "sk-ant-...",
  githubToken: "ghp_...",
});

const result = await bot.processComment({
  owner: "acme",
  repo: "project",
  prNumber: 42,
  commentBody: "Add error handling\n\n/create-issues",
});

console.log(result);
// ✅ Created 1 Linear issue:
// - [ACME-123](https://linear.app/...) Add error handling

Performance

gitlin is optimized for speed and efficiency:

87% faster execution: Docker-based deployment reduces cold start from ~152s to ~19s
Smart caching: Linear labels cached across issue creation runs
Efficient AI calls: Claude receives only relevant context for faster responses
Duplicate detection: Skips already-processed comments to save time and API calls

Before vs After

Before (pnpm install):  ~152s  (install 90s + build 30s + run 32s)
After (Docker):         ~19s   (pull 3s + run 16s, cached)

Cost

gitlin uses Claude Sonnet which costs approximately:

$0.01-0.05 per run (depending on context size)
Average PR review: ~$0.02
500 uses/month: ~$10

This pays for itself immediately by saving 5-10 minutes per code review.

Roadmap

Completed ✅

Docker-based execution for 87% faster performance (19s vs 152s)
Automatic resolution filtering (skip resolved comments)
Intelligent label suggestions (AI receives Linear labels)
Label mapping configuration
Auto-tagging for audit trail (gitlin-created tag)
Duplicate detection (tracks processed comments)
Automatic comment gathering (fetches all unresolved PR comments)
Conservative priority assignment (prevents over-prioritization)
Interactive TUI for manual issue selection

Planned

Sub-issue hierarchy support
Support for multiple Linear teams
Slack integration
Custom AI models (GPT-4, local models)
Integration with GitHub Projects

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

License

Built with ❤️ by Paper Diamond

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github/workflows		.github/workflows
dist		dist
docs		docs
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

License

paperdiamond/gitlin

Folders and files

Latest commit

History

Repository files navigation

gitlin 🤖

Features

Quick Start

Option 1: Automatic Setup (Recommended)

Option 2: Manual Setup

Interactive TUI Mode

TUI Workflow

TUI Features

Keyboard Shortcuts

Use It (GitHub Action)

Examples

From Code Review Feedback

From Commit Messages

How It Works

Configuration

Configuration Options

Development

Setup

Run Locally

Test

Build

API

Programmatic Usage

Performance

Before vs After

Cost

Roadmap

Completed ✅

Planned

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages