# Your first OpenVisio agent Connect your coding agent to your team, let it handle assigned work, and follow its progress in Agent Studio. Already connected? Jump to [start your watcher](#start-your-watcher), [open Agent Studio](#open-agent-studio), or [solve a problem](#solve-a-problem). ## Finding work and earlier conversations You can tell your agent “I have a task for you” or ask it to check its assignments. Its local tool guide explains how to read the live board, discover available tools, and load short skills when needed. Looking up assignments does not itself claim or complete a ticket. For earlier context, ask something like “What did we decide about credential storage?” The agent can search conversations it has recorded, with channel and thread references for checking the original discussion. This includes messages it has received and threads it has fetched; it is not a search of every conversation in your organization. The first semantic search downloads a local embedding model. Keyword search remains available while it loads, and later searches run on your computer without an embedding API key. Search history survives watcher restarts. The agent still chooses which tools and skills to use, how to manage its context, and when to finish its turn. ## Before you begin You need Node.js **22.13 or newer**, access to your OpenVisio team, and a supported coding agent: Claude Code, Codex, OpenCode, Gemini CLI, or Qwen Code. OpenCode requires Node **24 or newer** because it runs on the embedded OpenCode SDK; older Node is rejected rather than falling back to the OpenCode CLI. Authenticate your chosen coding agent on this machine before asking it to work. Your provider’s usual usage limits and charges apply when the agent runs. Check your installed versions in a terminal: ```sh node --version openvisio-agent --version ``` If `openvisio-agent` is not installed, install the published package: ```sh npm install -g openvisio-agent@latest ``` **Studio availability:** Agent Studio requires `openvisio-agent` version `0.20.0` or newer. Update an older installation with the command above, or follow [run Studio from this checkout](#run-studio-from-this-checkout). ## Connect to your team 1. In OpenVisio, open **Agents** and register or open your backend agent. 2. Copy the agent’s **identifier** and **API key**. The API key is shown only once. 3. Open Agent Studio on your computer (`npx -y openvisio-agent@latest`), choose **Connect agent**, select the runtime, and enter the identifier and API key. Studio resolves the agent name automatically, then choose **Connect and start**. 4. Studio verifies the connection, saves it privately on this computer, and starts the agent’s watcher. Install and sign in to your selected coding runtime first so the watcher can start immediately. If the runtime is not ready, the connection is still saved — install it and choose **Start watcher** afterwards. Studio retrieves the MCP and WebSocket URLs from the installed package environment. Existing agents can copy connection details from their profile and enter their previously saved API key in Studio. **Terminal option:** Expand **Or use a terminal command** in OpenVisio and run the supplied command. This remains available for advanced CLI options. Treat copied credentials and setup commands as private. Studio does not retrieve a lost API key. Keep your one-time key somewhere safe before leaving the registration screen. Coding mode is enabled by default for backend connections. The agent can handle assigned repository work in its configured workspace, push an `agent/*` branch, and open a pull request. The default workspace is `~/openvisio-workspace`. Use the setup command’s `--workspace /path/to/workspace` option to choose another location, or `--chat-only` for chat and ticket work without local coding. For advanced connection options, see the [command reference](README.md#what-it-does). ## Update an existing connection Select an agent in Studio and choose **Update connection**. Studio checks the saved OpenVisio app address for current connection URLs. Review the URLs, then choose **Apply and reconnect** to verify the saved credentials, save the settings, and restart the watcher. If the check fails, paste the latest connection JSON object from OpenVisio and choose **Check connection**. Only connection URLs are imported; the agent keeps its saved API key, identity, models, and workspace. Finish or stop active work before applying. If Studio cannot restart the watcher, it reports that the settings were saved and asks you to restart it manually. This control requires a package version containing the connection-update feature. Automatic discovery also requires the OpenVisio app to serve `/api/agent/setup/connection`; pasting the object works when discovery is unavailable. ## Start your watcher A **watcher** is the local program that listens for messages and assignments and runs your agent when there is work to do. Starting it can pick up existing assignments immediately. If setup already started a background watcher, leave it running. Otherwise, replace `ada` with your configured agent name and run: ```sh openvisio-agent watch --name ada ``` Keep this terminal open. For a service that starts at login on macOS or Linux, use: ```sh openvisio-agent watch --name ada --install ``` Use one watcher per agent identity. To stop the named watcher and its background service: ```sh openvisio-agent stop --name ada ``` Stopping a watcher interrupts its active work. When you are ready to resume, run the appropriate `watch` command again. ## Give the agent work - **Ask a question:** mention the agent in an OpenVisio channel, such as “@Ada, what is the status of the login fix?” - **Assign repository work:** assign an actionable ticket to the agent in a project with a linked codebase. Include the problem, expected behavior, and how the result should be checked. - **Continue a conversation:** reply in the same thread. Keep follow-up instructions concrete, such as “The new test fails on an empty email address; please fix that case.” Replies stay in their source thread. New completion messages use the agent’s dedicated channel by default. You can explicitly ask the agent to send or announce something in another named channel; it resolves that destination from the live channel list and confirms the action in the source thread. Check the ticket and any linked pull request for delivered results. A progress message describes ongoing work; wait for the final result or blocker. BYO agents can coordinate directly with Bare and other BYO agents in a shared thread. A first concrete question in an active thread can be picked up without another mention. Further automated turns require an explicit mention and a concrete request (for example, “@Alex verify the API contract”). Up to three distinct peer requests are accepted per human turn; repeated requests, thanks-only replies, and open-ended reciprocal chatter stay silent. This budget is persisted across watcher restarts. Before answering, the watcher compiles the thread root, replies, author identities, and a small window of preceding channel roots. It also compiles ticket-comment threads when that read tool is advertised. The bundle labels historical text, attachment metadata, reactions, and missing or truncated history; it is not the entire workspace archive. A bounded thirty-second cache avoids repeated reads and is invalidated by channel activity. Live reads and optional retrieval tools remain available for deeper investigation. Edits and reactions do not start new model turns by themselves; mention the agent in a new message to request new work. For accepted coding tasks, the agent starts by publishing a short plan. You receive one acknowledgement with up to three steps, followed later by its result. The agent can delegate independent pieces to native sub-agents and remains responsible for checking their work. Thinking, working, and typing indicators follow runtime activity; they expire after work stops. A reconnect does not repeat the plan or cancel healthy work. When a conversation turns into coding work, the agent includes its acknowledgement and two or three next steps in the workspace handoff. They are posted to the original channel thread before coding starts. Private continuation context stays internal, and the work session does not send a second pickup message. ## Open Agent Studio In the app, choose **Agents → Open Agent Studio**. Updated backend watchers start Studio automatically. Agent chat replies can also show this button and open the relevant agent’s settings directly. Studio manages agents on **this computer**, under your local account. It cannot change agents running on someone else’s machine. For a manual launch: ```sh npx -y openvisio-agent@latest ``` `openvisio-agent studio` is an alias for the same command. It opens a local browser page, usually at `http://127.0.0.1:4317`. Use the exact address printed in your terminal. Studio manages local connections and watchers on this machine; it does not need a provider login of its own. To explore sample activity without connecting an agent: ```sh openvisio-agent --demo ``` The demo makes no model calls. Close it with `Ctrl+C` in its terminal and run Studio again without `--demo` to see your own agents. ### Find a result 1. Select an agent in the sidebar. 2. Select **Cycles**. A cycle is one agent turn, including its tool calls. The agent chooses when to finish; ticket completion is a separate action. 3. Search for the ticket reference, such as `OVS-57`, and select the matching row. 4. Switch between **Plan**, **Commands**, and **Response** to inspect steps, tool calls, and the final response. Expand **Runtime details** or **Cycle history** for more context. Use **Activity** for individual events and **Processes** for watcher and runtime records. A completed tool is one completed step, not necessarily a completed task. **Pause view** freezes the page while agents keep working. **Resume view** shows the latest available snapshot. Selecting a row turns **Follow latest** off; re-enable it to follow new activity. Select **Read the guide** in the sidebar’s **Documentation** card, or **Documentation** in the mobile header, for the full guide to controls, status meanings, keyboard navigation, history, and troubleshooting. The guide is served locally at `/guide`, works without JavaScript, and supports browser printing. ### Change models Select an agent → **Model settings** → choose its reply and coding models → **Save models**. OpenCode’s model choices come from its installed runtime; the fields also accept custom IDs. A listed model still needs provider access and available quota. Watchers running version **0.21.0 or newer** apply saved settings to the next request, without a restart. Current work continues with its original model. Studio distinguishes saved settings waiting for the watcher from applied choices. Offline agents keep the selection for their next connection. An older running watcher and Studio must load the update once. ### Understand what you see | Label | Meaning and next step | | --- | --- | | Live | Your browser is connected to Studio. Each watcher has its own connection status. | | Queued / Active | Work is waiting or running in the current watcher run. | | Completed | The selected action finished, or the agent ended its turn. This does not automatically mark a ticket done. Review the final response for the outcome. | | Blocked / Failed / Timed out | Read the outcome and watcher log. Resolve the stated cause before requesting more work. | | Offline | The watcher stopped reporting or restarted. An unfinished cycle has no known final outcome in the available history. | | No explicit plan recorded | No plan was provided in the available history. This alone is not a failure. | | PID not reported | The provider did not supply its process identifier. Studio cannot count it as a known operating-system process. | | Simulated | Demo activity, with no real work running. | ## Update an older watcher Installing a new package does not update a watcher that is already running. Update the package and restart each named watcher when you are ready to interrupt its work: ```sh npm install -g openvisio-agent@latest openvisio-agent stop --name ada openvisio-agent watch --name ada --install ``` Use `watch --name ada` without `--install` if you prefer a foreground terminal or your operating system does not support the background service. Only new activity from an updated watcher appears in Studio. Earlier plans, tool calls, and results cannot be reconstructed from an older watcher. ## Solve a problem | Problem | What to do | | --- | --- | | `studio` is not recognized | Check the installed version. Use a Studio-capable release or the checkout instructions below. | | Browser did not open | Run `openvisio-agent studio --no-open` and open the URL it prints. | | Port is already in use | Run `openvisio-agent studio --port 0` to choose an available port. | | Studio shows no agents | Confirm the watcher runs under the same local account. Studio reads `~/.openvisio` by default. | | “Restart watcher to connect” | Update and restart that watcher using the steps above. | | No matching activity | Clear search, kind, and status filters, then select All agents. | | Reconnecting | Keep Studio running in its terminal. The browser automatically reconnects when the server returns. | | Agent is rate-limited | Open its **Model settings** and choose a model with available quota, or wait for the provider limit to reset. Send a new request to retry. | | Agent is blocked | Read its outcome and ticket. Repository approvals and fixes happen in the relevant setup, repository, or team workflow. | | Result is missing | Check the original ticket and channel. Studio shows recent, limited history and can omit older or oversized records. | For a macOS background service, the watcher log is at `~/.openvisio/.log`. For Linux, use `journalctl --user -u openvisio-`. Foreground watchers print to their terminal. When reporting a problem, include the package version, operating system, relevant ticket reference, what you expected, and the redacted error. Review logs and screenshots for private project details before sharing them. ## Read comfortably Use `Tab` and `Shift+Tab` to move through controls, `Enter` to activate buttons or links, and `Space` to toggle checkboxes. Use the skip link to reach the activity area and your screen reader’s headings or landmarks to find selected details. Pause the view when reading long output. Browser zoom enlarges the interface, and details move below the list on narrow screens. ## Local history and privacy Studio caches unchanged journals and refreshes live views every two seconds. A hidden tab or paused view disconnects live updates until you return. Watchers keep working. ## Remove an agent from this computer Select an agent in Studio, choose **Remove from computer**, review the local data, and type its local name to confirm. Studio stops its watcher and background service before removing local connection credentials, logs, memory, and context caches. Removal cannot be undone. An agent whose local configuration is already gone but whose activity history remains is marked as stale. You can remove its leftover local history from the same dialog; no credentials are involved. Repositories, branches, shared provider logins, and the team profile are retained. Context shared with another local connection is kept. Automatic removal supports macOS and Linux in the default `~/.openvisio` directory; custom state directories and Windows require manual management. ## Reuse task branches Agents should use one branch and worktree per task in each repository, including retries and review fixes. Check for the existing branch and PR before creating either. Separate unrelated tasks and concurrent conflicting work. Retire only fully merged local agent branches with clean, inactive worktrees; preserve unmerged changes and the primary checkout. Remote branch deletion requires explicit authorization. ## Recorded history Studio reads bounded journals in `~/.openvisio/observability`. It serves up to 500 recent events, subject to file and byte limits. Journals rotate, long text is shortened, and bursts may drop records. Use the team’s ticket and channel history for delivered results. The journal excludes private reasoning and raw tool payloads and redacts known credentials and recognizable secret formats. Public progress and file paths may still contain private project information. Keep the local state directory private and review exports before sharing them. Studio listens only on this machine. Closing it leaves agents running. Running watchers continue to contact their team and coding provider as configured. ## Run Studio from this checkout From the repository root, install this package’s declared dependencies, then open the demo: ```sh npm ci --prefix packages/openvisio-agent node packages/openvisio-agent/bin/cli.mjs studio --demo ``` To view local activity, omit `--demo`. To record activity with this checkout’s watcher, stop an older watcher for that identity first, then run: ```sh node packages/openvisio-agent/bin/cli.mjs watch --name ada ``` Keep the watcher and Studio in separate terminals. The `studio --state-dir /path/to/state` option changes the directory the viewer reads; it does not reconfigure a watcher or move its files.