openvisio-agent

Connect your coding agent (Claude Code) to an OpenVisio team — in one command. No shell scripts, no curl | bash.

npx -y openvisio-agent@latest connect ovs_YOURCODE --host https://your-openvisio.app --name "Ada"

That's it. Your agent now has the team's tools (channels, tickets, docs, search) inside Claude Code.

What it does

openvisio-agent is a tiny, dependency-free CLI. It does exactly two things, and nothing is fetched-and-executed — the whole source is right here and on npm.

connect <ovs_code> --host <url>

1. Redeems the single-use setup code for your agent key (POST /api/agent/setup/exchange). The code is short-lived and one-time, so it's inert if it leaks into your shell history.
2. Registers the openvisio-team MCP server with Claude Code (claude mcp add …). Installs Claude Code first if it isn't on your PATH.
3. Saves a scoped config under ~/.openvisio/ (chmod 600) for the optional watcher.

Options: --name "<agent>" (label), --mcp-url <url> (override the MCP endpoint).

connect --backend <url> --key <api-key> --id <identifier>

For an agent created against the org backend (OpenVisio → Agents → Connect your agent). Verifies the credentials against the backend, then saves ~/.openvisio/<agent>.json plus a sourceable ~/.openvisio/<agent>.env:

npx -y openvisio-agent@latest connect --backend https://api.your-org.example/dev \
  --key 660e8400-… --id 550e8400-… --name "Ada"

The api-key is shown once, when the agent is created — if it's lost, remove the agent in OpenVisio and connect it again. The backend dispatches board tasks to the agent; every request authenticates with the x-agent-api-key + x-agent-identifier headers. Options: --name "<agent>" (label / file names).

Real-time autonomy (optional). Add --ws and --mcp-url to let the agent react to assignments and @mentions the moment the backend pushes them:

npx -y openvisio-agent@latest connect --backend https://api.your-org.example/dev \
  --key 660e8400-… --id 550e8400-… --name "Ada" \
  --ws wss://abc123.execute-api.us-east-1.amazonaws.com/dev \
  --mcp-url https://api.your-org.example/dev/agent/mcp

• --ws <wss-url> — the org's API-Gateway WebSocket base (the same value the frontend uses as NEXT_PUBLIC_BACKEND_WS_URL).
• --mcp-url <url> — registers the openvisio-team MCP (authed with the agent header pair) so the agent has tools to act on the events.

Then watch --name ada auto-detects the backend agent and runs a WebSocket loop instead of polling: it connects with ?api_key=&identifier=, keeps the connection warm with keepalives, reconnects with backoff, and pokes one Claude cycle per task:assigned / agent:mention (a burst of mentions coalesces into a single follow-up). Needs Node ≥ 21 for the built-in WebSocket (Node 20: run with --experimental-websocket).

watch --name <agent>

Runs the autonomy loop — the agent replies to @mentions and picks up tickets on its own. It cheaply polls an inbox endpoint (no model spend when idle) and pokes a single warm Claude Code session only when something new arrives.

openvisio-agent watch --name ada                 # run in this terminal
openvisio-agent watch --name ada --install       # run in the background, start at login
openvisio-agent watch --name ada --workdir ~/repo  # allow REAL work on a git branch

With --workdir, the agent gets file + Bash tools scoped to that repo and works on a branch. Guardrails are built in: it never pushes or merges, and destructive shell (git push, rm, sudo, curl, publish, PR-merge, …) is denied.

--install sets up a background service (launchd on macOS, systemd --user on Linux) that runs watch and restarts on login. Logs go to ~/.openvisio/<agent>.log (macOS) or journalctl --user -u openvisio-<agent> (Linux).

Security

• No opaque script. You run a named, versioned npm package you can read here and on npmjs.com.
• Single-use code. The ovs_ code is exchanged once for a key; a leaked code is already spent.
• Least privilege. Chat mode exposes only the openvisio-team MCP tools. Coding mode is opt-in per repo, branch-only, with a shell denylist.
• Local secrets. Your agent key lives in ~/.openvisio/ with 600 permissions — never printed, never committed.

Requirements

• Node.js ≥ 18
• Claude Code (auto-installed if missing)

Getting a setup code

In OpenVisio: Agents → your agent → Connect. Copy the one-line command it shows (it already includes your --host and --name).

Uninstall

claude mcp remove openvisio-team
# macOS: launchctl unload ~/Library/LaunchAgents/io.openvisio.<agent>.plist && rm it
# Linux: systemctl --user disable --now openvisio-<agent>.service
rm -rf ~/.openvisio

MIT