Gorev

🚀 Gorev

Gorev is a modern task management system with Turkish support, designed specifically for MCP-compatible AI assistants such as Claude, VS Code, Windsurf, and Cursor. It combines project management, task tracking, and organization needs with the power of AI assistants to significantly boost productivity.

🚀 Quick Start

Gorev is a powerful Model Context Protocol (MCP) server written in Go. It provides task management capabilities to all MCP-compatible AI editors, such as Claude Desktop, VS Code, Windsurf, Cursor, Zed, etc.

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

Quick Start Commands

# Start daemon in background
gorev daemon --detach

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

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

✨ Features

📝 Task Management

• Smart task creation: Use natural language commands to create tasks effortlessly.
• Markdown support: Format task descriptions richly with Markdown.
• Status management: Track tasks through different statuses: Pending → In Progress → Completed.
• Priority levels: Set task priorities as Low, Medium, or High.
• Flexible editing: Update all task properties as needed.

📁 Project Organization

• Hierarchical structure: Group tasks under projects for better organization.
• Active project system: Perform quick operations with the default project.
• Project-based reporting: Get detailed statistics based on projects.
• Multi-project support: Create an unlimited number of projects.

🔗 Advanced Features

• 📅 Due date tracking: Manage deadlines and filter urgent tasks.
• 🏷️ Tagging system: Categorize tasks with multiple tags.
• 🔄 Task dependencies: Automate inter-task operations.
• 📋 Ready-made templates: Use templates for bug reports, feature requests, etc.
• 🔍 Advanced filtering: Query tasks based on status, tag, and date.
• 🌳 Subtask hierarchy: Build task trees with unlimited depth.
• 📊 Progress tracking: Monitor subtask completion percentages in parent tasks.
• 📁 File System Watcher: Monitor file changes and automatically update task statuses.
• 🔔 Automatic Status Updates: Automatically transition tasks from "pending" to "in_progress" on file changes.
• ⚙️ Configuration Management: Customize ignore patterns and watch rules.

🤖 AI Integration

• Natural language processing: Manage tasks by communicating with AI assistants.
• Multi-editor support: Works with Claude, VS Code, Windsurf, Cursor, Zed.
• Contextual understanding: Interpret commands smartly.
• MCP standard: Compatible with all MCP-compatible tools.

🎨 VS Code Extension Features (Optional)

• Bilingual Support: Enjoy a Turkish and English interface (v0.5.0+). 🌍
• TreeView Panels: View task, project, and template lists.
• Visual Interface: Have a click-and-use experience.
• Status Bar: Get real-time status information.
• Command Palette: Access features quickly (Ctrl+Shift+G).
• Color Coding: Distinguish tasks by priority visually.
• Context Menus: Perform operations with right-click.
• Automatic Language Detection: Set the UI language based on VS Code settings.
• Download from Marketplace 🚀

🌐 Web UI Features (NEW! v0.16.0)

• Modern Browser Interface: Use it in any browser without an IDE.
• Task Cards: Visualize tasks with rich metadata.
• Subtask Hierarchy: Expand and collapse nested tasks.
• Dependency Badges: See task dependencies visually.
• Project Organization: Navigate projects in the sidebar with task counts.
• Template-Based Creation: Create structured tasks using wizards.
• Real-time Updates: Synchronize tasks automatically with React Query.
• Responsive Design: Works on desktop and mobile devices.
• 🌍 Language Switcher: Toggle between Turkish and English, synchronized with the MCP server.
• Quick Actions: Edit, delete, and update task statuses easily.
• REST API Backend: Powered by a high-performance Fiber-based API server.
• 🚀 No Installation Required: Just run npx @mehmetsenol/gorev-mcp-server serve to start.
• Embedded UI: Bundled in the Go binary, no separate setup needed.
• Access: http://localhost:5082 (default port)

📦 Installation

🚀 NPM Quick Setup (Recommended!)

⚠️ Important Note

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:
   • Download the LTS version from Node.js website.
   • Check the "Add to PATH" option during installation.
   • Restart your computer after installation.
3. Install NPX separately (if needed):

   npm install -g npx
   

4. Check PATH:

   echo %PATH%
   

   The output should include Node.js paths (C:\Program Files\nodejs\).

🔧 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 Examples

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"

💡 Usage 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 <id>         # 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: Documentation for the embedded React interface.
• 🗂️ 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.

🔧 Technical Details

Three-Module Architecture

1. gorev-mcpserver - MCP server written in Go (core component)
   • Embedded Web UI 🌐 - React interface embedded in binary (NEW! v0.16.0)
   • REST API server (Fiber framework)
   • MCP protocol support
2. gorev-vscode - VS Code extension (optional visual interface)
3. gorev-web - React + TypeScript source code (development)

Daemon Architecture (v0.16.0+)

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

Core Features:

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

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<br/>~/.gorev-daemon/.lock]

        subgraph "Protocol Layers"
            MCP[MCP Proxy<br/>stdio]
            REST[REST API<br/>Fiber - 23 endpoints]
            WS[WebSocket<br/>Real-time events]
        end

        Handler[MCP Handlers<br/>24 Unified Tools]

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

        WebUI[Embedded Web UI<br/>React + 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 the 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, it checks if the daemon is running (reads the lock file).
2. Starts the daemon if it's not running.
3. Connects to the REST API for all operations.
4. Optionally shuts down the daemon on deactivation (if the 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 are 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 is 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 are now visible:

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

Validation: A 100% success rate was confirmed by the Kilocode AI comprehensive test report.

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

• NPM Binary Update Fix: Fixed a 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 are now always downloaded from GitHub).
  • All users now get the latest features (REST API, Web UI, VS Code auto-start).
• VS Code Auto-Start: The extension now automatically detects and starts the daemon.
  • No manual commands are required - the daemon auto-starts via lock file detection.
  • Checks if the daemon is running (~/.gorev-daemon/.lock), starts it 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: A modern React interface is built into the Go binary.
• Instant Access: Automatically available at http://localhost:5082.
• Full Features: Supports tasks, projects, templates, subtasks, and dependencies.
• Language Sync: A Turkish/English switcher is synchronized with the 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 the Web UI.
• Auto-Detection: Automatically detects the .gorev/ directory in the current folder.
• SHA256 IDs: Secure workspace identification.
• VS Code Integration: The extension auto-registers the workspace on activation.

🔌 REST API Migration

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

🏷️ Template Aliases

• Quick Commands: Use bug, feature, research instead of template IDs.
• Consistency: The same aliases are used across all workspaces.
• No More UUID Hunting: Human-readable template identifiers.
• Documentation: A full guide is available 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.

📄 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.