Quick Start Guide

October 7, 2025 · View on GitHub

Version: v0.16.0 Est. Time: 10 minutes Last Updated: October 5, 2025

Get up and running with Gorev in minutes!

What is Gorev

Gorev is a task management system designed for AI assistants (Claude, Copilot, etc.) with:

  • MCP Protocol: 41 tools for AI-powered task management
  • Embedded Web UI: Browser-based interface at http://localhost:5082
  • VS Code Extension: Rich IDE integration (optional)
  • Multi-Workspace: Isolated databases per project
  • Template System: 6 default templates for structured tasks

Installation (2 minutes)

# Use directly with NPX (no installation)
npx @mehmetsenol/gorev-mcp-server@latest

Or install globally:

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

Option 2: Download Binary

Linux/macOS:

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

Windows PowerShell:

irm https://raw.githubusercontent.com/msenol/Gorev/main/install.ps1 | iex

First Steps (3 minutes)

1. Initialize Workspace

cd /path/to/your/project
npx @mehmetsenol/gorev-mcp-server init

Output:

✓ Created .gorev/ directory
✓ Initialized database: gorev.db
✓ Workspace registered: my-project

2. Start Server

npx @mehmetsenol/gorev-mcp-server@latest

Output:

🚀 Gorev MCP Server v0.16.0
📦 Web UI: http://localhost:5082
🔌 MCP: Listening on stdio
✅ Ready for connections

3. Access Web UI

Open browser: http://localhost:5082

You'll see:

  • Workspace switcher (top-right)
  • Project sidebar (left)
  • Task list (center)
  • "New Task" button

Create Your First Task (2 minutes)

Via Web UI

  1. Click "New Task" button
  2. Select "bug" template
  3. Fill in fields:
    • Title: Fix login button
    • Module: auth
    • Environment: production
    • Steps: 1. Click login\n2. Button doesn't respond
    • Expected: User logs in
    • Actual: Nothing happens
    • Priority: high
  4. Click "Create Task"

✅ Task created and appears in task list!

Via CLI

npx @mehmetsenol/gorev-mcp-server task create \
  --template bug \
  --field baslik="Fix login button" \
  --field modul="auth" \
  --field ortam="production" \
  --field oncelik="yuksek"

Configure AI Assistant (3 minutes)

Claude Desktop

File: ~/.config/Claude/claude_desktop_config.json (Linux/macOS) File: %APPDATA%\Claude\claude_desktop_config.json (Windows)

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

Restart Claude Desktop

Test Connection

In Claude:

List all my tasks

Claude should respond with your task list!

VS Code (Kilo Code Extension)

File: .kilocode/mcp.json in workspace root

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

Reload VS Code window

Common Tasks

Create Project

Web UI: Sidebar → "New Project" → Enter name

CLI:

npx @mehmetsenol/gorev-mcp-server project create --name "My Project"

AI Assistant:

Create a new project called "Backend API"

List Tasks

Web UI: View in center panel (auto-updates)

CLI:

npx @mehmetsenol/gorev-mcp-server task list

AI Assistant:

Show me all my tasks

Update Task Status

Web UI: Click task → Change status dropdown

CLI:

npx @mehmetsenol/gorev-mcp-server task update --id <ID> --status completed

AI Assistant:

Mark the login button task as completed

Switch Workspace

Web UI: Top-right dropdown → Select workspace

CLI: Change directory and run commands

cd /path/to/other/project
npx @mehmetsenol/gorev-mcp-server task list

Next Steps

Learn Features

Advanced Setup

Troubleshooting

Quick Reference

Template Aliases

AliasUse For
bugSoftware bugs
featureNew features
researchInvestigation
refactorCode improvement
testTest writing
docDocumentation

CLI Commands

# Server
npx @mehmetsenol/gorev-mcp-server@latest          # Start server
npx @mehmetsenol/gorev-mcp-server --version      # Version info

# Workspace
npx @mehmetsenol/gorev-mcp-server init           # Initialize
npx @mehmetsenol/gorev-mcp-server workspace list # List workspaces

# Tasks
npx @mehmetsenol/gorev-mcp-server task list      # List tasks
npx @mehmetsenol/gorev-mcp-server task create    # Create task
npx @mehmetsenol/gorev-mcp-server task show <ID> # View details

# Projects
npx @mehmetsenol/gorev-mcp-server project list   # List projects
npx @mehmetsenol/gorev-mcp-server project create # Create project

Default Ports

Environment Variables

GOREV_LANG=en              # Interface language (en/tr)
GOREV_API_PORT=5082        # Web UI port
GOREV_DB_PATH=/custom/path # Custom database location

Tips & Tricks

1. Use Template Aliases

Instead of remembering UUIDs:

# ✅ Good
npx @mehmetsenol/gorev-mcp-server task create --template bug

# ❌ Tedious
npx @mehmetsenol/gorev-mcp-server task create --template 39f28dbd-10f3-454c-8b35-52ae6b7ea391

2. Workspace Auto-Detection

Don't specify GOREV_DB_PATH - let Gorev find .gorev/ automatically:

cd /projects/project-a
npx @mehmetsenol/gorev-mcp-server task list  # Uses project-a database

cd /projects/project-b
npx @mehmetsenol/gorev-mcp-server task list  # Uses project-b database

3. AI Assistant Prompts

Use natural language:

"Create a bug task for login issue"
"Show me high priority tasks"
"Mark authentication task as in progress"
"What should I work on next?"

4. Web UI Keyboard Shortcuts

  • N: New task
  • Ctrl+K: Search tasks
  • Escape: Close modals
  • Ctrl+S: Save task (in edit mode)

Getting Help

Documentation

Community

Report Bugs

Open issue with:

  • Gorev version (npx @mehmetsenol/gorev-mcp-server --version)
  • Error messages
  • Steps to reproduce
  • Expected vs. actual behavior

Congratulations! 🎉 You're ready to use Gorev for AI-powered task management!

For detailed documentation, see the guides directory.