meow-tool

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)
meow version	Print the current version (reads package.json)

meow version also accepts aliases: meow -v, meow -version, meow --version. Works in both dev (npm start) and packaged (npm i -g meow-tool) modes.

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 (url can be a base URL — suffix is auto-appended based on `type`)
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",
      "upstreamModel": "gpt-4",
      "headers": { "Authorization": "Bearer sk-..." },
      "maxTokens": 8192
    }
  }'

URL auto-suffix: When fullUrl is false (default for new models), the suffix is auto-appended based on type:

• openai-chat → /chat/completions (e.g. https://api.openai.com/v1 → .../v1/chat/completions)
• anthropic-chat → /v1/messages (e.g. https://api.anthropic.com → .../v1/messages, or https://api.deepseek.com/anthropic → .../anthropic/v1/messages)

If the URL already ends with the suffix (ignoring query/hash), it is not appended again. Set fullUrl: true to use the URL as-is (for Azure OpenAI or custom reverse proxies with non-standard paths).

Model fields:

Field	Type	Default	Description
type	"openai-chat" | "anthropic-chat"	required	Upstream protocol
url	string	required	Upstream API endpoint (base URL if fullUrl=false)
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)
anthropicVersion	string	2023-06-01	Anthropic API version header (anthropic-chat only)
fullUrl	boolean	false	If true, use url as-is (no auto-suffix). Default true for existing models migrated from v1 schema (backward compatible)

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