🚀 Gorev

🎯 What is Gorev

Gorev is a powerful Model Context Protocol (MCP) server written in Go that provides task management capabilities to all MCP-compatible AI editors (Claude Desktop, VS Code, Windsurf, Cursor, Zed, etc.). It combines project management, task tracking, and organization needs with the power of AI assistants to boost your productivity.

🏗️ Three-Module Architecture

1. gorev-mcpserver - MCP server written in Go (core component)

2. gorev-vscode - VS Code extension (optional visual interface)

3. gorev-web - React + TypeScript source code (development)

Thanks to the MCP protocol, you can connect to the server from any MCP-compatible editor. The daemon automatically starts on first MCP connection, and the Web UI becomes available at http://localhost:5082. The VS Code extension provides a rich IDE-integrated experience with automatic daemon management.

🔌 Daemon Architecture (v0.16.0+)

Gorev runs as a background daemon process, providing these key benefits:

Core Features:

• Single Instance Management: Lock file (`~/.gorev-daemon/.lock`) prevents port conflicts
• Multi-Client Support: Multiple MCP clients (Claude, VS Code, Windsurf, Cursor) can connect simultaneously
• Auto-Start: VS Code extension automatically detects and starts daemon (v0.16.2+)
• Health Monitoring: Real-time status via `/api/health` endpoint
• WebSocket Support: Real-time task update events (experimental)

Quick Start:

# Start daemon in background
gorev daemon --detach

# Check daemon status
curl http://localhost:5082/api/health

# Web UI automatically available
open http://localhost:5082

Architecture Diagram

graph TB
    subgraph "External Clients"
        Claude[Claude Desktop/Code]
        VSCode[VS Code Extension]
        Cursor[Cursor IDE]
        Windsurf[Windsurf]
    end

    subgraph "Gorev Daemon (Port 5082)"
        Lock[Lock File~/.gorev-daemon/.lock]

        subgraph "Protocol Layers"
            MCP[MCP Proxystdio]
            REST[REST APIFiber - 23 endpoints]
            WS[WebSocketReal-time events]
        end

        Handler[MCP Handlers24 Unified Tools]

        subgraph "Storage"
            DB[(SQLite DB.gorev/gorev.db)]
        end

        WebUI[Embedded Web UIReact + TypeScript]
    end

    Claude -->|MCP/stdio| MCP
    VSCode -->|REST/HTTP| REST
    Cursor -->|MCP/stdio| MCP
    Windsurf -->|MCP/stdio| MCP

    MCP --> Handler
    REST --> Handler
    WS -.->|broadcasts| VSCode

    Handler --> DB

    REST --> WebUI

    Lock -.->|manages| MCP
    Lock -.->|manages| REST

    style Claude fill:#f9f,stroke:#333
    style VSCode fill:#9cf,stroke:#333
    style Cursor fill:#fc9,stroke:#333
    style Windsurf fill:#9fc,stroke:#333
    style Handler fill:#ff9,stroke:#333
    style DB fill:#9f9,stroke:#333

Architecture Components:

• Lock File: `~/.gorev-daemon/.lock` contains PID, port, version, and daemon URL
• REST API Server: 23 endpoints for VS Code extension (Fiber framework)
• MCP Proxy: Forwards stdio MCP protocol requests to internal handlers
• WebSocket Server: Real-time event broadcasting for task updates
• Workspace Manager: Multi-workspace support with SHA256-based IDs

VS Code Integration:

The extension automatically manages the daemon lifecycle:

1. On activation, checks if daemon is running (reads lock file)

2. Starts daemon if not running

3. Connects to REST API for all operations

4. Optionally shuts down daemon on deactivation (if extension started it)

See Daemon Architecture Documentation for detailed technical specifications.

🎉 What's New in v0.17.0

🔧 MCP Tool Parameter Transformation Fixes (October 6, 2025)

gorev_bulk - All 3 operations now fully functional:

• `update` operation: Properly transforms `{ids: [], data: {}}` → `{updates: [{id, ...fields}]}`
• `transition` operation: Accepts both `status` and `yeni_durum` parameter names for flexibility
• `tag` operation: Accepts both `operation` and `tag_operation` parameter names
• Test result: 100% success rate (5/5 operations passed in production)

gorev_guncelle - Extended to support multiple field updates:

• Can update `status` (status), `priority` (priority), or both simultaneously
• At least one parameter required for validation
• Backward compatible with existing code

gorev_search (advanced mode) - Smart query parsing added:

• Example: `"durum:devam_ediyor oncelik:yuksek tags:frontend"`
• Automatically extracts filters from natural language queries
• Multi-filter support with space-separated key:value pairs
• Works seamlessly with existing filter parameters

VS Code Tree View - Dependency indicators now visible:

• 🔒 (blocked), 🔓 (unblocked), 🔗 (dependents) icons display correctly
• Fixed JSON serialization issue (removed `omitempty` from dependency counters)
• All dependency relationships now visible in tree structure

Validation: 100% success rate confirmed by Kilocode AI comprehensive test report

🐛 Previous Updates (v0.16.2 - October 5, 2025)

• NPM Binary Update Fix: Fixed critical bug where NPM package upgrades preserved old binaries
  • Users upgrading from v0.16.1 or earlier were stuck on v0.15.24 (September 2025)
  • Package size reduced from 78.4 MB to 6.9 KB (binaries now always downloaded from GitHub)
  • All users now get latest features (REST API, Web UI, VS Code auto-start)
• VS Code Auto-Start: Extension now automatically detects and starts daemon
  • No manual commands required - daemon auto-starts via lock file detection
  • Checks if daemon is running (~/.gorev-daemon/.lock), starts if needed
  • Proper database path configuration (workspace/.gorev/gorev.db)
  • Shared daemon across all MCP clients (Claude, Cursor, Windsurf)

🌐 Embedded Web UI (v0.16.0)

• Zero-Configuration: Modern React interface built into Go binary
• Instant Access: Automatically available at http://localhost:5082
• Full Features: Tasks, projects, templates, subtasks, and dependencies
• Language Sync: Turkish/English switcher synchronized with MCP server
• No Separate Installation: Just run `npx @mehmetsenol/gorev-mcp-server serve` and you're ready!

🗂️ Multi-Workspace Support (v0.16.0)

• Isolated Workspaces: Each project folder gets its own task database
• Workspace Switcher: Seamlessly switch between workspaces in Web UI
• Auto-Detection: Automatically detects `.gorev/` directory in current folder
• SHA256 IDs: Secure workspace identification
• VS Code Integration: Extension auto-registers workspace on activation

🔌 REST API Migration

• 23 Endpoints: Complete Fiber-based REST API
• VS Code Extension: Migrated from MCP to REST API for better performance
• Type-Safe: 100% TypeScript with zero parsing errors
• Faster: Direct HTTP calls vs. stdio + markdown parsing
• Backward Compatible: MCP protocol still fully supported

🏷️ Template Aliases

• Quick Commands: Use `bug`, `feature`, `research` instead of template IDs
• Consistency: Same aliases across all workspaces
• No More UUID Hunting: Human-readable template identifiers
• Documentation: Full guide at MCP Config Examples

📦 NPM Package

• Package Name: `@mehmetsenol/gorev-mcp-server`
• Global Install: `npm install -g @mehmetsenol/gorev-mcp-server`
• NPX Ready: `npx @mehmetsenol/gorev-mcp-server serve` for instant use
• Cross-Platform: Works on Windows, macOS, and Linux

✨ Features

📝 Task Management

• Smart task creation - Using natural language commands
• Markdown support - Rich description formatting
• Status management - Pending → In Progress → Completed
• Priority levels - Low, Medium, High
• Flexible editing - Update all task properties

📁 Project Organization

• Hierarchical structure - Task grouping under projects
• Active project system - Quick operations with default project
• Project-based reporting - Detailed statistics
• Multi-project support - Unlimited project creation

🔗 Advanced Features

• 📅 Due date tracking - Deadline management and urgent task filtering
• 🏷️ Tagging system - Multi-tag categorization
• 🔄 Task dependencies - Inter-task automation
• 📋 Ready-made templates - Bug reports, feature requests, and more
• 🔍 Advanced filtering - Status, tag, date-based queries
• 🌳 Subtask hierarchy - Unlimited depth task tree structure
• 📊 Progress tracking - Subtask completion percentage in parent tasks
• 📁 File System Watcher - Monitor file changes and automatic task status transitions
• 🔔 Automatic Status Updates - "pending" → "in_progress" automation on file changes
• ⚙️ Configuration Management - Customizable ignore patterns and watch rules

🤖 AI Integration

• Natural language processing - Task management by talking to AI assistants
• Multi-editor support - Claude, VS Code, Windsurf, Cursor, Zed
• Contextual understanding - Smart command interpretation
• MCP standard - Compatible with all MCP-compatible tools

🎨 VS Code Extension Features (Optional)

• Bilingual Support - Turkish and English interface (v0.5.0+) 🌍
• TreeView Panels - Task, project, and template lists
• Visual Interface - Click-and-use experience
• Status Bar - Real-time status information
• Command Palette - Quick access (Ctrl+Shift+G)
• Color Coding - Priority-based visual distinction
• Context Menus - Right-click operations
• Automatic Language Detection - UI language based on VS Code language setting
• **Download from Marketplace** 🚀

🌐 Web UI Features (NEW! v0.16.0)

• Modern Browser Interface - No IDE required, works in any browser
• Task Cards - Rich task visualization with metadata
• Subtask Hierarchy - Expandable/collapsible nested tasks
• Dependency Badges - Visual indicators for task dependencies
• Project Organization - Sidebar navigation with task counts
• Template-Based Creation - Wizard for creating structured tasks
• Real-time Updates - React Query for automatic synchronization
• Responsive Design - Works on desktop and mobile devices
• 🌍 Language Switcher - Toggle between Turkish/English, synchronized with MCP server
• Quick Actions - Edit, delete, and status updates
• REST API Backend - Fiber-based high-performance API server
• 🚀 No Installation Required: Automatically active with `npx @mehmetsenol/gorev-mcp-server serve`!
• Embedded UI: Bundled in Go binary, no separate setup needed
• Access: http://localhost:5082 (default port)

📦 Installation

🚀 NPM Quick Setup (Recommended!)

> ⚠️ Windows Users: NPM requires Node.js installation. Download Node.js and restart your system after installation.

Global Installation

npm install -g @mehmetsenol/gorev-mcp-server

Or use directly with NPX (no installation required):

npx @mehmetsenol/gorev-mcp-server serve

MCP Client Configuration

For Claude Desktop:

// Windows: %APPDATA%/Claude/claude_desktop_config.json
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmetsenol/gorev-mcp-server@latest"
      ],
      "env": {
        "GOREV_LANG": "en"
      }
    }
  }
}
// Note: Daemon auto-starts on first connection. No manual setup required!

For Kilo Code (VS Code Extension):

// .kilocode/mcp.json (workspace root)
{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmetsenol/gorev-mcp-server@latest"
      ],
      "env": {
        "GOREV_LANG": "en"
      }
    }
  }
}

For Cursor:

// .cursor/mcp.json (workspace root)
{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmetsenol/gorev-mcp-server@latest"
      ],
      "env": {
        "GOREV_LANG": "en"
      }
    }
  }
}

> 📚 More Examples: MCP Configuration Guide

🔧 Windows NPX Troubleshooting

If you get `ENOENT: spawn npx` error:

1. Check if Node.js is installed:

node --version
   npm --version
   npx --version

2. Install Node.js:

3. Install NPX separately (if needed):

npm install -g npx

4. Check PATH:

echo %PATH%

Should include Node.js paths (`C:\Program Files\nodejs\`).

For Cursor:

{
  "mcpServers": {
    "gorev": {
      "command": "npx",
      "args": [
        "@mehmetsenol/gorev-mcp-server@latest"
      ]
    }
  }
}

🔧 Traditional Installation (Automatic)

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/msenol/Gorev/main/install.sh | bash

# Specific version
curl -fsSL https://raw.githubusercontent.com/msenol/Gorev/main/install.sh | VERSION=v0.11.0 bash

🪟 Windows

# PowerShell (no admin rights required)
irm https://raw.githubusercontent.com/msenol/Gorev/main/install.ps1 | iex

# Or for specific version:
$env:VERSION="v0.11.0"; irm https://raw.githubusercontent.com/msenol/Gorev/main/install.ps1 | iex

💻 VS Code Extension (Optional)

Option 1: Gorev VS Code Extension (Recommended)

Install from VS Code Marketplace

code --install-extension mehmetsenol.gorev-vscode

🎮 Usage

AI Assistant Example Commands

"Create a new task: Write API documentation"
"List urgent tasks"
"Show tasks tagged with bug"
"Set Mobile App v2 project as active"
"Create new project for sprint planning"
"Mark task #5 as completed"
"Create new task from feature request template"
"Start watching project files"
"Enable automatic status transitions on file changes"
"Show watch list"
"Add git ignore rules to file watcher"

> 💡 Tip: These commands work with Claude, VS Code Copilot, Windsurf AI, Cursor, and other MCP-compatible AI assistants.

CLI Commands

# Daemon management (recommended)
gorev daemon --detach        # Start daemon in background
gorev daemon-status          # Check daemon status
gorev daemon-stop            # Stop running daemon

# Development/testing (foreground mode)
gorev serve                  # Normal mode
gorev serve --debug          # Debug mode
gorev serve --port 8080      # Different port

# Task operations
gorev task list              # List tasks
gorev task create            # Create new task
gorev task show          # Task details

# Project operations
gorev project list           # List projects
gorev project create         # Create new project

# Other
gorev version                # Version info
gorev help                 # Help

📚 Documentation

For detailed documentation, see the docs/ folder:

Getting Started

• 🚀 Quick Start Guide - Get up and running in 10 minutes
• 📦 Installation Guide - Platform-specific installation instructions
• 🆘 Troubleshooting Guide - Common issues and solutions
• 🔄 Migration Guide (v0.15→v0.16) - Upgrade from v0.15

Features

• 🌐 Web UI Guide - Embedded React interface documentation
• 🗂️ Multi-Workspace Support - Managing multiple projects
• 📋 Template System - Structured task creation
• 🤖 AI Context Management - AI assistant integration

Reference

• 🛠️ MCP Tools Reference - Complete reference for 24 optimized MCP tools (unified from 45)
• 🔧 MCP Configuration Examples - IDE setup guides
• 📖 Usage Guide - Detailed usage examples
• 🎨 VS Code Extension - Extension documentation

Development

• 🏗️ System Architecture - Technical details
• 💻 Contributing Guide - How to contribute
• 🗺️ Roadmap - Development roadmap and future plans
• 📚 Development History - Complete project history

AI Assistant Documentation

• 🌍 CLAUDE.en.md - English AI assistant guidance
• 🤖 CLAUDE.md - Turkish AI assistant guidance
• 📋 MCP Tools Reference - Detailed MCP tool documentation
• 📚 Development History - Complete project history

🏗 Architecture

Project Structure

gorev/
├── gorev-mcpserver/        # MCP Server (Go)
│   ├── cmd/gorev/         # CLI and server entry point
│   ├── internal/
│   │   ├── mcp/           # MCP protocol layer
│   │   └── gorev/        # Business logic
│   └── test/              # Integration tests
├── gorev-vscode/           # VS Code Extension (TypeScript)
│   ├── src/
│   │   ├── commands/      # VS Code commands
│   │   ├── providers/     # TreeView providers
│   │   └── mcp/           # MCP client
│   └── package.json       # Extension manifest
└── docs/                   # Project documentation

🧪 Development

Requirements

• Go 1.23+
• Make (optional)
• golangci-lint (for code quality)

Commands

# Download dependencies
make deps

# Run tests (90%+ overall coverage)
make test

# Coverage report
make test-coverage

# Lint check
make lint

# Build (all platforms)
make build-all

# Docker image
make docker-build

📊 Project Status

• Version: v0.17.0 🚀
• Test Coverage: 75%+ (Comprehensive test coverage with ongoing improvements)
• Go Version: 1.23+
• MCP SDK: mark3labs/mcp-go v0.6.0
• Database: SQLite (embedded)
• Security: Production-ready audit compliant
• Thread Safety: 100% race condition free

🤝 Community

• 📦 GitHub Releases
• 🐛 Issue Tracker
• 💬 Discussions
• 📖 Wiki

📄 License

This project is licensed under the MIT License.

🚨 Breaking Change: Template Requirement

Starting from v0.10.0, the `gorev_olustur` tool has been removed. All task creation must now use the template system for better structure and consistency.

Migration Guide

Before (v0.9.x and earlier):

Create a new task: Fix login bug

After (v0.10.0+):

Use bug-report template to create: Fix login bug

Available templates:

• `bug-report` - Bug reports and fixes
• `feature` - New features and enhancements
• `task` - General tasks and activities
• `meeting` - Meeting planning and notes
• `research` - Research and investigation tasks

For more details, see MCP Tools Documentation.