Journey

Universal Goal Engine, Local Web Portal & Model Context Protocol (MCP) Server

Journey is a local-first goal tracking and mastery engine with a Next.js web portal and a built-in MCP server. It manages skill trees, mastery roadmaps, and daily task priorities through a single JSON file (~/.journey/data/roadmap.json) accessible by both humans and AI agents in real time.

System Architecture

┌─────────────────────────────────────────────────────────┐
│                   Journey Web Portal                    │
│                (http://localhost:6161)                  │
│   • Home Overview          • Execution Dashboard        │
│   • Goal Tree Graph        • 24 Preset Themes           │
└────────────────────────────┬────────────────────────────┘
                             │ reads & writes
┌────────────────────────────▼────────────────────────────┐
│            ~/.journey/data/roadmap.json                 │
│        (User's Local Goal & Mastery Data)               │
└────────────────────────────▲────────────────────────────┘
                             │ MCP / Stdin-Stdout
┌────────────────────────────┴────────────────────────────┐
│             AI Assistants & MCP Clients                 │
│ (Claude Code, OpenCode, Hermes, Cursor, Windsurf, etc.) │
└─────────────────────────────────────────────────────────┘

Core Capabilities

Local-First & Private: Personal data remains stored locally at ~/.journey/data/roadmap.json. Requires no external databases, account creation, or cloud services.
Model Context Protocol (MCP): Native journey-mcp executable exposing JSON-RPC 2.0 tools (get_roadmap, add_goal, update_item_status) for seamless AI integration.
24 Theme Color Combos: Includes 24 harmonized color theme presets (Dracula, Nord, Gruvbox, Tokyo Night, Monokai, Rosé Pine, Synthwave, Catppuccin, Cyberpunk, and Clean Light/Dark) with automatic YIQ text contrast adjustment.
Algorithmic Execution Engine: Evaluates task priority, career ROI, and dependencies to synthesize daily focus items and surface blocked goals on the Dashboard.
Interactive Goal Graph: Visual node tree interface allowing direct inline node creation, deletion, status updates, and track filtering.
Density Scaling: Toggle between Comfortable and Compact layout densities for different display sizes.

Quick Start

1. Installation

Install Journey globally via npm:

npm install -g @ziuus/journey

Upgrading: To update an existing global installation:
npm install -g @ziuus/journey@latest

2. Launch Portal

Start the background web service:

journey

Navigate to http://localhost:6161. Journey automatically creates a starter roadmap file at ~/.journey/data/roadmap.json on initial launch if one does not exist.

Interface Guide

View	Path	Primary Purpose
Overview	`/`	Track-by-track accordion hierarchy, global progress statistics, search filtering.
Dashboard	`/dashboard`	Algorithmic focus recommendation engine, high-ROI target lists, dependency warning panels.
Goal Tree	`/tree`	Full-screen interactive DAG node graph view with live node editing tools.
Settings	`/settings`	Theme selector (24 presets), custom accent override, density mode, default landing view preferences.

Agent Configuration Guide (MCP Setup)

Journey supports any agent using the Model Context Protocol (MCP). Since different AI CLI tools and IDEs use different configuration formats, find your agent below for step-by-step setup instructions:

1. Claude Code (CLI)

Run the built-in MCP CLI command:

claude mcp add journey journey-mcp

Or with NPX (zero-install):

claude mcp add journey npx -y @ziuus/journey journey-mcp

2. OpenCode Interpreter

Run in your terminal:

opencode mcp add journey journey-mcp

Or add to ~/.config/opencode/mcp.json:

{
  "mcpServers": {
    "journey": {
      "command": "journey-mcp"
    }
  }
}

3. Hermes Agent

Run in terminal:

hermes mcp add journey journey-mcp

Or add to ~/.hermes/mcp.json:

{
  "mcpServers": {
    "journey": {
      "command": "journey-mcp"
    }
  }
}

4. Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "journey": {
      "command": "journey-mcp"
    }
  }
}

5. Cursor IDE

Open Cursor Settings → Features → MCP or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "journey": {
      "command": "journey-mcp"
    }
  }
}

6. Windsurf (Codeium)

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "journey": {
      "command": "journey-mcp"
    }
  }
}

7. Roo Code / Cline (VS Code)

Open Roo Code Settings → MCP Servers → Add New MCP Server or edit cline_mcp_settings.json:

{
  "mcpServers": {
    "journey": {
      "command": "journey-mcp"
    }
  }
}

8. Zed Editor

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "journey": {
      "command": "journey-mcp"
    }
  }
}

9. Goose CLI

Add to ~/.config/goose/config.yaml:

mcpServers:
  journey:
    command: journey-mcp

10. Continue.dev (VS Code & JetBrains)

Add to ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "journey",
      "command": "journey-mcp"
    }
  ]
}

11. Zero-Install Alternative (NPX)

If you prefer not to install globally, you can use npx in any MCP config:

{
  "mcpServers": {
    "journey": {
      "command": "npx",
      "args": ["-y", "@ziuus/journey", "journey-mcp"]
    }
  }
}

MCP Tools Reference

When connected, AI agents automatically discover and execute these 3 tools:

Tool	Input Parameters	Description
`get_roadmap`	None	Reads the user's complete roadmap and goal tree from `~/.journey/data/roadmap.json`.
`add_goal`	`layerId`, `title`, `goal`	Inserts a new goal into a specified roadmap layer.
`update_item_status`	`type`, `itemId`, `status`	Updates target item status (`pending` or `done`).

Direct File Reference (For Non-MCP Agents)

For agents without native MCP support (e.g. Gemini CLI, ChatGPT Web, custom scripts), simply inform your agent:

"My goal roadmap is stored at ~/.journey/data/roadmap.json. Read this file to track my active goals and progress."

Environment	Strategy
Gemini CLI	Reference `GEMINI.md` in your workspace context.
Claude Code	Include `AGENTS.md` at your project root.
Custom Agents	Read/write directly to `~/.journey/data/roadmap.json`.

CLI Command Reference

Command	Action
`journey`	Launches background portal process on port 6161
`journey dev`	Runs development portal in foreground on port 3000
`journey status`	Queries current background service state
`journey stop`	Terminates background portal service
`journey logs`	Displays real-time portal process logs
`journey-mcp`	Runs stdio Model Context Protocol server

Data Structure & Filesystem Layout

journey/
├── src/                    # Next.js 16 Web Portal Application
│   ├── app/                # Application routes (/ , /dashboard, /tree, /settings)
│   ├── components/         # Navigation bar, Footer, and SVG Logo components
│   ├── config/             # Theme metadata & default system configurations
│   ├── context/            # Global preference & theme context provider
│   └── lib/                # Roadmap normalizers & scoring algorithm
├── data/
│   └── roadmap.json        # Repository starter template (Do NOT write user data here)
├── scripts/
│   ├── journey-cli.js      # CLI service manager executable
│   └── mcp-server.js       # Model Context Protocol stdio server executable
└── ~/.journey/data/        # User storage location (roadmap.json)

Data Separation Policy:

User Roadmap: Saved strictly to ~/.journey/data/roadmap.json outside the source directory.

Starter Template: The repository file data/roadmap.json provides initial default schema structure for new installations.

License

MIT © ziuus

Name		Name	Last commit message	Last commit date
.omo		.omo
agent-skills/journey		agent-skills/journey
data		data
mcp		mcp
public		public
scripts		scripts
src-tauri		src-tauri
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
GEMINI.md		GEMINI.md
LEARN.md		LEARN.md
LICENSE		LICENSE
README.md		README.md
add_web3_roadmap.py		add_web3_roadmap.py
append_themes.py		append_themes.py
eslint.config.mjs		eslint.config.mjs
install.sh		install.sh
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
setup.sh		setup.sh
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

Journey

System Architecture

Core Capabilities

Quick Start

1. Installation

2. Launch Portal

Interface Guide

Agent Configuration Guide (MCP Setup)

1. Claude Code (CLI)

2. OpenCode Interpreter

3. Hermes Agent

4. Claude Desktop

5. Cursor IDE

6. Windsurf (Codeium)

7. Roo Code / Cline (VS Code)

8. Zed Editor

9. Goose CLI

10. Continue.dev (VS Code & JetBrains)

11. Zero-Install Alternative (NPX)

MCP Tools Reference

Direct File Reference (For Non-MCP Agents)

CLI Command Reference

Data Structure & Filesystem Layout

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Journey

System Architecture

Core Capabilities

Quick Start

1. Installation

2. Launch Portal

Interface Guide

Agent Configuration Guide (MCP Setup)

1. Claude Code (CLI)

2. OpenCode Interpreter

3. Hermes Agent

4. Claude Desktop

5. Cursor IDE

6. Windsurf (Codeium)

7. Roo Code / Cline (VS Code)

8. Zed Editor

9. Goose CLI

10. Continue.dev (VS Code & JetBrains)

11. Zero-Install Alternative (NPX)

MCP Tools Reference

Direct File Reference (For Non-MCP Agents)

CLI Command Reference

Data Structure & Filesystem Layout

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages