AI Agents

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.

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 and Anthropic’s Claude Code skills documentation for platform-specific details.

Listing Platforms

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

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:

curio skills install agents

Or install them for a specific platform:

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:

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:

curio skills uninstall claude

Or remove every Curio CLI-managed installation:

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:

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

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:

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 or inspect a live selected target.
curio_get	curio get	Read properties for a figure, idea space, or Organizer item.
curio_set	curio set	Update writable properties.
curio_create	curio create	Create sections, folders, and idea spaces.
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_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.

Manual MCP Host Configuration

Claude Desktop users should normally install the packaged connector. For other MCP hosts, use this stdio server configuration:

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

If your host expects only the server entry, use:

{
  "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:

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 (codex), install skills in the shared folder:

curio skills install agents

Or install them only for Codex:

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 offers Chat, Work, and Codex modes.

Install the skills in the shared folder:

curio skills install agents

Or install them only for ChatGPT’s Codex mode:

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. This avoids exposing a public inbound port on your Mac, but ChatGPT can still request Curio data through the tools you allow.

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:

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:

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 (claude), install the skills with:

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 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:

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:

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:

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:

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.

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:

{
  "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.

Antigravity CLI

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

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:

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. After a live mutation workflow, ask the agent to save the affected Curio project.
• 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.

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.