What this package is

@moxxy/cli is the published moxxy binary. It bundles the framework runtime, every built-in mode, every built-in provider, every built-in plugin, the Ink TUI channel, MCP support, the scheduler, webhooks, and the OS service installer into a single executable.

Install this if you want to use moxxy. If you want to author plugins, depend on @moxxy/sdk instead.

What you get out of the box

• A complete agent stack with Anthropic, OpenAI, and ChatGPT (OAuth) providers.
• Three loop modes: default (Claude-Code-style ReAct loop), goal (autonomous auto-approve loop), and research (parallel-subagent fan-out + synthesis).
• Built-in tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch, computer-control (macOS), and browser-session (Playwright, optional).
• Multi-channel by design: TUI, Telegram, HTTP, web, cron, and webhooks. One session can drive several surfaces at once.
• Voice input on any audio-capable channel through @moxxy/plugin-stt-whisper.
• An encrypted vault (AES-256-GCM at rest) so secrets in config are referenced as ${vault:KEY} and never written in plaintext.
• A long-term memory subsystem with a journal and vector recall. TF-IDF ships built-in. Swap to OpenAI embeddings via @moxxy/plugin-embeddings-openai.
• A permission resolver that gates every tool call and learns allow-always rules per tool.
• Opt-in capability isolation. Tools declare what they need and an isolator enforces it. inproc ships built-in. worker, subprocess, wasm, and Docker isolators drop in behind the same interface.
• A scheduler for cron expressions and one-shot ISO timestamps.
• A webhook listener with HMAC verification, header and JSON-path filters, and a cloudflared or ngrok tunnel helper.
• An OS service installer for launchd (macOS) and systemd (Linux), or a single serve --background process that runs every channel together.

Installation

npm install -g @moxxy/cli

Or run it without installing:

npx @moxxy/cli init

Requirements: Node.js 20.19 or later. Use an API key for Anthropic/OpenAI, sign into ChatGPT with moxxy login openai-codex, or reuse an authenticated Claude Code Pro/Max subscription as described below.

Claude Code (Pro/Max subscription, no API key)

1. Install the official Claude CLI so claude is on PATH (or set CLAUDE_CODE_EXECUTABLE=/absolute/path/to/claude).
2. Run claude auth login or moxxy login claude-code, then confirm with claude auth status and moxxy doctor.
3. Select claude-code in moxxy init. It defaults to claude-sonnet-5; override per run with --model, or persist plugins.provider.items.claude-code.model.

The default transport disables Claude's internal tools (except WebSearch). moxxy's own tools still work: they are described to the model in the prompt, and each call it makes runs through moxxy's permission resolver like with any other provider. To opt into an isolated coding task, configure the provider item explicitly:

plugins:
  provider:
    default: claude-code
    items:
      claude-code:
        model: claude-sonnet-5
        config:
          mode: native-tools
          permissionMode: acceptEdits
          allowedTools: [Read, Write, Edit]

allowedTools and permissionMode are forwarded to and enforced by Claude CLI. Moxxy's permission resolver, --allow-tools, and isolators govern moxxy-registered tools only; they do not govern Claude's internal native tools. Claude also owns its login files—moxxy neither reads nor stores subscription credentials in its vault.

Desktop and interactive CLI setup can start sign-in. Headless runners/services generally cannot complete browser or TTY authentication: authenticate first as the same OS account that runs the service, make claude available in that account's service PATH (or set the executable path), and restart it. Recovery commands are claude auth status, claude auth login, moxxy login claude-code, and moxxy doctor.

Contributors with an authenticated subscription can run the opt-in, no-API-key smoke gate after pnpm build:

node scripts/e2e-claude-cli-live.mjs
# optional: MOXXY_CLAUDE_E2E_MODEL=claude-opus-5 node scripts/e2e-claude-cli-live.mjs

It skips clearly when claude is missing or signed out, streams a real text prompt, and performs its native-tool assertion only inside a generated temporary git repository.

Quickstart

moxxy init      # interactive: choose provider, paste API key (stored in the vault)
moxxy           # launch the interactive TUI

One-shot from the command line:

moxxy -p "summarize the README in three bullets"

Resume a previous conversation:

moxxy resume

moxxy --help lists every command. moxxy <command> --help shows per-command details.

Commands

The CLI groups commands the same way moxxy --help does.

Setup

| Command | What it does | |---|---| | moxxy init | Interactive first-time setup. Picks a provider, captures the key, writes it into the vault. | | moxxy login <provider> | OAuth sign-in for providers that do not use API keys (for example openai-codex). | | moxxy login status | Show stored OAuth credentials. | | moxxy login logout <provider> | Remove stored OAuth credentials. | | moxxy doctor | Diagnose your install: provider readiness, vault unlock, missing optional dependencies. |

Run

| Command | What it does | |---|---| | moxxy | Default. Starts the Ink TUI. | | moxxy tui | Same as above, explicit. | | moxxy -p "…" (or --prompt) | One-shot prompt to stdout. | | moxxy resume [-s <id>] | Resume a persisted session. Interactive picker if no id. | | moxxy <channel> | Start a registered channel by name. | | moxxy channels | List registered channels and their subcommands. | | moxxy serve | Start every channel together with the scheduler and webhooks in one process. |

Manage

| Command | What it does | |---|---| | moxxy sessions list and delete | Inspect or remove persisted sessions. | | moxxy skills list, new, audit | Manage skill files across user, project, builtin, and plugin scopes. | | moxxy plugins list, reload, new | Manage the plugin host. reload picks up newly installed packages. | | moxxy mcp list, add, enable, disable, remove | Manage MCP servers in ~/.moxxy/mcp.json. | | moxxy perms list, add, remove | Inspect or edit the persisted permission rules. | | moxxy memory journal and recall | Read or query long-term memory. | | moxxy schedule add, list, remove | Time-driven prompts (cron or one-shot ISO). | | moxxy security audit, status, isolators | Inspect tool capability declarations and the active isolator. | | moxxy service install, logs, status, uninstall | Background OS services (launchd or systemd). | | moxxy self-update | Update bundled plugins, skills, and core safely. |

Flags

| Flag | What it does | |---|---| | --prompt, -p "…" | One-shot input. | | --model <id> | Override the default model for this invocation. | | --output-format <fmt> | text, json, or stream-json (one-shot output mode). | | --cwd <path> | Set the agent's working directory. | | --config <path> | Load a specific moxxy.config.ts. | | --no-color | Disable ANSI colors. | | -h, --help, -v, --version | Standard. |

Environment

| Variable | What it does | |---|---| | ANTHROPIC_API_KEY | Default Anthropic provider key. | | OPENAI_API_KEY | OpenAI provider key (also used by the openai embeddings plugin). | | MOXXY_VAULT_PASSPHRASE | Headless vault unlock when no OS keychain is available. | | MOXXY_FIXTURES | record or replay. Provider fixture mode used by tests. |

Channels

Run your agent through whichever surface fits the task.

| Channel | What it does | Command | |---|---|---| | TUI | Grok-style interactive terminal UI. | moxxy | | Telegram | Message the agent from anywhere. Voice notes get transcribed and run as turns. Pairs with a 6-digit code. | moxxy telegram | | HTTP | POST /v1/turn (JSON, SSE streaming) and POST /v1/turn/audio (raw bytes, iOS Shortcut friendly), bearer-token auth. | moxxy channels http | | Cron | Time-driven prompts. Cron expressions or one-shot ISO timestamps. | moxxy schedule add … | | Webhooks | External systems fire prompts on signed POST. HMAC plus bearer plus filter rules. | moxxy serve (auto-starts the listener) |

Services

Two ways to keep moxxy online 24/7.

Per-channel units, one process each so failures stay independent:

moxxy service install telegram     # launchd on macOS, systemd --user on Linux
moxxy service logs telegram         # tail the log

Or one process for everything, with a shared event log:

moxxy serve --background            # every channel plus the scheduler plus webhooks
moxxy serve --background --except http   # skip what you do not want
moxxy serve --status                # is it running?

Logs land in ~/.moxxy/services/<name>.log. The units survive reboots.

Configuration

moxxy.config.ts at your project root:

import { defineConfig } from '@moxxy/config';

export default defineConfig({
  provider: {
    name: 'anthropic',
    model: 'claude-sonnet-5',
    config: { apiKey: '${vault:ANTHROPIC_API_KEY}' },   // resolved from the vault
  },
  mode: 'default',
  plugins: {
    '@moxxy/plugin-browser': { enabled: false },        // disable a plugin (or use `moxxy plugins disable`)
  },
});

${vault:NAME} placeholders resolve on session start. The vault unlocks via OS keychain (keytar) with a passphrase fallback (MOXXY_VAULT_PASSPHRASE for headless boxes).

Docs

Full documentation lives at docs.moxxy.ai: concepts, recipes, plugin authoring, channel guides. The marketing site is at moxxy.ai.

Contributing

PRs welcome. The issue tracker and author guides live in the moxxy monorepo.

License

MIT. See the repository root for the full text.