gv-ai

v1.1.3

Published

5 months ago

Internal CLI tool for GV team - Linear ticket enforcement and automated Sentry issue resolution

0High
0Medium
0Low

proper_naughty_boi

gv-internal internal-tool

GV AI - Linear Ticket Enforcement for AI Coding Tools

Automate Linear ticket tracking across OpenCode, Claude Code, and Gemini CLI. Never forget to update tickets again!

Problem

Backend developers often get so focused on building that they forget to:

Update Linear tasks with progress
Link PRs to tickets
Create tickets for ad-hoc work
Change ticket status

This leads to out-of-sync project management and lost context.

Solution

GV AI enforces a simple rule: No code changes without a Linear ticket.

Your AI coding assistant will:

Ask which Linear ticket you're working on before making changes
Show you existing tickets or help create new ones
Update the ticket automatically as you work
Link commits and PRs to the ticket

Features

Universal: Works with OpenCode, Claude Code, and Gemini CLI
Project-agnostic: Works in any repository
Simple setup: One command to configure everything
Non-intrusive: Only gates implementation, not conversations
Multi-ticket support: Track multiple tickets in one session

Installation

bun install -g @gv-org/gv-ai

Or use with bunx:

bunx @gv-org/gv-ai project init

Quick Start

1. Initialize Your Project

cd your-project
gv-ai project init

You'll be prompted to:

Select which AI tools you use (OpenCode, Claude Code, Gemini CLI, VSCode, Cursor, Windsurf)

That's it! The tool will:

Configure Linear's remote MCP server for selected tools
Create AGENTS.md with workflow instructions
Create symlinks (CLAUDE.md, GEMINI.md) if needed
Update .gitignore to exclude MCP configs

2. Authenticate with Linear

When you first use Linear in your AI tool, you'll be prompted to authenticate via OAuth. The MCP server will guide you through the process.

3. Start Coding

Restart your AI coding tool and start a session:

You: Fix the authentication bug in login.ts

Agent: Let me search for relevant Linear tickets...

Found potential matches:
1. BACK-234: Token expiration issues
2. BACK-189: Login endpoint returning 401

Or create new ticket in:
3. Backend API (BACK)
4. Platform (PLAT)

Which one? (enter number)

You: 1

Agent: ✓ Working on BACK-234: Token expiration issues
       Let me fix the bug...

How It Works

The Enforcement Gate

The agent follows these rules (defined in AGENTS.md):

Free actions (no ticket needed):

Answering questions
Explaining code
Discussing approaches
Code review

Gated actions (ticket required):

Creating/editing files
Running commands that modify state
Creating branches/PRs

Runtime Flow

User asks to implement something
Agent searches Linear for relevant tickets using MCP
Agent presents options as a numbered list:
- Existing tickets that match
- Options to create new tickets in different projects
User selects a number
Agent proceeds and updates the ticket as it works

Multi-Ticket Support

If your work touches multiple features:

You: Refactor the authentication system

Agent: This work touches multiple areas. I found:
1. BACK-234: Token expiration (authentication logic)
2. BACK-156: Session management (related)

Should I track both tickets? Or just one?

You: Both

Agent: ✓ Tracking BACK-234 and BACK-156
       [proceeds with implementation]

Configuration

File Structure After Init

your-project/
├── AGENTS.md                 # Main instruction file
├── CLAUDE.md → AGENTS.md     # Symlink (if using Claude Code)
├── GEMINI.md → AGENTS.md     # Symlink (if using Gemini CLI)
├── .mcp.json                 # Claude Code MCP config
├── .gemini/
│   └── settings.json         # Gemini CLI MCP config
└── opencode.json             # OpenCode MCP config

MCP Configuration

The tool configures the Linear MCP server for each selected tool:

OpenCode (opencode.json):

{
  "mcp": {
    "linear": {
      "type": "local",
      "command": ["npx", "-y", "mcp-remote", "https://mcp.linear.app/sse"],
      "enabled": true
    }
  }
}

Claude Code (.mcp.json):

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
    }
  }
}

Gemini CLI (.gemini/settings.json):

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
    }
  }
}

VSCode (.vscode/mcp.json):

{
  "servers": {
    "linear": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"],
      "auth": {
        "type": "oauth2"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
    }
  }
}

Customizing AGENTS.md

The generated AGENTS.md contains the Linear workflow instructions. You can customize:

Which actions require tickets
Status transitions (Todo → In Progress → In Review)
Branch naming conventions
Ad-hoc ticket labels

Supported AI Tools

| Tool | Status | Notes | |------|--------|-------| | OpenCode | ✅ Fully supported | Reads AGENTS.md directly | | Claude Code | ✅ Fully supported | Uses symlink to CLAUDE.md | | Gemini CLI | ✅ Fully supported | Uses symlink to GEMINI.md | | VSCode | ✅ Fully supported | Reads AGENTS.md directly | | Cursor | ✅ Fully supported | Reads AGENTS.md directly | | Windsurf | ✅ Fully supported | Reads AGENTS.md directly |

CLI Commands

# Initialize project
gv-ai project init

# Future commands (coming soon)
gv-ai project status        # View current configuration
gv-ai project add-tool      # Add another AI tool
gv-ai config show           # Show current config

Technical Details

Built With

TypeScript - Type-safe CLI development
Commander - CLI framework
Inquirer - Interactive prompts
Chalk - Terminal styling
Ora - Loading spinners
Execa - Process execution

Requirements

Node.js 20.0.0 or higher
npm or yarn
At least one AI coding tool installed (OpenCode, Claude Code, or Gemini CLI)
Linear API key

AGENTS.md Standard

This tool follows the AGENTS.md standard, an open format for guiding AI coding agents. AGENTS.md is supported by:

OpenCode
Claude Code (via symlink)
Gemini CLI (via symlink)
Cursor
GitHub Copilot
Devin
Factory
And 60,000+ open source projects

Linear MCP Server

Uses the community-built linear-mcp-server which provides:

Issue search and filtering
Issue creation and updates
Comment management
Project and team listing
User assignment

Troubleshooting

"Tool not found" error

Make sure the AI coding tool is installed and available in your PATH:

# Check if tools are installed
opencode --version
claude --version
gemini --version

MCP not working

Restart your AI tool - MCP configs are loaded at startup
Check your Linear API key - Test it at linear.app/settings/api
Verify MCP config files - Make sure they were created in the right location

Agent not enforcing tickets

Check AGENTS.md exists - The agent needs this file to know the rules
Verify symlinks - Claude Code and Gemini CLI need CLAUDE.md/GEMINI.md symlinks
Restart your session - Some tools need a fresh session to reload instructions

Examples

Example 1: Bug Fix

You: The user profile page is crashing when email is null

Agent: Let me search Linear...

Found: FRONT-89: Profile page crashes with null email

Is this the ticket? (yes/no)

You: yes

Agent: ✓ Working on FRONT-89
       [analyzes code, finds bug, implements fix]

       I've fixed the null check in ProfilePage.tsx
       Updated FRONT-89 with the solution

Example 2: New Feature

You: Add dark mode toggle to settings

Agent: No existing ticket found. Create new ticket in:
1. Frontend (FRONT)
2. Design System (DS)

Which project? (enter number)

You: 1

Agent: ✓ Created FRONT-234: Add dark mode toggle to settings (ad-hoc)
       ✓ Set status to "In Progress"

       [proceeds with implementation]

Example 3: Refactoring

You: Refactor the auth system to use JWT instead of sessions

Agent: This affects multiple areas. Found:
1. BACK-156: Migrate to JWT authentication
2. BACK-189: Remove session storage

Work on both tickets?

You: yes

Agent: ✓ Tracking BACK-156 and BACK-189
       [proceeds with refactoring both areas]

Roadmap

[ ] Support for GitHub integration
[ ] Automatic PR creation with ticket linking
[ ] Status auto-transitions based on git events
[ ] Team-wide configuration templates
[ ] Analytics dashboard for ticket tracking
[ ] Slack notifications for ticket updates

Contributing

This is an internal tool for GV team. For issues or suggestions, reach out to the platform team.

License

MIT

Credits

Built with:

AGENTS.md Standard - Open format for AI agents
Model Context Protocol (MCP) - Standard for connecting AI to data sources
Linear MCP Server - Community-built Linear integration
Commander.js - CLI framework
Inquirer - Interactive prompts