Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
#!/usr/bin/env node
// three-ws: connect any MCP client to three.ws in one command.
// npx three-ws setup
import { parseArgs } from 'node:util';
import { realpathSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { systemEnv } from './paths.js';
import { readStore, resolveOrigin } from './store.js';
import { VERSION, ApiError } from './http.js';
import { c, errorLine, line, printJson } from './ui.js';
import { CancelledError } from './commands/common.js';
import { clientsFromFlags } from './commands/quick.js';
import { CliError, EXIT_CODES, exitCodeFor, isNonInteractive } from './automation.js';
export const HELP = `${c.bold('three-ws')} ${c.dim(`v${VERSION}`)}: connect any MCP client to three.ws
${c.bold('Usage')}
npx three-ws <command> [options]
${c.bold('Commands')}
setup Sign in, write the three.ws MCP servers into your clients, verify with tools/list
login Sign in or switch accounts (OAuth by default)
link <code> Link this terminal with a code from three.ws/dashboard/account
signup --agent An autonomous agent signs itself up: local Solana key, no email, no browser
logout Remove stored credentials and revoke the OAuth refresh token
doctor Diagnose a broken setup: bad config, expired sign-in, unreachable server
status Account, plan, wallet balance, token expiry, and every configured client
whoami Print the signed-in account
create [name] Create an agent with its own Solana wallet and a public page
agent status [id] Live state of your agents: wallet balance, page, body
team [status <id>] Your specialist teams: roster, findings, last error
launch Fill in a coin for one of your agents, then review and sign it on three.ws/launch
launch --intent Quote a launch paid from the agent's wallet in SOL or USDC, open its page, watch the stages
launch status <id> Stages of a funded launch intent (quote, paid, submitted, confirmed, indexed); --watch polls
tools Choose which tool groups each server exposes (financial tools are off by default)
mcp list Show three.ws servers configured in each client (--available lists all servers)
mcp add <server> Add one server to your clients without prompts
mcp remove <server> Remove one server from your clients
skills <sub> Browse and install community agent skills (list, search, show, import|install, installed)
agents list|get Your agents, for scripts: ids, names, pages and wallets
runs list|get An agent's runs (--agent), or one run with its steps, tool calls and receipt chain
orders list An agent's programmable orders (--agent, --network)
report run <id> One run as a single self-contained HTML file (--out report.html)
proxy <url> Run a stdio bridge to a hosted server (written into client configs by setup)
fund Top up credits from an agent wallet (--amount, --agent); mints an inference key once
provider use three-ws Point this machine's model clients at three.ws, billed to your credits
provider show The active model provider
usage Credits, burn rate, days left and recent top-ups (--agent for one agent's budget)
ask "<prompt>" One completion through the active provider
pay <url> Pay an x402 or MPP challenge from a local Solana key, inside pay-permissions.json
pay init|permissions|mcp Write the default limits, show them, or run the stdio MCP payer
wallet <sub> The local pay key: init, address, export-public, balance (never prints the private key)
version Print the version
${c.bold('Sign-in options')} (setup, login)
--oauth Browser sign-in with PKCE; tokens refresh automatically
--device Approve a code in any browser; yields an API key (works over SSH)
--key [sk_live_...] Use an API key (or set THREE_WS_API_KEY)
--financial Also request the scopes that let tools spend from your agent wallet
${c.bold('One flag per client')} (whole setup, no prompts, no secrets in the client's config)
--claude --cursor --codex --vscode --windsurf --gemini --bob --hermes
e.g. npx three-ws --claude; Claude Code also gets the three.ws skill
${c.bold('Setup options')}
--clients a,b claude-code, claude-desktop, cursor, windsurf, vscode, bob, codex, gemini, hermes, grok-bot, print
--servers a,b Server slugs or paths (default: /mcp, the unified server with every tool)
--packages a,b Also add stdio @three-ws/*-mcp packages
--project Write project-scoped config (.mcp.json, .cursor/, .vscode/, .bob/, .gemini/) in this directory
--proxy Route every server through the local proxy (enforces tool choices in every client)
--yes Never prompt; use defaults
${c.bold('Grok Bot options')} (setup --client grok-bot; Grok Bot keeps connectors in xAI's cloud)
--auth <mode> none (free), install (free, a quota that survives reconnects),
key (a connector key that can never spend) or oauth
--connector-key <key> Use this key for --auth key instead of minting one
--servers <slug> Connect another server than the recommended three-ws-grok
${c.bold('Tools options')}
--server <slug> Server to change
--enable a,b Tiers (read, write, financial) or tool names to turn on
--disable a,b Tiers or tool names to turn off
--reset Back to the default (read and write on, financial off)
${c.bold('Agent options')} (create, launch)
--name <text> Agent name (create) or coin name (launch)
--description <text> What the agent or coin is
--avatar <id> An avatar you own to use as the agent's 3D body (create)
--agent <id> The agent that launches the coin (launch)
--symbol <ticker> Coin ticker, letters and digits (launch)
--image <https-url> Coin image; the agent's portrait when omitted (launch)
--initial-buy <sol> SOL for the first buy, prefilled for review (launch)
--intent Create a funded launch intent instead of prefilling /launch (launch)
--quote <sol|usdc> Asset the launch and first buy are paid in; /api/pump/pairs lists what is live (launch --intent)
--creator-fee <bps> Creator fee in basis points within the range the program allows (launch --intent)
--network <net> mainnet (default) or devnet, where a dry run never touches mainnet (launch --intent)
--watch Keep polling until the intent settles (launch status)
${c.bold('Inference options')} (fund, provider, usage)
--amount <usdc> USDC to move from the agent wallet into credits (fund)
--agent <id> The agent whose wallet pays (fund) or whose budget to show (usage)
--name <label> Name for the minted inference key (fund)
--yes Approve the printed transfer without a prompt (fund)
${c.bold('Pay options')} (pay, wallet)
--dry-run Print the decision, exact amount and payee; sign and send nothing
--max <amount> Refuse anything above this many whole units (e.g. 0.05)
--network <net> Only consider mainnet, devnet or a CAIP-2 network id
--method <verb> HTTP method (default GET, POST with --data)
--data <text> Request body, resent after payment
-H, --header <h> Extra request header "Name: value" (repeatable)
--yes Approve a payment above confirmAbove without a prompt
--storage <where> auto (keychain, else sealed file), keychain or file (wallet init)
Exit codes: 10 outside permissions, 11 needs confirmation, 12 no payable option,
13 payment rejected, 14 wallet missing or locked. Reason string in --json.
${c.bold('Automation')} (every command)
--json One JSON document on stdout; diagnostics and errors' text go to stderr
--non-interactive Never prompt (also THREE_WS_NON_INTERACTIVE=1); missing input exits 2
Exit codes: 0 ok, 1 error, 2 usage, 3 auth, 4 refused by a guard, 5 payment required, 6 network.
(\`pay\` keeps its own 10 to 14, listed above.) Full table: docs/cli.md
${c.bold('Global')}
--json Machine-readable output on stdout
--origin <url> Talk to another three.ws deployment (or THREE_WS_ORIGIN)
--no-color Plain output
-h, --help This help
Docs: https://three.ws/docs/cli`;
const OPTIONS = {
json: { type: 'boolean' },
'non-interactive': { type: 'boolean' },
out: { type: 'string' },
origin: { type: 'string' },
'no-color': { type: 'boolean' },
help: { type: 'boolean', short: 'h' },
version: { type: 'boolean', short: 'v' },
yes: { type: 'boolean', short: 'y' },
oauth: { type: 'boolean' },
device: { type: 'boolean' },
key: { type: 'string' },
financial: { type: 'boolean' },
clients: { type: 'string' },
client: { type: 'string' },
'no-copy': { type: 'boolean' },
servers: { type: 'string' },
packages: { type: 'string' },
project: { type: 'boolean' },
proxy: { type: 'boolean' },
server: { type: 'string' },
enable: { type: 'string' },
disable: { type: 'string' },
reset: { type: 'boolean' },
available: { type: 'boolean' },
amount: { type: 'string' },
agent: { type: 'string' },
name: { type: 'string' },
description: { type: 'string' },
avatar: { type: 'string' },
symbol: { type: 'string' },
image: { type: 'string' },
'initial-buy': { type: 'string' },
auth: { type: 'string' },
'connector-key': { type: 'string' },
intent: { type: 'boolean' },
quote: { type: 'string' },
'creator-fee': { type: 'string' },
network: { type: 'string' },
watch: { type: 'boolean' },
'dry-run': { type: 'boolean' },
max: { type: 'string' },
method: { type: 'string' },
data: { type: 'string' },
header: { type: 'string', short: 'H', multiple: true },
storage: { type: 'string' },
claude: { type: 'boolean' },
cursor: { type: 'boolean' },
codex: { type: 'boolean' },
vscode: { type: 'boolean' },
windsurf: { type: 'boolean' },
gemini: { type: 'boolean' },
bob: { type: 'boolean' },
hermes: { type: 'boolean' },
};
// `--key` alone (no value) means "prompt for it"; parseArgs needs a value for a
// string option, so a bare --key becomes --key= before parsing.
// `signup --agent` is a mode switch, but `agent` is a string option elsewhere
// (`--agent <id>`), so on the signup command a bare --agent becomes --agent=.
function normalizeArgv(argv) {
const bare = (i) => argv[i + 1] === undefined || argv[i + 1].startsWith('-');
return argv.map((a, i) => {
if (a === '--key' && bare(i)) return '--key=';
if (a === '--agent' && argv[0] === 'signup' && bare(i)) return '--agent=';
return a;
});
}
export function parse(argv) {
const { values, positionals } = parseArgs({ args: normalizeArgv(argv), options: OPTIONS, allowPositionals: true, strict: true });
if (values.client && !values.clients) values.clients = values.client;
const perClient = clientsFromFlags(values).length > 0;
// A per-client flag with no command is the whole setup for that client.
const fallback = values.version ? 'version' : perClient ? 'quick' : 'help';
let [command = fallback, ...rest] = positionals;
if (perClient && command === 'setup') command = 'quick';
return { command, positionals: rest, flags: values };
}
const COMMANDS = {
setup: async (ctx) => (await import('./commands/setup.js')).setup(ctx),
login: async (ctx) => (await import('./commands/account.js')).login(ctx),
link: async (ctx) => (await import('./commands/account.js')).link(ctx),
signup: async (ctx) => (await import('./commands/signup.js')).signup(ctx),
logout: async (ctx) => (await import('./commands/account.js')).logout(ctx),
status: async (ctx) => (await import('./commands/account.js')).status(ctx),
whoami: async (ctx) => (await import('./commands/account.js')).whoami(ctx),
tools: async (ctx) => (await import('./commands/tools.js')).tools(ctx),
quick: async (ctx) => (await import('./commands/quick.js')).quick(ctx),
doctor: async (ctx) => (await import('./commands/doctor.js')).doctor(ctx),
team: async (ctx) => (await import('./commands/live.js')).team(ctx),
agent: async (ctx) => {
const [sub, ...rest] = ctx.positionals;
const next = { ...ctx, positionals: rest };
if (sub === 'status') return (await import('./commands/live.js')).agentStatus(next);
if (sub === 'create') return (await import('./commands/agent.js')).create(next);
if (sub === 'launch') return (await import('./commands/agent.js')).launch(next);
throw new CliError(EXIT_CODES.USAGE, 'usage', 'usage: three-ws agent <status [id]|create [name]|launch [status <id>]>');
},
create: async (ctx) => (await import('./commands/agent.js')).create(ctx),
launch: async (ctx) => (await import('./commands/agent.js')).launch(ctx),
mcp: async (ctx) => (await import('./commands/mcp.js')).mcp(ctx),
proxy: async (ctx) => {
const [url] = ctx.positionals;
if (!url || !/^https?:\/\//.test(url)) throw new Error('usage: three-ws proxy <https://three.ws/api/mcp> [--server <slug>]');
const { runProxy } = await import('./proxy.js');
await runProxy({ url, server: ctx.flags.server || null, env: ctx.env });
return 0;
},
agents: async (ctx) => (await import('./commands/automation.js')).agents(ctx),
runs: async (ctx) => (await import('./commands/automation.js')).runs(ctx),
orders: async (ctx) => (await import('./commands/automation.js')).orders(ctx),
report: async (ctx) => (await import('./commands/automation.js')).report(ctx),
pay: async (ctx) => (await import('./commands/pay.js')).payCommand(ctx),
wallet: async (ctx) => (await import('./commands/wallet.js')).wallet(ctx),
fund: async (ctx) => (await import('./commands/inference.js')).fund(ctx),
provider: async (ctx) => (await import('./commands/inference.js')).provider(ctx),
usage: async (ctx) => (await import('./commands/inference.js')).usage(ctx),
ask: async (ctx) => (await import('./commands/inference.js')).ask(ctx),
version: async (ctx) => {
if (ctx.flags.json) printJson({ version: VERSION, node: process.versions.node });
else line(VERSION);
return 0;
},
help: async () => {
line(HELP);
return 0;
},
};
/**
* Print a failure and return its exit code. Under --json stdout carries exactly
* one JSON document (the error object) and the human sentence goes to stderr;
* otherwise the sentence goes to stderr alone.
*/
function failure(err, { json, env }) {
const exit = exitCodeFor(err);
if (json) {
printJson({ error: err.code || 'error', message: err.message, exit, detail: err.detail, status: err instanceof ApiError ? err.status : undefined });
}
errorLine(err.message);
if (env.vars.THREE_WS_DEBUG === '1' && err.stack) process.stderr.write(`${err.stack}\n`);
return exit;
}
export async function main(argv = process.argv.slice(2), env = systemEnv()) {
// `skills` (alias `skill`) owns its own argument grammar (see commands/skills.js).
if (argv[0] === 'skills' || argv[0] === 'skill') {
const rest = argv.slice(1);
const json = rest.includes('--json');
try {
const { runSkills } = await import('./commands/skills.js');
const originIdx = rest.indexOf('--origin');
const { code, output } = await runSkills(rest, { env, origin: originIdx >= 0 ? rest[originIdx + 1] : undefined });
if (json && code !== 0) {
printJson({ error: code === EXIT_CODES.USAGE ? 'usage' : code === EXIT_CODES.GUARD ? 'refused_by_guard' : 'error', message: output, exit: code });
return code;
}
if (output) (code === 0 ? process.stdout : process.stderr).write(`${output}\n`);
return code;
} catch (err) {
return failure(err, { json, env });
}
}
let parsed;
try {
parsed = parse(argv);
} catch (err) {
if (argv.includes('--json')) printJson({ error: 'usage', message: err.message, exit: EXIT_CODES.USAGE });
errorLine(`${err.message}. Run \`three-ws --help\`.`);
return EXIT_CODES.USAGE;
}
const { command, positionals, flags } = parsed;
if (flags.help && command !== 'help') return COMMANDS.help();
const run = COMMANDS[command];
if (!run) {
if (flags.json) printJson({ error: 'usage', message: `unknown command "${command}"`, exit: EXIT_CODES.USAGE });
errorLine(`unknown command "${command}". Run \`three-ws --help\`.`);
return EXIT_CODES.USAGE;
}
const origin = resolveOrigin({ flag: flags.origin, env, store: readStore(env) });
const ctx = { command, positionals, flags, env, origin, nonInteractive: isNonInteractive(flags, env) };
try {
return await run(ctx);
} catch (err) {
if (err instanceof CancelledError) {
errorLine('Cancelled. Nothing after the last completed step was changed.');
return 130;
}
return failure(err, { json: flags.json, env });
}
}
const invokedDirectly = (() => {
try {
return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
} catch {
return false;
}
})();
if (invokedDirectly) {
main().then((code) => {
process.exitCode = code;
});
}