Agent Studio user guide

Open Studio

Agent Studio is a local viewer for bring-your-own (BYO) agents connected to an OpenVisio team. It shows recorded actions from Claude Code, Codex, OpenCode, Gemini CLI, and Qwen Code watchers on this machine.

In the OpenVisio app, open Agents → Open Agent Studio. Agents can also include this button in chat replies. Updated backend watchers start Studio automatically on this computer.

You can also open Studio manually with one command:

npx -y openvisio-agent@latest

Your browser opens the local address printed in the terminal, usually http://127.0.0.1:4317. Keep that terminal running while you use Studio. openvisio-agent studio is an alias for the same command.

To explore without connecting an agent:

openvisio-agent --demo

The demo uses clearly labeled sample activity. It makes no model calls. To return to your agents, press Ctrl+C in the Studio terminal and run the command again without --demo.

Change models

Select an agent in the sidebar, choose Model settings, select its reply and coding models, then choose Save models. Model fields let you search the runtime’s choices or enter a custom model ID.

Updated watchers load saved choices immediately and apply them to the next request without a restart. Work already running continues with its original model. After a request starts, Studio shows the model the runtime actually selected. Offline agents retain the selection for their next connection.

Model choices come from the selected runtime’s local catalog. Listing a model does not guarantee credentials or available quota. If a model is rate-limited, choose one with available quota or retry after the provider’s limit resets.

Studio controls agents configured on this computer. An agent running on another teammate’s computer must be managed there.

Remove a local agent

Select an agent, choose Remove agent, review the local data, and type its local name to confirm. Studio stops its watcher and background service, then removes its local connection credentials, logs, memory, and cached context. This cannot be undone.

If an agent’s local configuration is already gone but its activity history remains, it is marked as stale. Remove its leftover local history from the same dialog; no credentials are involved.

Repositories, branches, shared model-provider logins, and the team’s agent profile stay in place. Context shared with another local connection is retained. Removal is available on macOS and Linux for the default local agent storage; custom state directories and Windows require manual management.

Show your agents

A watcher is the local program that listens for assignments and messages, then starts your coding agent when work arrives. Studio displays what the watcher records.

After registering your backend agent in OpenVisio, copy its identifier and API key. In Studio, choose Connect agent, select the runtime, enter both credentials, and choose Connect and start. Studio resolves the agent name from OpenVisio, saves the private connection, and starts the watcher for you.
Your agent should appear in the sidebar. Select its name to see its activity.

If the selected runtime is not installed or signed in yet, the connection is still saved. Install and sign in to that runtime, then choose Start watcher. Studio installs its background watcher and starts it with the current package and saved model settings.

Use Stop watcher to take an agent offline and Restart watcher after changing its runtime installation or troubleshooting a connection. Restarting preserves its configuration and model choices. While connected and idle, the watcher waits for WebSocket or local settings events without starting a coding runtime or polling project activity.

Watcher controls are available for locally configured agents in the default local agent storage on macOS and Linux. Their earlier activity cannot be reconstructed.

Find and inspect work

Select an agent, or choose All agents.
Choose Activity for individual actions, Cycles for groups of work, or Processes for watchers and coding runtimes.
Search for a ticket such as DEMO-77, an action, or a recorded file path. Use the kind and status filters to narrow the list.
Select a row. Its details appear beside the list, or below it on a smaller screen.

A cycle is one unit of agent work. It can include a plan, several tool calls, progress updates, and a final response. Expand Cycle history to review its recorded sequence.

Switch between Plan, Commands, and Response for steps, tool calls, and visible output. The Task activity card groups recorded work on the same ticket by agent; select an agent in the diagram to inspect its cycle. Expand Runtime details for model and timing information.

No explicit plan recorded means the provider did not send a plan in the available history. A missing process ID means the provider did not report that operating-system identifier. Neither message alone means the work failed.

The process summary counts distinct reported process IDs associated with connected watchers. It is not a system-wide process monitor. The demo deliberately shows no real process count.

Tasks and conversation recall

Tell your agent “I have a task for you” or ask it to check its assignments. The agent has a live task lookup, a searchable tool guide, and short skills it can load when helpful. A lookup does not itself claim, start, or complete a task.

Ask about an earlier decision, such as “What did we decide about credential storage?” The agent can search recorded conversations by meaning and return to the original channel or thread for verification. It searches messages it has observed or fetched, so conversations it has never read may be missing.

The first semantic search downloads a local embedding model. Keyword search stays available while it loads. Later inference runs on this computer without an embedding API key. The agent chooses what context to retrieve and when to end its turn.

Understand statuses

Live: Your browser is connected to the local Studio server. Check each agent’s own status to see whether its watcher is connected.
Queued / Active: Work is waiting to start, or the current watcher has recorded it as running.
Completed: The selected action finished, or the agent ended its turn. Ending a turn does not automatically mark its ticket done. A completed tool is only one step; inspect the cycle’s final response and the ticket for the overall result.
Blocked / Failed / Timed out: Read the cycle’s Outcome and final response, then check the ticket or watcher log for the cause. Studio has no retry or approval button.
Cancelled / Skipped: The work was stopped or did not proceed. These are separate from successful completion.
Idle / Connecting / Recovering: A coding runtime is waiting, connecting, or attempting recovery. These describe the runtime’s last recorded state.
Continued in workspace: The agent requested its coding workspace and carried the same request and context into a work session. Follow that session for the final response.
Offline: The watcher stopped reporting, exited, or was replaced by a newer run. An unfinished cycle’s outcome is unknown; offline does not mean completed or failed.
Simulated: This record belongs to the demonstration. No real agent is working on it.

Pause and follow

Pause view freezes the displayed snapshot so you can read without changes. Your agents keep working. Resume view displays the latest available snapshot.

Follow latest selects the newest matching activity as updates arrive. Selecting a row turns following off so you can inspect that item. Turn it on again when you want to follow new activity.

Show earlier activity reveals more of the available history. Search and filters apply to that same limited history.

Closing the browser or pressing Ctrl+C in the Studio terminal leaves watchers running. To stop an agent, use a separate terminal:

openvisio-agent stop --name ada

Keyboard and reading

Use Tab and Shift+Tab to move between controls. Use Enter to activate links and buttons; Space also activates buttons and checkboxes. Native select menus use your browser’s keyboard controls.

The first focusable link skips navigation. Controls have text labels, and statuses use words as well as color. Use your screen reader’s headings and landmarks to find the activity list, selected details, or guide sections.

Pause the view before reading a long result. Browser zoom can enlarge the interface; the details panel moves below the activity list on narrower screens. This guide works without JavaScript and can be printed or saved as a PDF using your browser’s print command.

Troubleshooting

“Unknown command: studio”

Check openvisio-agent --version. Studio requires version 0.20.0 or newer. Update with npm install -g openvisio-agent@latest. To run from a local checkout, use:

node packages/openvisio-agent/bin/cli.mjs studio

Run this from the repository root after installing the package’s dependencies.

No agents or “Restart watcher to connect”

Confirm the watcher uses the same local account as Studio. After updating the watcher package, stop the named watcher and start it again. Replace ada with your agent name:

openvisio-agent stop --name ada
openvisio-agent watch --name ada

Stopping interrupts that agent’s work. For a background service on macOS or Linux, use openvisio-agent watch --name ada --install instead of the second command. Studio reads ~/.openvisio by default; --state-dir /path/to/state selects a different directory to read.

No matching activity

Choose Clear filters or select All agents and clear the search. If there is still no activity, check whether the watcher has received work since its update.

Reconnecting or the page will not open

Keep the Studio terminal running and open the exact URL it printed. The browser reconnects automatically when the server returns. If automatic browser opening fails, run openvisio-agent studio --no-open and open the printed address yourself.

Port already in use

Choose another available local port:

openvisio-agent studio --port 0

A result or older event is missing

Studio shows a bounded recent history. Look at the original ticket and channel for delivered results. Watcher logs are at ~/.openvisio/<agent>.log for the macOS service, or journalctl --user -u openvisio-<agent> for the Linux service. A foreground watcher prints to its terminal.

History and privacy

Live views refresh at most every two seconds and reuse unchanged journal data. Pausing the view or hiding its browser tab disconnects live updates; returning reconnects automatically. Agents keep working while the view is paused.

Studio reads local journals under ~/.openvisio/observability. The viewer serves up to 500 recent events from a bounded set of journal files. Logs rotate, large text can be shortened, and bursts can drop records. This is a recent activity view, not a complete audit archive.

The journal records visible plans, tool metadata, and public output. Private reasoning and raw tool payloads are excluded. Known credentials and recognizable secret formats are redacted, but visible output can still include project text and file paths. Review it before sharing a screenshot or journal.

Studio’s server accepts local connections only. Saving models changes only the selected agent’s local model settings; it does not start a model call or modify your team. Your running watchers continue to use their configured team and provider connections.

Return to Agent Studio