🚀 Gorev
⚠️ WARNING: HEAVY DEVELOPMENT ⚠️
This project is currently under active development. Breaking changes, API modifications, and feature updates may occur frequently. Use with caution in production environments.
Last Updated: November 28, 2025 | Version: v0.17.0
🎉 NEW in v0.17.0: MCP tool parameter transformation fixes + 100% test success! See What's New
Modern task management system with Turkish support, designed for MCP-compatible AI assistants (Claude, VS Code, Windsurf, Cursor)
Features • Installation • Usage • Documentation • Contributing
🎯 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
- 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
- gorev-vscode - VS Code extension (optional visual interface)
- 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/healthendpoint - 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<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/.lockcontains 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:
- On activation, checks if daemon is running (reads lock file)
- Starts daemon if not running
- Connects to REST API for all operations
- 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:
updateoperation: Properly transforms{ids: [], data: {}}→{updates: [{id, ...fields}]}transitionoperation: Accepts bothstatusandyeni_durumparameter names for flexibilitytagoperation: Accepts bothoperationandtag_operationparameter 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
omitemptyfrom 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 serveand 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,researchinstead 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 servefor 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:
-
Check if Node.js is installed:
node --version npm --version npx --version -
Install Node.js:
- Download LTS version from Node.js website
- Check "Add to PATH" option during installation
- Restart your computer after installation
-
Install NPX separately (if needed):
npm install -g npx -
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 <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 - 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 fixesfeature- New features and enhancementstask- General tasks and activitiesmeeting- Meeting planning and notesresearch- Research and investigation tasks
For more details, see MCP Tools Documentation.
Made with ❤️ by msenol
📚 Documentation enhanced by Claude (Anthropic) - Your AI pair programming assistant