companion-cli 1.0.0 → 1.1.0

package/README.md

@@ -1 +1,171 @@
-# nm-cli
+# companion-cli
+
+A model-agnostic AI assistant for your terminal. Chat with OpenAI, Anthropic, or Google models — with built-in tools for file operations, git, image generation, video creation, desktop automation, smart home control, and more.
+
+## Install
+
+```bash
+npm install -g companion-cli
+```
+
+Requires **Node.js 20+**.
+
+## Quick Start
+
+```bash
+# Start interactive chat
+companion-cli
+
+# Configure your API key (at least one provider required)
+# Inside the chat, run:
+/config set providers.openai.apiKey sk-...
+```
+
+Or set environment variables:
+
+```bash
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export GOOGLE_API_KEY=AIza...
+```
+
+## Supported Providers & Models
+
+| Provider | Models |
+|----------|--------|
+| **OpenAI** | GPT-5.4, GPT-4.1, GPT-4.1 Mini, GPT-4.1 Nano, o3, o3-mini, o4-mini, GPT-4o, GPT-4o Mini |
+| **Anthropic** | Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4, Claude Sonnet 4, Claude Haiku 4.5 |
+| **Google** | Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.0 Flash, Gemini 2.0 Flash Lite, Gemini 1.5 Pro, Gemini 1.5 Flash |
+
+Switch models on the fly with `/model` or `/model openai:gpt-4.1`.
+
+## Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `/help` | `/h`, `/?` | Show available commands |
+| `/model` | `/m` | Switch AI provider and model |
+| `/config` | `/cfg` | Manage settings (API keys, theme, defaults) |
+| `/agent` | `/a` | Create, run, and manage custom agents |
+| `/devices` | `/dev` | Manage smart home devices |
+| `/clear` | | Clear screen and chat history |
+| `/exit` | `/quit`, `/q` | Exit |
+
+## Built-in Tools
+
+The AI has access to a rich set of tools it can use to help you:
+
+### Filesystem
+- **Read/write/edit files** with surgical string replacement
+- **Search files** by content (grep) or glob patterns
+- **File stats**, directory creation, deletion
+
+### Shell & Git
+- **Run shell commands** with timeout and output capping
+- **Git operations** — status, diff, log, commit, branch management
+
+### Image & Video
+- **DALL-E 3** image generation — saved directly to disk
+- **Sora** video generation — up to 5 minutes, with async progress tracking
+
+### Canvas & Drawing
+- **14 brush types** — round, flat, fan, airbrush, watercolor, ink, chalk, and more
+- Gradients, flood fill, smudge, blur effects
+- Compositing and text rendering — save to PNG
+
+### Desktop Automation (Windows)
+- **Screenshots** — capture full screen or regions
+- **Window management** — list, move, resize, focus windows
+- **Mouse & keyboard** — click, type, send key combos
+- **Launch applications**
+
+### Smart Home
+- **Google Cast** (Chromecast, Google Home, Nest) — play media, TTS, volume control
+- **Amazon Alexa** (Echo, Fire TV) — playback control, notifications
+- **YouTube search & play** — find and play music on your speakers
+- **Device discovery** via mDNS scanning
+
+### Web
+- **Fetch URLs** with SSRF protection
+
+## Custom Agents
+
+Create specialized AI personas with custom system prompts, specific models, and curated tool sets:
+
+```
+/agent create my-coder
+```
+
+Run agents directly:
+
+```
+/agent run my-coder "refactor this function to use async/await"
+```
+
+Run multiple agents in parallel:
+
+```
+/agent run-parallel coder,reviewer "analyze this pull request"
+```
+
+Agents are stored in your config directory alongside your settings.
+
+## Configuration
+
+All configuration is stored in your OS config directory:
+
+| OS | Path |
+|----|------|
+| Windows | `%APPDATA%\companion-cli-nodejs\config.json` |
+| macOS | `~/Library/Preferences/companion-cli-nodejs/config.json` |
+| Linux | `~/.config/companion-cli-nodejs/config.json` |
+
+```bash
+# Set config values
+/config set providers.openai.apiKey sk-...
+/config set defaultProvider anthropic
+/config set defaultModel claude-sonnet-4-6
+/config set theme.userColor cyan
+
+# View config
+/config list
+/config path
+
+# Or use the interactive wizard
+/config
+```
+
+API key priority: **environment variables** > **config file**.
+
+## CLI Usage
+
+```bash
+# Interactive chat (default)
+companion-cli
+
+# With flags
+companion-cli --verbose
+companion-cli --debug
+companion-cli --quiet
+
+# Direct config management
+companion-cli config set <key> <value>
+companion-cli config get <key>
+companion-cli config list
+
+# Run agents from the command line
+companion-cli agent list
+companion-cli agent run <name> "<prompt>"
+```
+
+## Security
+
+- Mutating file operations and shell commands require user confirmation
+- Path traversal protection on all filesystem tools
+- SSRF protection on URL fetching
+- Dangerous shell commands are blocked
+- API keys are masked in output
+
+## License
+
+MIT