meow-tool

Multi-provider LLM router with OpenAI/Anthropic compatible API, smart mode routing, SSE streaming, session persistence, token analytics, and unified Agent/Skill/MCP orchestration.

meow-tool is a self-hosted LLM gateway that unifies multi-vendor model configuration behind both OpenAI and Anthropic compatible APIs. Ships with a bundled Web UI for managing everything visually; an optional terminal TUI (meow cli) is available for keyboard-driven workflows.

Features

• Dual protocol -- OpenAI + Anthropic compatible APIs, any client works
• Multi-vendor routing -- OpenAI / Anthropic / vLLM / any OpenAI-compatible upstream
• Normal / Making modes -- smart routing: classifier evaluates query complexity, routes to the right model tier ( low / medium / high)
• SSE streaming -- full streaming with reasoning chain pass-through
• Sessions -- persistent chat history, resumable across CLI/Web invocations
• Token analytics -- daily / monthly / yearly usage aggregation
• Agent / Skill / MCP orchestration -- unified tool calling with persona prompts, skill injection, and MCP tool routing
• System ops -- built-in file read/write + command execution (sandboxed)
• SQLite storage -- zero-config, all data in ~/.meowtool/meow.db
• OSS sync -- optional S3-compatible backup (startup pull + shutdown push)

Install

# global install (recommended)
npm install -g meow-tool

# or use directly without install
npx meow-tool start

The postinstall hook creates ~/.meowtool/ (the data home). Override with MEOW_HOME env var if you want a different location.

Quick Start

# 1. start backend API server on :4399 (Web UI is served from the same port)
meow start

# 2. open Web UI in browser
meow web

# 3. check status
meow status

# 4. stop background services
meow stop

For most users meow start + Web UI plus any OpenAI/Anthropic compatible client (Cherry Studio, Open WebUI, etc.) is enough. The terminal TUI (meow cli) is optional for those who prefer a keyboard-driven workflow.

CLI Commands

| Command | Description | |---------------|--------------------------------------------------------------| | meow start | Start backend in background (detached, PID + log file) | | meow stop | Stop background services (graceful shutdown with OSS upload) | | meow web | Open browser to Web UI (http://localhost:4399) | | meow status | Check if backend is running | | meow cli | (optional) Start terminal TUI chat (new session each time) |

API Endpoints

Once running, point any OpenAI/Anthropic compatible client at:

• OpenAI compatible: http://localhost:4399/v1/chat/completions
• Anthropic compatible: http://localhost:4399/v1/messages
• Models list: http://localhost:4399/v1/models

Chat Request (OpenAI compatible)

curl http://localhost:4399/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

Chat Request (Anthropic compatible)

curl http://localhost:4399/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-3-opus",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

Smart Routing

Use virtual model names to enable smart routing:

# Normal mode: always routes to the configured default model
{"model": "normal", "messages": [...]}

# Making mode: classifier evaluates complexity, routes to low/medium/high tier
{"model": "making", "messages": [...]}

# Auto mode: alias for making
{"model": "auto", "messages": [...]}

Orchestration

Add session_id, agent_id, or meow_tools to enable full orchestration (MCP tools, skill injection, agent persona):

# Use an agent with session history
{
  "model": "normal",
  "session_id": "your-session-uuid",
  "agent_id": "my-agent",
  "messages": [{"role": "user", "content": "Help me write code"}]
}

Without these fields, requests are pure-routed (no MCP/Skill injection).

REST API Overview

| Method | Path | Description | |-------------------------|-----------------------------------------|------------------------------------------| | GET | /api | Server status + available endpoints | | GET | /v1/models | List all models (real + virtual aliases) | | POST | /v1/chat/completions | OpenAI compatible chat | | POST | /v1/messages | Anthropic compatible chat | | GET/PUT | /v1/config/models | Read/write model configurations | | GET/PUT | /v1/config/router | Read/write router configurations | | GET/PUT | /v1/config/mcps | Read/write MCP configurations | | GET | /v1/mcps/status | MCP connection status | | GET | /v1/mcps/tools | Aggregated tool list | | POST | /v1/mcps/tools/:name | Manually invoke a tool | | GET/POST/PUT/DELETE | /v1/config/skills | CRUD skills | | GET/PUT/DELETE | /v1/config/skills/:id/files/:filename | CRUD skill files | | GET/POST/PUT/DELETE | /v1/config/agents | CRUD agents | | POST/GET/PATCH/DELETE | /v1/sessions | Session management | | GET | /v1/analytics/tokens | Token usage aggregation | | GET | /v1/analytics/models | Models with usage records | | GET | /v1/analytics/records | Recent raw usage records | | GET/PUT | /v1/oss/config | Read/write OSS sync config | | POST | /v1/oss/push | Manual upload to OSS | | POST | /v1/oss/pull | Manual pull from OSS |

Configuration

All config lives in ~/.meowtool/meow.db (SQLite). Edit via REST API or Web UI.

Model Configuration

# read current models
curl http://localhost:4399/v1/config/models

# add a model
curl -X PUT http://localhost:4399/v1/config/models \
  -H 'Content-Type: application/json' \
  -d '{
    "gpt-4": {
      "type": "openai-chat",
      "url": "https://api.openai.com/v1/chat/completions",
      "upstreamModel": "gpt-4",
      "headers": { "Authorization": "Bearer sk-..." },
      "maxTokens": 8192
    }
  }'

Model fields:

| Field | Type | Default | Description | |--------------------|-------------------------------------|----------|---------------------------------------| | type | "openai-chat" \| "anthropic-chat" | required | Upstream protocol | | url | string | required | Upstream API endpoint | | upstreamModel | string | required | Real model name sent to upstream | | headers | object | {} | Custom request headers (auth, etc.) | | body | object | {} | Fields merged into request body | | maxTokens | number | 4096 | Max output tokens | | includeReasoning | boolean | false | Pass through reasoning/thinking chain | | upstreamStream | boolean | true | Force streaming to upstream | | timeoutMs | number | 600000 | Upstream request timeout (ms) |

Router Configuration

# read router config
curl http://localhost:4399/v1/config/router

# configure smart routing
curl -X PUT http://localhost:4399/v1/config/router \
  -H 'Content-Type: application/json' \
  -d '{
    "defaultModel": "gpt-4",
    "making": {
      "classifierModel": "gpt-3.5-turbo",
      "intensity": {
        "low": "gpt-3.5-turbo",
        "medium": "gpt-4",
        "high": "gpt-4-turbo"
      }
    }
  }'

• Normal mode (model: "normal"): always routes to defaultModel
• Making mode (model: "making" or "auto"): classifier evaluates query complexity, routes to the corresponding tier

MCP Configuration

MCP (Model Context Protocol) tools are external sub-processes or remote HTTP services. Configure via API or Web UI:

curl -X PUT http://localhost:4399/v1/config/mcps \
  -H 'Content-Type: application/json' \
  -d '[{
    "id": "my-mcp",
    "name": "My MCP Server",
    "enabled": true,
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "my-mcp-server"],
    "timeoutMs": 60000
  }]'

Skills

Skills are pure markdown files injected into the system prompt. Create via API or Web UI, then edit the .md files:

# create a skill
curl -X POST http://localhost:4399/v1/config/skills \
  -H 'Content-Type: application/json' \
  -d '{"id": "coding", "name": "Coding Assistant", "enabled": true}'

# edit skill content
curl -X PUT http://localhost:4399/v1/config/skills/coding/files/SKILL.md \
  -H 'Content-Type: application/json' \
  -d '{"content": "You are an expert programmer..."}'

Agents

Agents are structured presets that override model, tools, and system prompt:

curl -X POST http://localhost:4399/v1/config/agents \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "coder",
    "name": "Code Agent",
    "enabled": true,
    "model": "gpt-4",
    "systemPrompt": "You are a senior developer...",
    "tools": ["system__read_file", "system__write_file"]
  }'

Activate an agent by adding "agent_id": "coder" to your chat request body.

OSS Sync (optional)

Sync meow.db + skills/ to any S3-compatible service (Aliyun / MinIO / Cloudflare R2 / AWS S3). On startup the data is pulled from OSS (overriding local); on shutdown the local data is pushed back.

Create ~/.meowtool/oss.json:

{
  "enabled": true,
  "endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
  "region": "oss-cn-hangzhou",
  "accessKeyId": "your-key-id",
  "accessKeySecret": "your-secret",
  "bucket": "meow-backup",
  "prefix": "meow/",
  "forcePathStyle": false
}

| Field | Description | |------------------|----------------------------------------------------------------------| | endpoint | S3-compatible endpoint (Aliyun / MinIO required; AWS S3 leave empty) | | forcePathStyle | true for MinIO self-hosted; false for Aliyun / AWS | | prefix | Object key prefix for multi-instance isolation on the same bucket |

The oss.json file itself is not synced (keys stay local only). When enabled is false or the file is missing, sync is silently skipped.

Manual sync via API:

# upload local data to OSS
curl -X POST http://localhost:4399/v1/oss/push

# pull skills from OSS (DB pulled on startup only)
curl -X POST http://localhost:4399/v1/oss/pull

Web UI

The Web UI is bundled with the npm package and served from the same backend port (http://localhost:4399). It provides a graphical interface for managing models, router, MCPs, skills, agents, sessions, token analytics, and OSS sync.

meow start && meow web

No extra install step needed -- meow start serves both the API and the Web UI.

Terminal TUI (optional)

The terminal TUI (meow cli) is an optional keyboard-driven chat client that connects to the same backend over HTTP. It is bundled in the same meow binary -- no extra install or project clone needed. It supports multi-line editing with Emacs keybindings, history navigation, and paced streaming output. Useful when you prefer the terminal or want a lightweight chat without a browser.

meow start   # ensure backend is running
meow cli     # start a new TUI chat session (bundled, same binary)

Environment Variables

| Variable | Default | Description | |-------------|---------------|---------------------------------------------| | MEOW_HOME | ~/.meowtool | Data directory (DB, skills, logs, PID file) | | PORT | 4399 | Backend server port |

Data Directory

All runtime data lives in ~/.meowtool/:

~/.meowtool/
  meow.db            # SQLite main database
  skills/            # Skill markdown files
  logs/              # Backend logs (when running in background)
  oss.json           # OSS sync configuration (optional)
  .meow-pids.json    # Background process PID file

Requirements

• Node.js >= 20
• Windows / macOS / Linux

License

MIT (c) naclnezn