@xyne/xyne-cli

Xyne CLI

A terminal-first AI coding assistant with a local client/server architecture, Pi-powered agent runtime, OpenTUI interface, MCP support, and extension management.

Xyne CLI brings an AI coding assistant to the terminal using a local server + terminal client model:

• the server hosts the Pi-based runtime, sessions, tools, MCP integration, and extensions
• the terminal client is built with OpenTUI and connects over WebSocket
• the repo also exposes a library surface so other products, such as xyne-code, can reuse the backend

Features

Core capabilities

• Interactive terminal client powered by OpenTUI
• Local daemon server started automatically when needed
• Multi-provider model setup through LiteLLM and built-in provider presets for OpenAI, Anthropic, and Gemini
• One-shot prompt mode with optional custom system prompt and tool filtering
• Reusable library exports for external consumers

Agent and workflow features

• Session management with resume, rename, load, delete, and history replay support
• Model controls for listing, switching, and cycling models
• Thinking controls including level switching and context compaction
• Extension management for Pi-compatible extensions
• MCP integration for local and remote MCP servers
• Optional Serper-backed web search

Terminal UI features

• Right sidebar, header, footer, and input UI rendered in OpenTUI
• Slash commands such as /compact, /model, /resume, /session, /theme, and /export
• Clipboard helpers including copying the last response and pasting a clipboard image
• Session export to HTML from the interactive client
• Theme switching from inside the terminal UI

Installation

Global installation

npm install -g @xyne/xyne-cli

The published package includes the launcher and bundled CLI assets needed to run xyne.

Run with Nix

With Nix installed, run the CLI straight from the repo without installing anything:

nix run github:xynehq/xyne-cli

Verify installation

xyne --version

Usage

Interactive mode

# Start interactive terminal mode
xyne

# Continue the last session
xyne --continue

# Resume a specific session by id
xyne --session <id>

# Load a previously exported conversation
xyne --load=path/to/conversation.json

# Start daemon mode only
xyne --daemon

# Run a one-shot prompt
xyne prompt "Summarize this repository"

# Show help
xyne --help

Interactive mode automatically:

1. parses CLI arguments
2. ensures the local server is running
3. launches the OpenTUI terminal client
4. connects the client to the local server over WebSocket

Supported interactive flags:

• --debug
• --continue
• --session <id>
• --daemon
• --port=<number>
• --load=<path>

One-shot prompts

xyne prompt "What files are in this project?"
xyne prompt "Help me debug this" --system="You are concise"
xyne prompt "Inspect the repo" --tools=read,grep,ls
echo "Summarize this" | xyne prompt

Supported prompt options:

• --debug
• --system-prompt="..."
• --system="..."
• --tools=tool1,tool2,...

Prompt mode tools from CLI help:

• read
• write
• edit
• multiedit
• grep
• glob
• ls
• bash
• todo-write

Interactive slash commands

The OpenTUI client exposes commands such as:

• /compact
• /clear
• /copy
• /extensions
• /export
• /model
• /name
• /new
• /resume
• /session
• /surface-debug
• /theme
• /hotkeys
• /quit

Configuration

AI provider setup

Xyne setup is currently centered around configuring providers into ~/.xyne/agent/models.json.

LiteLLM

# Use the default LiteLLM base URL
xyne setup --litellm <api_key>

# Or specify a custom LiteLLM-compatible base URL and provider name
xyne setup --litellm <url> <api_key> [provider-name]

Default LiteLLM values used by setup:

• default base URL: https://grid.ai.juspay.net/v1
• default provider name: juspay

During setup, Xyne fetches available models from the LiteLLM /models endpoint and stores them in the local models configuration.

Direct provider presets

Xyne also supports quick provider setup commands for:

• OpenAI
• Anthropic Claude
• Google Gemini

xyne setup --openai <api_key> [provider-name]
xyne setup --claude <api_key> [provider-name]
xyne setup --gemini <api_key> [provider-name]

These commands use built-in default base URLs and default model lists for each provider.

Setup wizard

xyne setup

Quick setup commands:

xyne setup --litellm <api_key>
xyne setup --litellm <url> <api_key> [provider-name]
xyne setup --openai <api_key> [provider-name]
xyne setup --claude <api_key> [provider-name]
xyne setup --gemini <api_key> [provider-name]
xyne setup --services serper <api_key>

MCP servers

xyne mcp add context7 sh -c "npx -y @upstash/context7-mcp 2>/dev/null"
xyne mcp add deepwiki --transport=http --url=https://mcp.deepwiki.com/mcp
xyne mcp add myserver npx my-mcp-server --env=API_KEY=secret --cwd=/path/to/project

xyne mcp list
xyne mcp get context7
xyne mcp remove context7

xyne mcp add-json github '{"command":"docker","args":["run","-i","--rm","ghcr.io/github/github-mcp-server"]}'

Enabling Specific Servers:

By default, all configured MCP servers are available as tools but not advertised in the system prompt. Use --mcp to enable specific servers:

# Enable specific servers at startup
xyne --mcp=deepwiki --mcp=context7

Available MCP subcommands:

• add
• remove
• list
• get
• add-json

You can use --global for global MCP configuration.

Extension management

Xyne supports Pi-compatible extensions through the runtime.

xyne extension add npm:pi-mono-btw
xyne extension add git:github.com/emanuelcasco/pi-mono-extensions
xyne extension list
xyne extension inspect npm:pi-mono-btw
xyne extension disable npm:pi-mono-btw
xyne extension enable npm:pi-mono-btw
xyne extension reload
xyne extension remove npm:pi-mono-btw

Available extension subcommands:

• add
• remove
• list
• inspect
• reload
• enable
• disable

All extensions are installed globally in ~/.xyne/agent/settings.json.

Configuration and storage

Important local paths used by the CLI:

• agent directory: ~/.xyne/agent
• service keys: ~/.xyne/agent/services.json
• sandbox config: ~/.xyne/agent/sandbox.json
• theme preference: ~/.xyne/agent/theme.json
• model config: ~/.xyne/agent/models.json
• auth storage: ~/.xyne/agent/auth.json
• local MCP config: .xyne/config/mcp.json
• global MCP config: ~/.xyne/config/mcp.json

The agent directory can be overridden with XYNE_AGENT_DIR.

Optional web search configuration

export SERPER_API_KEY="your-serper-key"

or save it through setup:

xyne setup --services serper <api_key>

Keyboard shortcuts

Interactive hotkeys exposed by the terminal client include:

• Esc — abort current run
• Ctrl+C — clear input / exit on double press
• Ctrl+D — exit
• Shift+Tab — cycle thinking level
• Ctrl+P — cycle model forward
• Ctrl+Shift+P — cycle model backward
• Alt+Enter — queue a follow-up message
• Ctrl+O — toggle tool output expansion
• Ctrl+T — toggle thinking block visibility
• Ctrl+V — paste clipboard image

Library usage

This package is also consumable as a library.

Main exports include:

• createXyneSession
• connectUI
• session history helpers from src/agent/session-service.ts
• shared types from src/agent/types.ts
• protocol exports via @xyne/xyne-cli/protocol

Example:

import { createXyneSession, connectUI } from "@xyne/xyne-cli";
import type { XyneUI } from "@xyne/xyne-cli/agent";

The library entrypoint is designed for external consumers such as VS Code integrations and other UI surfaces.

Protocol and clients

The server and clients communicate using the shared protocol in packages/protocol.

Key pieces:

• ClientMessage — messages sent from a client to the server
• ServerMessage — messages sent from the server to a client
• AgentSessionEvent — Pi session events forwarded through the Xyne bridge
• WsXyneUI — WebSocket implementation of the Xyne UI bridge on the server side

Current clients in this repo:

• OpenTUI terminal client in src/agent/opentui-client.ts
• web client workspace in packages/web
• legacy tui-client.ts still exists in the repo, but the main CLI path uses OpenTuiClient

Development

Requirements

• Node.js 18+
• Bun for local development and build workflows

Common commands

# Run the CLI in development
bun run dev

# Build distributable package artifacts
bun run build

# Build the protocol package
bun run build:protocol

# Build the library surface
bun run build:lib

# Type-check
bun run typecheck

Library verification

After changing files under src/agent/, build the library output:

bun run build:lib
bunx tsc -p tsconfig.lib.json
bunx tsc --noEmit

Workspace packages

• root package: @xyne/xyne-cli
• protocol package: @xyne/protocol
• web workspace: @xyne/web

Documentation notes

This README reflects the current codebase structure:

• terminal UI is based on OpenTUI, not Ink
• the CLI uses a local daemon + WebSocket client architecture
• extension management command is xyne extension ..., not extensions
• xyne --serve and remote --url interactive mode are no longer supported

Made with by the Xyne Team