Working with AI agents

Covo is a workbench for the AI agent you already use. It is not an agent and never calls a model. Git protects your code; Covo protects the code and the database together, so you can let an agent update plugins or run migrations and still go back.

Work with an agent

In the app, open a site and choose Work with an Agent… From the terminal:

covo agent start shop
covo agent start shop --tool codex --terminal iTerm

--tool takes claude, codex, gemini, cursor-agent, cursor or copilot. --terminal takes Terminal, iTerm or Ghostty. Covo remembers the last agent and terminal you used.

Covo then:

1. Opens an agent session for the site and waits until the starting snapshot of files and database is saved.
2. Lets agents change that site until the session closes. This temporary permission shows in Settings → AI Agents.
3. Starts the agent in the site’s folder in a new terminal window (Cursor opens the folder), with Covo’s MCP server connected and a short description of the site: its address, PHP version, database and the recommended workflow.

Nothing is written into your project folder. Gemini CLI and Cursor need Covo in their own settings file: Covo asks first and backs the file up (--connect agrees in advance). Covo finds agents already installed on your Mac and never installs one.

Agent sessions

While an agent works on a site, Covo keeps the site’s starting state until you decide what to do with the changes.

A session opens when an agent started from Covo begins, when an agent starts Covo’s MCP server inside the site’s folder, or at the first change an agent makes through Covo. For an agent that does not use Covo’s MCP server, open one yourself before it starts:

covo agent session open shop
covo agent session list        # open sessions (--all: recent closed ones too)
covo agent session show shop   # starting snapshot and checkpoints

Inside a session Covo also takes a checkpoint before risky actions, such as plugin and core updates, database imports, search-replace, Laravel migrations, Composer installs and a change of PHP version. A session keeps its newest 20 checkpoints.

When the agent is done, the app shows a banner on the site with What Changed…, Keep Changes and Undo All…:

covo agent session keep shop     # keep the changes
covo agent session revert shop   # undo everything since the start (asks; --yes)

Keep closes the session. The starting snapshot stays as an ordinary snapshot, so you can still go back for a while.

Undo All puts the files and the database back to how they were at the start. It also undoes changes you made yourself during the session, since Covo cannot tell who changed what. .git and node_modules are never touched, and the current state is saved first as a pre-restore snapshot, so you can undo the undo.

A session with no activity for 24 hours closes by itself and keeps the changes. Change this in Settings → AI Agents or with covo agent idle 48 (0 means never).

Agents can see their session but cannot keep or undo it. That decision stays with you.

What changed

covo agent diff shop                        # files and tables since the start
covo agent diff shop --file wp-config.php   # one file's diff

You see files added, modified and deleted, and for each database table the rows inserted, updated and deleted, plus tables added, dropped or altered. When an agent asks for the same diff, passwords, keys and salts in files like .env and wp-config.php are masked.

Tools for checking the work

Agents can check their work with read-only tools, which you can also run yourself:

covo fetch shop /checkout/              # status, redirects, text and PHP errors of that request
covo mail list --to buyer@example.com   # mail PHP sent, caught by Mailpit
covo mail show                          # the newest message: text and links
covo db query shop "SELECT option_value FROM wp_options WHERE option_name = 'home'"

covo db query runs one SELECT, SHOW, DESCRIBE, EXPLAIN or WITH statement as a user that can only read, limited to 10 seconds and 500 rows.

Connecting an agent with MCP

To use Covo from an agent outside Work with an Agent, add Covo’s MCP server to the agent’s settings. Settings → AI Agents → Connect… does it for you, or:

covo agent tools             # agents on this Mac and whether Covo is connected
covo agent connect claude    # also codex, gemini, cursor, claude-desktop

Covo backs up the agent’s settings file first and leaves a file alone if it is not valid JSON. To add it by hand in Claude Code:

claude mcp add covo -- covo mcp

Settings → AI Agents shows the exact lines, with the full path of the covo inside the app.

Read-only by default

Connected agents can always read: sites, logs, PHP versions, databases, snapshots. They can change a site only where you allow it:

covo mcp allow shop    # changes to one site
covo mcp allow '*'     # everywhere, including adding sites, start and stop
covo mcp deny shop
covo mcp status        # what is allowed
covo mcp log -n 50     # what agents did, refused attempts included

Every change happens inside a session and is written to the log. No tool takes a password.

What agents can never do

There is no MCP tool to remove a site, a database, a snapshot or a group, and none to push to a server: those stay with you. Agents can pull from production but never push. wp shell, wp --prompt and artisan tinker are refused because they need a terminal.

Claude Code plugin

The Covo plugin for Claude Code (available once the Covo repository is public) connects Covo and teaches Claude the workflow: check permissions first, work inside the session, verify with fetch_page, logs and mail, and show the diff before finishing.

/plugin install covo --marketplace getcovo/covo

Codex, Cursor and Gemini read an AGENTS.md (Gemini: GEMINI.md) from the project. Covo never writes one into your repository; add one yourself if you want those agents to follow the same workflow. For what Covo itself touches on your Mac, see What Covo touches.