{"id":34239324,"url":"https://github.com/paperdiamond/gitlin","last_synced_at":"2026-03-13T10:32:07.224Z","repository":{"id":327362819,"uuid":"1108971101","full_name":"paperdiamond/gitlin","owner":"paperdiamond","description":"AI-powered GitHub bot that creates Linear issues from code reviews, PRs, and commits. Just comment /create-issues and let Claude do the work.","archived":false,"fork":false,"pushed_at":"2025-12-03T11:21:44.000Z","size":192,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-06T08:46:26.686Z","etag":null,"topics":["ai","automation","claude","developer-tools","github-bot","linear","productivity","project-management"],"latest_commit_sha":null,"homepage":"https://github.com/paperdiamond/gitlin","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paperdiamond.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-03T06:57:27.000Z","updated_at":"2025-12-04T22:53:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/paperdiamond/gitlin","commit_stats":null,"previous_names":["paperdiamond/gitlin"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/paperdiamond/gitlin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperdiamond%2Fgitlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperdiamond%2Fgitlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperdiamond%2Fgitlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperdiamond%2Fgitlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paperdiamond","download_url":"https://codeload.github.com/paperdiamond/gitlin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperdiamond%2Fgitlin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30465421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T06:34:02.089Z","status":"ssl_error","status_checked_at":"2026-03-13T06:33:49.182Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","claude","developer-tools","github-bot","linear","productivity","project-management"],"created_at":"2025-12-16T03:36:23.772Z","updated_at":"2026-03-13T10:32:07.215Z","avatar_url":"https://github.com/paperdiamond.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gitlin 🤖\n\n\u003e AI-powered GitHub bot that creates Linear issues from code reviews, PRs, and commits.\n\nStop manually copying tasks from code reviews into Linear. Just comment `/create-issues` and let Claude do the work.\n\n## Features\n\n- ✨ **AI-Powered Extraction** - Uses Claude to intelligently parse comments, reviews, and PRs\n- 📋 **Smart Issue Creation** - Automatically populates title, description, priority, effort, labels, and assignees\n- 🔗 **Dependency Management** - Links related issues automatically\n- 👀 **Visual Feedback** - Emoji reactions show processing status (eyes → rocket on success)\n- ⚡ **Zero Configuration** - Works out of the box with sensible defaults\n- 🎯 **Context-Aware** - Understands PR context, commit history, and review feedback\n- 🔐 **Secure** - Auto-fetches Linear team UUID, validates origins, minimal permissions\n- 🚀 **Fast** - Docker-based execution with 87% faster cold start (19s vs 152s)\n- 🎯 **Smart Filtering** - Automatically skips resolved comment threads to prevent duplicates\n- 🏷️ **Intelligent Labels** - AI receives Linear's available labels for accurate suggestions, automatic tagging\n- 🔄 **Duplicate Detection** - Tracks processed comments to prevent creating duplicate issues on multiple runs\n- 🔍 **Automatic Comment Gathering** - Fetches and analyzes all unresolved PR comments in one operation\n- 🖥️ **Interactive TUI** - Terminal interface for browsing, selecting, and editing issues before creation\n\n## Quick Start\n\n### Option 1: Automatic Setup (Recommended)\n\nClone this repo into your project and run the interactive setup:\n\n```zsh\ncd your-project\ngit clone https://github.com/paperdiamond/gitlin.git .gitlin\ncd .gitlin\npnpm install\npnpm run setup\n```\n\nThe setup wizard will:\n- Install the GitHub Action workflow\n- Automatically fetch your Linear teams and let you select one (no manual UUID lookup!)\n- Add required secrets to your repository (via GitHub CLI)\n- Verify everything is configured correctly\n\n### Option 2: Manual Setup\n\nIf you prefer to set things up manually:\n\n**1. Add the GitHub Action workflow**\n\nCreate `.github/workflows/gitlin.yml`:\n\n```yaml\nname: Gitlin - Create Linear Issues\non:\n  issue_comment:\n    types: [created]\n  pull_request_review_comment:\n    types: [created]\n\njobs:\n  create-issues:\n    if: contains(github.event.comment.body, '/create-issues')\n    uses: paperdiamond/gitlin/.github/workflows/gitlin-bot.yml@main\n    secrets:\n      LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}\n      LINEAR_TEAM_ID: ${{ secrets.LINEAR_TEAM_ID }}\n      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n```\n\n**2. Add Secrets**\n\nGo to your repository's Settings → Secrets → Actions and add:\n\n- `LINEAR_API_KEY` - Get from https://linear.app/settings/api\n- `LINEAR_TEAM_ID` - Your Linear team UUID (get it by running `node scripts/get-team-id.js` in the gitlin directory)\n- `ANTHROPIC_API_KEY` - Get from https://console.anthropic.com/\n\n### Interactive TUI Mode\n\nFor a more hands-on experience, use the interactive Terminal User Interface:\n\n```zsh\ncd .gitlin\npnpm tui\n```\n\n**Requirements:** The TUI requires a `.env` file with your API keys:\n```zsh\ncp .env.example .env\n# Edit .env and add your LINEAR_API_KEY, LINEAR_TEAM_ID, and ANTHROPIC_API_KEY\n```\n\n#### TUI Workflow\n\n1. **Select Repository** - Auto-detects current repo from git, or choose from your recent GitHub repos\n2. **Select PR** - Browse open PRs or enter a PR number manually\n3. **Select Comments** - View all unresolved comments, with existing Linear tickets marked (🎫)\n4. **AI Analysis** - Claude parses selected comments and extracts actionable issues\n5. **Review \u0026 Edit** - Toggle issues on/off, edit title/description/priority/effort/labels\n6. **Confirm \u0026 Create** - Preview final issues before creating them in Linear\n7. **Results** - See created issues with direct links to Linear\n\n#### TUI Features\n\n- 📂 **Smart Repo Detection** - Auto-detects current repo from git remote\n- 📋 **PR Browser** - Lists open PRs with author info, or enter PR # manually\n- 🎫 **Duplicate Detection** - Comments with existing Linear tickets are marked\n- ✏️ **Full Issue Editor** - Edit all fields: title, description, priority, effort, labels\n- 🏷️ **Label Picker** - Multi-select from your Linear team's available labels\n- ☑️ **Selective Creation** - Toggle individual issues on/off before creating\n\n#### Keyboard Shortcuts\n\n| Screen | Key | Action |\n|--------|-----|--------|\n| All | `↑/↓` or `j/k` | Navigate up/down |\n| All | `Esc` | Go back to previous screen |\n| All | `q` | Quit (except when editing) |\n| All | `Ctrl+C` | Force quit |\n| Comments | `Space` | Toggle comment selection |\n| Comments | `a` | Select all comments |\n| Comments | `n` | Deselect all comments |\n| Comments | `Enter` | Continue to AI analysis |\n| Issues | `Space` or `t` | Toggle issue enabled/disabled |\n| Issues | `Enter` or `e` | Edit selected issue |\n| Issues | `c` | Continue to confirmation |\n| Editor | `Enter` or `e` | Edit current field |\n| Editor | `s` | Save and return |\n| Results | `r` | Create more issues (restart) |\n| Error | `r` | Retry from beginning |\n\n### Use It (GitHub Action)\n\nComment `/create-issues` on any PR or issue, and the bot will:\n1. **Automatically fetch all unresolved comments** on the PR (both issue comments and review comments)\n2. **Filter out resolved review threads** to prevent duplicate issues\n3. Parse all comments and extract actionable items using AI\n4. Create Linear issues with full details\n5. Reply with links to the created issues\n\n**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.\n\n## Examples\n\n### From Code Review Feedback\n\n**GitHub Comment:**\n```\nGreat work on the feature! A few things to address:\n\n1. Add input validation for user email addresses\n2. Extract the authentication logic into a reusable service\n3. Consider adding rate limiting to the API endpoints\n\nThe security changes look good though!\n\n/create-issues\n```\n\n**gitlin creates:**\n```\n✅ Created 3 Linear issues:\n\n- [PROJ-123](https://linear.app/team/issue/PROJ-123) Add input validation for user email addresses\n  Priority: High | Effort: Small | Assignee: alex@company.com\n\n- [PROJ-124](https://linear.app/team/issue/PROJ-124) Extract authentication logic into reusable service\n  Priority: Medium | Effort: Medium | Assignee: taylor@company.com\n\n- [PROJ-125](https://linear.app/team/issue/PROJ-125) Add rate limiting to API endpoints\n  Priority: Low | Effort: Large | Assignee: Unassigned\n```\n\n### From Commit Messages\n\nThe bot can also parse commit messages with follow-up items:\n\n```\nfeat: Add user authentication with OAuth\n\n## Follow-up Items\n\n1. Add comprehensive error handling for auth failures (High priority, 3 points, jordan@company.com)\n   - Display user-friendly error messages for common auth failures\n   - Log authentication errors to monitoring service\n   - Add retry mechanism for transient failures\n\n2. Implement session refresh token rotation (Medium priority, 5 points, casey@company.com)\n   - Automatically refresh access tokens before expiration\n   - Handle refresh token expiration gracefully\n   - Add security audit logging for token refresh events\n\n3. Add multi-factor authentication support (Low priority, 8 points, Unassigned)\n   - Research MFA provider options (Authy, Google Authenticator)\n   - Design user enrollment flow\n   - Implement backup codes for account recovery\n\n/create-issues\n```\n\n## How It Works\n\n```mermaid\ngraph LR\n    A[Comment on GitHub] --\u003e B[Trigger GitHub Action]\n    B --\u003e C[Extract Context]\n    C --\u003e D[AI Parser Claude]\n    D --\u003e E[Create Linear Issues]\n    E --\u003e F[Post Results]\n```\n\n1. **Trigger**: User comments `/create-issues`\n2. **Fetch**: Bot automatically fetches all unresolved comments on the PR\n3. **Filter**: Resolved review comment threads are skipped\n4. **Context**: Bot gathers PR title, description, and all comment text\n5. **AI Parse**: Claude analyzes content and extracts structured issues\n6. **Validation**: Zod validates the parsed data structure\n7. **Creation**: Linear SDK creates issues with all fields\n8. **Response**: Bot replies with links to created issues\n\n## Configuration\n\nCreate `.github/gitlin.json` to customize behavior:\n\n```json\n{\n  \"defaultPriority\": \"medium\",\n  \"labelMapping\": {\n    \"security\": [\"security\", \"vulnerability\"],\n    \"performance\": [\"performance\", \"optimization\"],\n    \"ui\": [\"frontend\", \"design\"]\n  },\n  \"effortMapping\": {\n    \"small\": 1,\n    \"medium\": 3,\n    \"large\": 5\n  },\n  \"gitlinAutoTag\": \"gitlin-created\",\n  \"skipResolvedComments\": true\n}\n```\n\n### Configuration Options\n\n- **`labelMapping`**: Map AI-suggested labels to multiple Linear labels\n- **`gitlinAutoTag`**: Custom tag added to all created issues (default: `\"gitlin-created\"`)\n- **`skipResolvedComments`**: Skip creating issues from resolved comment threads (default: `true`)\n- **`defaultPriority`**: Default priority if AI can't determine it\n- **`effortMapping`**: Map effort estimates to Linear points\n\n## Development\n\n### Setup\n\n```zsh\ngit clone https://github.com/yourusername/gitlin.git\ncd gitlin\npnpm install\ncp .env.example .env  # Add your API keys\n```\n\n### Run Locally\n\n```zsh\npnpm run dev\n```\n\n### Test\n\n```zsh\npnpm test              # Run tests once\npnpm test:watch        # Run tests in watch mode\npnpm lint              # Check for lint errors\npnpm format:check      # Check formatting\n```\n\n**CI/CD:** All PRs run automated tests via GitHub Actions. Tests must pass before merging.\n\n### Build\n\n```zsh\npnpm run build\n```\n\n## API\n\n### Programmatic Usage\n\n```typescript\nimport { Gitlin } from \"gitlin\";\n\nconst bot = new Gitlin({\n  linearApiKey: \"lin_api_...\",\n  linearTeamId: \"abc123\",\n  anthropicApiKey: \"sk-ant-...\",\n  githubToken: \"ghp_...\",\n});\n\nconst result = await bot.processComment({\n  owner: \"acme\",\n  repo: \"project\",\n  prNumber: 42,\n  commentBody: \"Add error handling\\n\\n/create-issues\",\n});\n\nconsole.log(result);\n// ✅ Created 1 Linear issue:\n// - [ACME-123](https://linear.app/...) Add error handling\n```\n\n## Performance\n\ngitlin is optimized for speed and efficiency:\n\n- **87% faster execution**: Docker-based deployment reduces cold start from ~152s to ~19s\n- **Smart caching**: Linear labels cached across issue creation runs\n- **Efficient AI calls**: Claude receives only relevant context for faster responses\n- **Duplicate detection**: Skips already-processed comments to save time and API calls\n\n### Before vs After\n```\nBefore (pnpm install):  ~152s  (install 90s + build 30s + run 32s)\nAfter (Docker):         ~19s   (pull 3s + run 16s, cached)\n```\n\n## Cost\n\ngitlin uses Claude Sonnet which costs approximately:\n- **$0.01-0.05 per run** (depending on context size)\n- Average PR review: ~$0.02\n- 500 uses/month: ~$10\n\nThis pays for itself immediately by saving 5-10 minutes per code review.\n\n## Roadmap\n\n### Completed ✅\n- [x] Docker-based execution for 87% faster performance (19s vs 152s)\n- [x] Automatic resolution filtering (skip resolved comments)\n- [x] Intelligent label suggestions (AI receives Linear labels)\n- [x] Label mapping configuration\n- [x] Auto-tagging for audit trail (gitlin-created tag)\n- [x] Duplicate detection (tracks processed comments)\n- [x] Automatic comment gathering (fetches all unresolved PR comments)\n- [x] Conservative priority assignment (prevents over-prioritization)\n- [x] Interactive TUI for manual issue selection\n\n### Planned\n- [ ] Sub-issue hierarchy support\n- [ ] Support for multiple Linear teams\n- [ ] Slack integration\n- [ ] Custom AI models (GPT-4, local models)\n- [ ] Integration with GitHub Projects\n\n## Contributing\n\nContributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.\n\n## License\n\nMIT © Paper Diamond\n\n---\n\n**Built with** ❤️ **by Paper Diamond**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperdiamond%2Fgitlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaperdiamond%2Fgitlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperdiamond%2Fgitlin/lists"}