# AI Agents [<span class="proPill"></span>](/curio/docs/#curio-professional) [<span class="sustainerPill"></span>](/curio/docs/#curio-sustainers)

The Curio CLI lets AI agents search, inspect, organize, and modify Curio projects. Agents that can run command-line tools work most efficiently with Curio’s bundled skills. Other AI clients can connect through the CLI’s Model Context Protocol (MCP) server.

!!! note "Agents, assistants, and chatbots"
    People often call products such as ChatGPT and Claude *chatbots* or *AI assistants* because conversation is their primary interface. In this guide, *AI agent* is a capability-based term for an AI client that can use tools—such as Curio’s CLI or MCP server—to take actions on your behalf. This includes coding agents such as Codex and Claude Code as well as more autonomous or persistent agent systems; it does not imply that the client runs unattended.

!!! note "Before you begin"
    Install and verify the CLI as described in [Installing the CLI](index.md). See [Using the CLI](working.md) for its commands, fields, transport modes, output, and errors.

## Choosing an Integration

| AI client | Recommended integration |
| --- | --- |
| ChatGPT desktop Work or Codex mode | Curio skills in `~/.agents/skills/` or `~/.codex/skills/` |
| Codex CLI | Curio skills in `~/.agents/skills/` or `~/.codex/skills/` |
| Claude Code CLI or Claude Desktop Code tab | Curio skills in `~/.claude/skills/` |
| Claude Desktop Chat or Cowork tab | Packaged Curio Claude Connector |
| Antigravity CLI or Desktop | Curio skills in the corresponding platform folder |
| ChatGPT web | Secure MCP Tunnel to the local Curio MCP server |
| Other MCP hosts | Curio’s local stdio MCP server |

Skills let a CLI-capable agent call `curio` directly. MCP hosts instead launch `curio mcp-server` and interact with its tools, prompts, and resources over standard input and output.

## AI Agent Skills

The Curio CLI bundles skill files that teach CLI-capable AI agents how to use the `curio` command effectively. Installed skills are symlinks to files under `/Library/Application Support/CurioCLI/skills/`, so they automatically reflect the latest installed CLI version.

Two skills are installed by `curio skills install ...`:

- **curio** — all commands, transport modes, fields, workflows, and error handling.
- **curio-query** — query language syntax, including boolean logic, tags, dates, comparisons, sorting, grouping, scopes, and limits.

A third bundled skill, **curio-mcp**, remains available as reference material for legacy or manual hosts that support uploaded skill packages. Claude Desktop users should normally install the MCPB connector with `curio claude install` instead of uploading `curio-mcp-upload.zip`.

Codex and Claude Code can choose a skill automatically when a request matches its description, or you can invoke one explicitly. In Codex, mention `$curio` or `$curio-query`, or type `/skills` and choose it from the Skills UI. In Claude Code, use `/curio` or `/curio-query`.

See OpenAI’s [Codex skills documentation](https://developers.openai.com/codex/skills) and Anthropic’s [Claude Code skills documentation](https://code.claude.com/docs/en/skills) for platform-specific details.

### Listing Platforms

Use `curio skills` or `curio skills list` to see available platforms and their current installation state:

```text
curio skills list
```

Each platform is reported as **installed**, **partial**, or **not installed**. Status is determined from the platform’s current skill symlinks rather than a separate manifest. Platforms are detected from their configuration directories, such as `~/.agents/` or `~/.claude/`. A partial installation identifies the missing skills.

### Installing Skills

Install the skills in the common folder used by most AI agents, including ChatGPT/Codex and Gemini/Antigravity but not Claude:

```text
curio skills install agents
```

Or install them for a specific platform:

```text
curio skills install claude
curio skills install codex
curio skills install agy
curio skills install antigravity
```

To detect installed platforms and install the skills for all of them:

```text
curio skills install --all
```

For example, `curio skills install agents` creates:

- `~/.agents/skills/curio` → `/Library/Application Support/CurioCLI/skills/curio`
- `~/.agents/skills/curio-query` → `/Library/Application Support/CurioCLI/skills/curio-query`

The command does not install the bundled `curio-mcp` reference skill as a platform symlink. Installation is idempotent, so running the command again is a safe no-op. If a file or directory not managed by the CLI already exists at a destination, the installer skips it and prints a warning rather than overwriting it.

### Uninstalling Skills

Remove skills for one platform:

```text
curio skills uninstall claude
```

Or remove every Curio CLI-managed installation:

```text
curio skills uninstall --all
```

Uninstall only removes symlinks that point to the CLI’s bundled skills directory. It does not remove files or symlinks created manually or by another tool.

### Browsing Bundled Skills

Open the bundled skills folder in Finder for inspection or manual copying to an unsupported platform:

```text
curio skills reveal
```

### Supported Platforms

| Platform | Skill directory |
| --- | --- |
| Agents (common folder used by most AI agents) | `~/.agents/skills/` |
| Claude Code | `~/.claude/skills/` |
| Codex | `~/.codex/skills/` |
| Antigravity CLI (`agy`) | `~/.gemini/skills/` |
| Antigravity Desktop | `~/.antigravity/skills/` |

Platforms that support manual skill copying can use `curio skills reveal`. The ChatGPT desktop app can use skills installed in either `~/.agents/skills/` or `~/.codex/skills/`.

### Skills Command Summary

```text
curio skills
curio skills install <platform>
curio skills install --all
curio skills uninstall <platform>
curio skills uninstall --all
curio skills reveal
```

## MCP Server

The same `curio` binary can run as a stdio MCP server:

```text
curio mcp-server
curio mcp-server --log ~/Library/Logs/curio-mcp.log
```

This mode is launched by an MCP host such as Claude Desktop. It is not a daemon or background service. The host starts the server on demand, communicates with it over stdin/stdout for the session, and then shuts it down.

The MCP server shares its command runner with the CLI so the two surfaces stay aligned.

| MCP tool | CLI equivalent | Purpose |
| --- | --- | --- |
| `curio_query` | `curio query` | Search figures using a Curio query expression. |
| `curio_get` | `curio get` | Read properties for a figure, idea space, Organizer item, or live selected target. |
| `curio_set` | `curio set` | Update writable properties. |
| `curio_create` | `curio create` | Create sections, folders, and idea spaces. |
| `curio_project_create` | `curio project create` | Create and open an empty project with a Default Section; a missing `.curio` extension is added. |
| `curio_move` | `curio move` | Move a figure or Organizer item. |
| `curio_batch` | `curio batch` | Run command batches with pseudo-variable references. |
| `curio_fields` | `curio fields` | List automation fields. |
| `curio_field_detail` | `curio fields <name>` | Describe one field and its usage. |
| `curio_docs` | bundled MCP docs | Read bundled MCP guidance. |
| `curio_tags` | `curio tags` | List project tags. |
| `curio_tags_create` | `curio tags create` | Create project/global keyword tags or named tag sets. |
| `curio_export` | `curio export` | Export a figure or live selection. |
| `curio_import` | `curio import` | Import files, content, or Spread PDF pages. |
| `curio_navigate` | `curio navigate` | Navigate to a project, section, idea space, or figure. |
| `curio_save` | `curio save` | Save the current or specified open project. |
| `curio_sections` | `curio sections` | List the section hierarchy. |
| `curio_assets` | `curio assets` | List figures and assets. |
| `curio_project_center` | `curio project-center` | List Project Center categories and project paths. |
| `curio_status` | `curio status` | Check app state, projects, transport, and selection availability. |
| `curio_help` | `curio help` | Show CLI help. |
| `curio_version` | `curio --version` | Show CLI version information. |
| `curio_update` | `curio update` | Check CLI update status. |

`curio_docs` supports the topics `overview`, `query-language`, `workflows`, and `transport-modes`. It provides read-only guidance for hosts that do not expose MCP resources directly.

`curio_project_center` uses Curio’s live Project Center when the app is available and otherwise reads the persisted Project Center and Recently Opened snapshots. Its `operation` is `categories` or `projects`; `projects` accepts an optional category UUID or title. Check `result.data_source` for `live` or `persisted`.

The server also exposes MCP-native resources at identifiers such as:

- `curio-mcp://docs/overview`
- `curio-mcp://docs/query-language`
- `curio-mcp://docs/workflows`
- `curio-mcp://docs/transport-modes`

It exposes prompts for workflows including `build_curio_query`, `inspect_curio_selection`, and `update_curio_item`.

!!! important "MCP resource identifiers"
    `curio-mcp://docs/...` identifiers belong to the MCP server. An MCP client passes them back to the server during `resources/read`; macOS and Curio do not open them. They are intentionally separate from Curio’s real `curio://` link scheme.

### Manual MCP Host Configuration

Claude Desktop users should normally install the [packaged connector](#chat-and-cowork-tabs). For other MCP hosts, use this stdio server configuration:

```json
{
  "mcpServers": {
    "curio": {
      "command": "/Library/Application Support/CurioCLI/bin/curio",
      "args": ["mcp-server"]
    }
  }
}
```

If your host expects only the server entry, use:

```json
{
  "command": "/Library/Application Support/CurioCLI/bin/curio",
  "args": ["mcp-server"]
}
```

Use `/Library/Application Support/CurioCLI/bin/curio` for host-launched MCP connections. This installed path remains stable across CLI updates.

## Integrating with AI Clients

### Shared Agents Folder

Many AI agent tools, including ChatGPT/Codex and Gemini/Antigravity but not Claude, use the common `~/.agents/` folder:

```text
curio skills install agents
```

This installs the Curio skills under `~/.agents/skills/`. Remove them with `curio skills uninstall agents`, or remove every CLI-managed Curio skill installation with `curio skills uninstall --all`.

### Codex CLI

For the [Codex CLI](https://learn.chatgpt.com/docs/codex/cli) (`codex`), install skills in the shared folder:

```text
curio skills install agents
```

Or install them only for Codex:

```text
curio skills install codex
```

The second command installs `curio` and `curio-query` under `~/.codex/skills/`. Launch Codex and type `$curio` or `$curio-query` to invoke one directly. Typing `$` displays installed skill completions, and `/skills` lists or manages them. Codex can also choose a matching skill automatically.

Remove the Codex-specific installation with `curio skills uninstall codex`.

### ChatGPT Desktop

The [ChatGPT desktop app](https://learn.chatgpt.com/docs/app) offers **Chat**, **Work**, and **Codex** modes.

!!! note "Which mode should you use?"
    - **Chat** mode cannot interact with the Curio app or invoke its installed skills.
    - Choose **Work** to use Curio skills with your projects—for example, to search, inspect, organize, modify, or produce deliverables.
    - Choose **Codex** for software development with codebase context and developer tools—for example, to write Python scripts that automate Curio workflows.

Install the skills in the shared folder:

```text
curio skills install agents
```

Or install them only for ChatGPT’s Codex mode:

```text
curio skills install codex
```

Verify the installation in ChatGPT by opening **Settings**, choosing **Plugins**, and selecting **Skills**. The Curio skills should appear when installed in either folder.

### ChatGPT Web

ChatGPT on the web can connect to Curio’s local stdio MCP server through OpenAI’s [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels). This avoids exposing a public inbound port on your Mac, but ChatGPT can still request Curio data through the tools you allow.

!!! warning "Unsupported feature"
    Curio does not support configuring or troubleshooting OpenAI’s Secure MCP Tunnel. It may involve your organization’s infrastructure, security policies, or firewall. Consult OpenAI’s documentation for assistance.

#### How the Tunnel Works

1. Curio provides `/Library/Application Support/CurioCLI/bin/curio mcp-server`.
2. OpenAI’s `tunnel-client` runs on your Mac and launches that command over stdio.
3. The client opens an outbound HTTPS connection to OpenAI’s tunnel service.
4. ChatGPT sends MCP requests through the tunnel, which forwards them to Curio locally.

#### Requirements

- The current Curio CLI.
- OpenAI access to Secure MCP Tunnel and ChatGPT custom connectors.
- A tunnel created in OpenAI Platform.
- A runtime OpenAI API key permitted to use that tunnel.
- OpenAI’s `tunnel-client` on the Mac that can run Curio.
- The Curio app running for current-selection, current-idea-space, navigation, import/export, or property-change workflows.

Read-only offline queries against a `.curio` file can use MCP tools that expose `project_path`. For selection-based work or project changes, run `tunnel-client` as your normal logged-in Mac user while Curio is open.

#### Setup Outline

Follow OpenAI’s Secure MCP Tunnel documentation to create the tunnel and install `tunnel-client`. Point the local stdio profile at Curio’s installed MCP server:

```text
export CONTROL_PLANE_API_KEY="sk-..."

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile curio \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "/Library/Application Support/CurioCLI/bin/curio mcp-server"
```

Validate and run it:

```text
tunnel-client doctor --profile curio --explain
tunnel-client run --profile curio
```

Keep `tunnel-client run --profile curio` running while ChatGPT uses the connector. In ChatGPT’s connector settings, create a custom connector, choose **Tunnel**, and select or paste its tunnel ID.

Start verification with read-only Curio tools such as status, fields, docs, and query. Enable tools that can change state—such as set, import, export, navigate, create, move, or batch—only when you are comfortable allowing those actions against local Curio projects.

### Claude Code CLI

For the [Claude Code CLI](https://claude.com/product/claude-code) (`claude`), install the skills with:

```text
curio skills install claude
```

This installs `curio` and `curio-query` under `~/.claude/skills/`. Launch Claude Code and type `/curio` or `/curio-query` to invoke a skill, or `/skills` to list installed skills. Claude Code can also choose a matching skill automatically.

Remove them with `curio skills uninstall claude`, or remove every CLI-managed installation with `curio skills uninstall --all`.

### Claude Desktop

[Claude Desktop](https://claude.com/download) has three tabs with different integration behavior:

- The **Code** tab behaves like Claude Code CLI and reads `~/.claude/skills/`.
- The **Chat** and **Cowork** tabs connect over MCP through the Curio Claude Connector.

#### Code Tab

Install the CLI-oriented skills just as you would for Claude Code:

```text
curio skills install claude
```

The Code tab can then call `curio` directly without an MCP layer.

#### Chat and Cowork Tabs

Install the packaged Curio Claude Connector:

```text
curio claude install
```

This creates an `.mcpb` connector package, opens it in Claude Desktop, and lets Claude install Curio’s tool and prompt metadata. No `claude_desktop_config.json` edit or manual skill upload is required.

To create the package without opening it immediately:

```text
curio claude package
curio claude package --output ~/Desktop/curio.mcpb
```

The package command reveals the `.mcpb` file in Finder by default. Add `--no-reveal` when scripting package creation.

##### Troubleshooting the Claude Connector

Verify the CLI and connector prerequisites with:

```text
curio claude doctor
```

The command checks the installed `curio` path, connector resources, Claude Desktop availability, old `mcpServers.curio` entries, and whether the MCP server answers an `initialize` request.

Claude Desktop groups Curio tools into read-only and write/delete categories. You can set tools such as **Query**, **Get**, **Docs**, and **Status** to **Always Allow** while leaving tools such as **Set**, **Import**, **Export**, and **Navigate** at **Needs Approval**.

To uninstall the packaged connector:

1. In Claude Desktop, click **Customize** in the sidebar.
2. Click **Connectors**.
3. Select the Curio connector.
4. Click **Uninstall**.

!!! note "Uninstall from Customize"
    Do not uninstall the packaged connector through **Settings > Connectors**. That path may not remove it reliably; use **Customize > Connectors**.

#### Manual Claude Desktop Configuration

The packaged connector is preferred. For the older manual setup, edit `~/Library/Application Support/Claude/claude_desktop_config.json` and add:

```json
{
  "mcpServers": {
    "curio": {
      "command": "/Library/Application Support/CurioCLI/bin/curio",
      "args": ["mcp-server"]
    }
  }
}
```

If the file already contains `preferences` or other top-level objects, add `mcpServers` beside them with valid JSON punctuation.

To remove a manual configuration, quit Claude Desktop, remove the `curio` entry from `mcpServers`, and relaunch. Remove the `mcpServers` key too if it is then empty.

!!! note "Edit the configuration directly"
    Do not use the Settings UI’s **Disconnect** button for a classic manual `mcpServers.curio` entry. The UI can report “Invalid server ID format” because the entry has a name rather than a UUID or `mcpsrv_*` ID.

### Antigravity CLI

For Antigravity CLI (`agy`), formerly Gemini CLI (`gemini`), install the skills with:

```text
curio skills install agy
```

This installs them under `~/.gemini/skills/`. Launch `agy` and type `/curio` to see the Curio skills or `/skills` to list installed skills.

Remove them with `curio skills uninstall agy`, or remove every CLI-managed installation with `curio skills uninstall --all`.

### Antigravity Desktop

Antigravity Desktop uses a separate skill directory:

```text
curio skills install antigravity
```

This installs the skills under `~/.antigravity/skills/`. Remove them with `curio skills uninstall antigravity`.

## Working with AI Agents

Once an integration is installed, begin with a first prompt to see how Curio and the agent work together. Many focused tasks can then be requested with a single ordinary-language instruction. For more complex, multi-step work, use the planning workflow that follows.

### First Prompts

For agents using the Curio skills, such as ChatGPT Work or Codex, Codex CLI, Claude Code, Claude Desktop’s Code tab, and Antigravity:

> What can you do with the Curio skills available to you? Summarize what you can do with my Curio projects.

For an MCP client such as Claude Desktop’s Chat or Cowork tab:

> What Curio MCP tools, prompts, and resources are available? Summarize what you can do with my Curio projects.

After the agent confirms its capabilities, try a read-only request:

> Check whether Curio is running, then summarize the selected figure or active idea space without changing anything.

Or explore a project file without opening it in Curio:

> Inspect `~/Documents/MyProject.curio` in read-only mode. Summarize its sections, major idea spaces, and active tasks.

### For Complex Workflows: Plan, Refine, Then Act

Some outcomes involve enough decisions or coordinated changes that they cannot be captured reliably in one instruction. You still do not need to know Curio’s commands or specify every implementation detail yourself. Describe the outcome, then let the agent use Curio’s published skills to develop the command-level plan with you:

1. **Describe the desired outcome in ordinary language.** Explain what you want to accomplish, which project or selection is involved, and any important constraints.
2. **Ask the agent to propose a plan without changing anything yet.** The agent can inspect available Curio capabilities, identify the necessary steps, and surface questions or assumptions before taking action.
3. **Refine the plan conversationally.** Add details, correct assumptions, change the sequence, or ask the agent to make the plan more thorough. Continue until the proposed result and workflow look right.
4. **Say “Do it.”** This clearly tells the agent that the planning phase is complete and it may carry out the approved workflow.

This approach lets you begin with a simple goal while the agent expands it into a detailed, reliable sequence of skills-based Curio commands. It also gives you an opportunity to review the scope and catch misunderstandings before anything changes.

For example:

> I want to prepare this Curio project for a screencast that demonstrates how research moves from an inbox into an organized presentation. Propose a detailed plan using the Curio skills, but do not change anything yet.

After reviewing the response, refine the plan in the same conversation. When you are satisfied, reply:

> Do it.

### Prompting Tips

- **Name the scope.** Say whether to use the running Curio app, the current selection, the active idea space, or a specific `.curio` project path.
- **State whether changes are allowed.** Ask for read-only inspection when you do not want modifications. For changes, say whether the agent may act immediately or should propose a plan first.
- **Ask for a preview.** For bulk edits, request the matching item count and a short sample before approving the mutation.
- **Describe the result, not the command.** The installed skills teach the agent the command syntax. A request such as “find overdue active tasks, group them by project, and summarize blockers” is usually enough.
- **Be explicit about saving.** Ordinary imports and other live mutations can be grouped without forcing a save after each command; ask the agent to save the affected Curio project once after the completed workflow.
- **Use stable targets.** For repeatable automation, ask the agent to use UUIDs or identifiers after discovery instead of relying only on titles.
- **Separate inspection from action.** A two-step workflow—first inspect, then approve changes—makes large or ambiguous jobs easier to verify.
- **Keep approvals for risky tools.** In MCP clients, consider automatic approval only for read-only tools and require confirmation for tools that create, update, move, import, export, or navigate.

### Example Workflows

> Find all active tasks due in the next seven days, group them by tag, and summarize the three most urgent items. Do not change the project.

> Examine the current selection, explain which properties can be changed, and wait for my approval before editing anything.

> Find figures tagged `Research/Inbox`, show me a five-item sample, then ask whether I want you to move the matches into the Research idea space.

> Create a section named “Client Work” with an idea space for each client in this list. Show the proposed structure before creating it, then save the project when finished.

> List every file-backed asset in this project and produce a manifest with its title, section path, Organizer path, and asset file path. Do not modify any files.

> Help me write and test a reusable Curio query for overdue, incomplete, high-priority tasks. Explain the query before running it.

### Creating Standalone Scripts

An AI agent can also turn a recurring Curio workflow into a standalone shell or Python script that you save to disk and run whenever you need it. Describe the result you want in ordinary language; the agent can use Curio’s skills to choose the appropriate commands, parse their JSON output, handle errors, and document how to run the finished script.

!!! note "The agent creates the script; the CLI runs it"
    Once the script has been created, it calls the `curio` CLI directly. Running it does not require ChatGPT, Codex, Claude, an MCP connection, or another AI agent. The agent is only involved while creating, testing, or later improving the script.

The finished script becomes an ordinary reusable automation. You can launch it yourself, schedule it with tools such as `launchd`, or call it from another workflow using only its normal runtime—such as the shell or Python—and the installed Curio CLI.

The script can be as simple as monitoring project backup folders and reporting missing or stale backups, or as sophisticated as querying several Curio projects and generating an interactive dashboard. For example:

> Write a Python script that checks my Curio project backup folder, reports projects without a recent backup, and exits with an error if any backup is more than seven days old. Save the script to disk and include usage instructions.

> Build a local dashboard that queries my Curio projects for active tasks, upcoming due dates, and project status. Propose the data model and interface first, without creating files yet.

A coding agent such as Codex or Claude Code is especially useful for this work because it can create and refine the script directly in a working folder, run it, inspect failures, and add tests. If the result includes a web interface, a coding agent with browser tools may also be able to open the dashboard, exercise its controls, and verify the rendered output.

!!! tip "Start with read-only testing"
    When possible, have the agent develop and test against a copied project or Curio’s read-only `--project` mode first. Before allowing a script to change a live project, ask the agent to show which commands will mutate data, add clear error handling, and verify that the intended project is targeted. Live scripts that make changes should finish with `curio save`.