mewkit

CLI for MeowKit — scaffold, upgrade, and manage your AI agent toolkit.

Install

npx mewkit init           # New project or update existing
npx mewkit <command>      # Runtime commands

Commands

| Command | Description | | ------------------- | ----------------------------------------------------------------- | | meowkit init | Scaffold new project or update existing (--dry-run, --force, --beta) | | meowkit upgrade | Update to latest version (--check, --beta, --list) | | meowkit doctor | Diagnose environment (Node.js, Python, Git, .claude/ structure) | | meowkit setup | Guided configuration (Python venv, MCP, .env, .gitignore) | | meowkit validate | Verify .claude/ structure integrity | | meowkit budget | Token usage and cost tracking (--monthly) | | meowkit memory | View/manage cross-session memory (--show, --stats, --clear) | | meowkit status | Print version, channel, and config | | meowkit task new | Create structured task file from template | | meowkit task list | List active tasks with status | | meowkit orchviz | Live web visualizer for the active Claude Code session |

Usage

# Scaffold or update a MeowKit project
npx mewkit init                 # Interactive version selection
npx mewkit init --beta          # Use beta channel
npx mewkit init --dry-run       # Preview changes without writing
npx mewkit init --force         # Overwrite all files (bypass user modification checks)

# Upgrade MeowKit
npx mewkit upgrade              # Latest stable
npx mewkit upgrade --beta       # Latest beta
npx mewkit upgrade --check      # Check without installing
npx mewkit upgrade --list       # Show all available versions

# Post-install setup
npx mewkit setup

# Check environment
npx mewkit doctor

# View token costs
npx mewkit budget --monthly

# Manage memory
npx mewkit memory --show        # Display lessons learned
npx mewkit memory --clear       # Reset memory

Visualizer (meowkit orchviz)

Live web visualizer for the active Claude Code session. Tails the JSONL transcript at ~/.claude/projects/<encoded-cwd>/<session>.jsonl, parses it into structured AgentEvents, and serves them at http://127.0.0.1:<port>/ as a Canvas2D + d3-force interactive graph plus a live transcript panel and meowkit-specific overlays (Gate state, model tier, today's tokens, phase).

# Default: random port, auto-open browser
npx mewkit orchviz

# Custom flags
npx mewkit orchviz --port 3001       # fixed port (0 = random)
npx mewkit orchviz --no-open         # don't auto-launch browser
npx mewkit orchviz --session <uuid>  # pin to a single session id
npx mewkit orchviz --workspace .     # override watched workspace (default: cwd)
npx mewkit orchviz --verbose         # print sanitized AgentEvents to stderr
npx mewkit orchviz --log             # persist to .claude/logs/orchviz-<sid>.md
npx mewkit orchviz --log /tmp/run.md # custom path (must end .md)

Security: server binds 127.0.0.1 only; Host-header guarded against DNS rebinding; SSE frames sanitized (ANSI strip + strict-prefix secret scrub on sk-…, ghp_…, AKIA…, PEM blocks); path traversal blocked.

Limitations (v1): simplified canvas renderer (no bloom / detail panels / multi-session tabs); v1.1 ports the full agent-flow visualizer. Ported (in part) from patoles/agent-flow under the Apache-2.0 license — see NOTICE.

orchviz API Endpoints (v1.2)

The orchviz server exposes these HTTP endpoints on http://127.0.0.1:<port>:

GET /api/plans — list non-archived plans sorted by mtime (newest first):

curl http://127.0.0.1:3001/api/plans
# { "plans": [{ "slug": "260501-my-plan", "title": "...", "status": "draft", ... }] }

GET /api/plan?slug=<slug> — full plan state with per-phase ETags:

curl "http://127.0.0.1:3001/api/plan?slug=260501-my-plan"
# { "plan": { ... }, "phaseEtags": { "1": "<hex64>", "2": "<hex64>" }, "readonly": true }
# Omit ?slug= to get the most-recently-modified plan.

Read-only by default. The visualizer is a viewer, not an editor — graph, plan tree, and todos all render read-only. The hamburger drawer browses the plan tree (plan → phase → todo) without exposing edit affordances. To opt into write mode (legacy todo-toggle endpoint), launch with MEOWKIT_ORCHVIZ_WRITABLE=1. The legacy MEOWKIT_ORCHVIZ_READONLY=0 flag also opts in for backwards compatibility; MEOWKIT_ORCHVIZ_READONLY=1 forces read-only as a defensive lock.

POST /api/plan/todo — toggle a todo checkbox (write mode only):

# Default (no env): returns 405 { "error": "readonly" }
MEOWKIT_ORCHVIZ_WRITABLE=1 npx mewkit orchviz   # opt in to write mode

curl -X POST http://127.0.0.1:3001/api/plan/todo \
  -H "Content-Type: application/json" \
  -H "Origin: http://127.0.0.1:3001" \
  -d '{"slug":"260501-my-plan","phase":1,"todoIdx":0,"checked":true,"etag":"<hex64>"}'
# 200: { "ok": true, "changed": true, "etag": "<new-hex64>" }
# 409: { "error": "stale", "currentEtag": "<latest-hex64>" }  → re-fetch and retry
# 403: Origin header missing or not in allowlist
# 405: server is in read-only mode (the default)

Origin requirement: POST requests must include Origin: http://127.0.0.1:<port> or Origin: http://localhost:<port>. This prevents cross-origin writes from browser tabs served by other origins.

Related

• GitHub

License

MIT