companion-cli

A model-agnostic AI assistant that lives in your terminal. Chat with OpenAI, Anthropic, or Google models; let them read and edit files, run shell commands, control Windows desktop apps, cast audio to Google Home / Alexa, and generate images and video — all from a single companion command.

Install

npm install -g companion-cli

Requires Node.js ≥ 20. Works on Windows, macOS, and Linux (desktop-automation tools are Windows-only; smart-home features run anywhere).

Quick start

companion

On first run it walks you through picking a provider and model. After that, just type — the AI will use tools automatically when your request needs them.

(openai:gpt-4o)> what's in this folder?
(openai:gpt-4o)> read package.json and tell me the main entry
(openai:gpt-4o)> create a file called notes.md with today's plan
(openai:gpt-4o)> launch notepad
(openai:gpt-4o)> play some lofi on the living room speaker

Configuring providers

Set an API key for at least one provider:

companion config set providers.openai.apiKey sk-...
companion config set providers.anthropic.apiKey sk-ant-...
companion config set providers.google.apiKey AIza...

Or, from inside the chat:

/config set providers.openai.apiKey sk-...

Other useful config commands:

| Command | What it does | | --- | --- | | companion config list | Show all stored settings | | companion config get <key> | Read a single value | | companion config path | Print the on-disk config file path |

API-key values are masked in output. The config file lives in the OS-standard app data directory (%APPDATA%/nm-cli-nodejs/ on Windows).

Slash commands

Inside the chat, type / to see suggestions. Core commands:

| Command | Purpose | | --- | --- | | /help | List all commands | | /model | Switch provider or model interactively | | /config | Manage configuration (same keys as the CLI config subcommand) | | /devices | Discover, register, and test smart-home devices (Google Cast, Alexa) | | /agent | List, view, and run saved agents | | /clear | Wipe conversation history | | /exit (or /quit, /q) | Leave the chat |

Prefix-matching works, so /mo is enough to hit /model.

What the AI can do

When you ask for something, the model picks the right tool from this catalog. Mutating actions prompt you for confirmation before running.

Filesystem — listFiles, readFile, viewImage, searchFiles, globFiles, fileStats, writeFile, editFile, createDirectory, deleteFile

Shell & git — runCommand, gitStatus, gitDiff, gitLog, gitCommit, gitBranch

Web & media — fetchUrl (with SSRF protection), generateImage, generateVideo

Canvas (in-memory image editing) — createCanvas, drawText, drawImage, drawGradient, floodFill, brush tools (setBrush, brushStroke, brushFill, brushSmudge, brushBlur), saveCanvas

Desktop automation (Windows only) — takeScreenshot, getOpenWindows, moveWindow, focusWindow, mouseClick, pressKeys, launchApp

Smart home — listSmartDevices, getDeviceStatus, controlDevice, playMedia, searchMusic, playMusic, sendNotification, askAssistant

Smart-home setup

Register devices once, then talk to them by name.

/devices

The interactive wizard scans your network for Google Cast devices (Chromecast, Google Home, Nest Hub) and walks you through linking Alexa. Once registered, the AI routes requests automatically:

• "play some jazz in the kitchen" → YouTube search + Cast
• "turn off the living room lights" → Google Assistant relay
• "what's the weather?" → ask any linked Google device

Agents

Agents are reusable presets (system prompt + provider + model + temperature) stored as JSON in agents/. Run one from the command line:

companion agent list
companion agent view code-reviewer
companion agent run code-reviewer "review the diff in src/chat.ts"

Or from inside the chat:

/agent run code-reviewer review the last change I made

CLI reference

companion                       # start interactive chat (default)
companion chat [--verbose|--debug|--quiet]
companion config set <k> <v>
companion config get <k>
companion config list
companion config path
companion agent list
companion agent view <name>
companion agent run <name> <prompt>
companion --help
companion --version

Environment

• .env in the current working directory is loaded automatically; system env vars take precedence.
• Desktop automation uses koffi FFI to Win32 and is only enabled on process.platform === 'win32'.
• Smart-home adapters (castv2-client, alexa-remote2, bonjour-service, google-tts-api) are optional dependencies — the CLI degrades gracefully when they aren't installed.

Development

git clone https://github.com/anmarht/companion-cli.git
cd companion-cli
npm install
npm run dev          # run from TypeScript via tsx
npm run build        # bundle to dist/ with tsup
npm run typecheck    # tsc --noEmit

The project is ESM-only — relative imports in TypeScript source must use the .js extension.

License

MIT — see LICENSE. Author: anmarht.