AI Agent Integration

CommandIt works with AI coding assistants like Claude Code, Codex, Cursor, and more. Once connected, your AI can search, use, and create snippets — making every snippet in your library a tool your AI can call.

Quick Setup

1. Install the CLI

Open Settings → Agent Integration and click Install CLI, or run in Terminal:

commandit install-cli

This creates a commandit command available system-wide.

To uninstall:

commandit install-cli --uninstall

2. Connect Your AI Tool

Open Settings → Agent Integration and copy the setup instruction for your platform:

Terminal agents (CLI):

Platform	Command
Claude Code	claude plugin add chriscox/commandit-plugin
Codex	codex mcp add commandit -- commandit mcp
Gemini CLI	gemini mcp add commandit -- commandit mcp

Editor agents (JSON config):

Platform	Config file	Key
Cursor	~/.cursor/mcp.json	mcpServers
Windsurf	~/.windsurf/mcp.json	mcpServers
VS Code	.vscode/mcp.json	servers

For editor agents, add the JSON from Settings to the config file. Example for Cursor/Windsurf:

{
  "mcpServers": {
    "commandit": {
      "command": "commandit",
      "args": ["mcp"]
    }
  }
}

Alternatively, use the CLI to write the config automatically:

commandit install-mcp --cursor     # Writes to ~/.cursor/mcp.json
commandit install-mcp --windsurf   # Writes to ~/.windsurf/mcp.json
commandit install-mcp --claude     # Writes to Claude Desktop config

That’s it — your AI agent now has access to your snippet library.

What Your AI Can Do

Once connected, your AI can work with your snippets through natural conversation. Here are real-world scenarios:

Search and use snippets

You: “Deploy to staging” AI: searches your snippets → finds “K8s Deploy” → fills in env=staging, replicas=3 AI: “Running: kubectl apply -f deployment.yaml --namespace staging”

Your AI finds the right snippet by meaning, not just keywords. Ask for “deploy” and it finds your snippet named “K8s Apply” even without an exact match.

Fill arguments automatically

You: “Set up a Redis container on port 6380” AI: finds your Docker Run snippet → fills image=redis, port=6380 AI: “Here’s the command: docker run -d -p 6380:6379 --name redis redis:alpine”

The AI understands your intent and fills template arguments ({port}, {image}, {name}) from context — no manual substitution needed.

Discover your library

You: “What Git commands do I have?” AI: searches by category → lists all snippets in your Git category AI: “You have 12 Git snippets: interactive rebase, bisect, cherry-pick…”

Browse by category, tag, or just describe what you’re looking for.

Create new snippets

You: “Save that complex find command I just ran as a snippet” AI: detects arguments, generates description, suggests category and tags AI: “Created ‘Find & Delete Old Logs’ with args: {days}, {extension}”

Your AI builds complete snippets with detected arguments, descriptions, and organization — not just raw text.

Use snippets in your editor

You (in Cursor): “Add the nginx reverse proxy config for this project” AI: searches your ops snippets → finds Nginx Reverse Proxy → renders with project values

Editor agents paste snippets directly into your files with arguments filled from your project context.

Set up more integrations

You: “Set up CommandIt for Cursor” AI: finds the MCP setup snippet in your library → shows the JSON config

The setup instructions are themselves CommandIt snippets. Once one agent is connected, it can help you connect the others.

Full capability list

• Search your snippets — “Find my Docker commands”
• Use a snippet — “Run my deploy script with port 8080”
• Create snippets — “Save that kubectl command I just ran as a snippet” (Plus)
• Browse your library — “What categories do I have?”
• Describe a snippet — “What args does my deploy snippet take?”
• Generate commands — “Create a command to compress all PNGs recursively” (Plus)
• Explain commands — “Explain what this find command does” (Plus)
• Enhance snippets — “Add metadata to all my snippets missing descriptions” (Plus)

CLI Commands

Use these in Terminal or let your AI call them:

Free

Command	What it does
commandit search "query"	Search snippets
commandit list	List all snippets
commandit get <id>	View a snippet
commandit describe <id>	See a snippet’s args and schema
commandit categories	List categories
commandit tags	List tags
commandit version	Show CLI version, schema, and database info
commandit detect-args --template "..."	Detect arguments in a command template
commandit describe-command --command "..."	Generate an AI description for a command
commandit categorize --command "..."	Suggest the best category for a command

Plus

Command	What it does
commandit render <id> --arg key=value	Fill in a snippet’s args
commandit paste <id> --arg key=value	Fill and paste into your active app
commandit create --name "..." --template "..."	Create a new snippet
commandit history	View execution history
commandit generate "description"	Generate a shell command from natural language
commandit explain "command"	Explain a command with flag breakdown
commandit enhance --command "..."	Fill all metadata (name, desc, args, tags, category)
commandit improve --command "..."	Polish and optimize a command template
commandit suggest-tags --command "..."	Suggest relevant tags for a command

JSON output
Add --format json for machine-readable output (automatic when piped).

MCP Server

CommandIt includes a built-in MCP (Model Context Protocol) server. All supported platforms connect through MCP, giving your AI native access to your snippet library.

MCP Tools

Tool	Tier	What it does
commandit_search	Free	Search snippets by query, category, or tags
commandit_describe	Free	Get a snippet’s schema (args, types, defaults)
commandit_list_categories	Free	List categories with snippet counts
commandit_detect_args	Free	Detect arguments in a command template
commandit_describe_command	Free	Generate an AI description for a command
commandit_categorize	Free	Suggest the best category for a command
commandit_render	Plus	Fill args and return rendered text
commandit_create	Plus	Create a new snippet (supports dry_run)
commandit_paste	Plus	Render and paste into the active app
commandit_generate	Plus	Convert natural language to a shell command
commandit_explain	Plus	Explain a command with flag breakdown and warnings
commandit_enhance	Plus	Fill all metadata for a command or existing snippet
commandit_improve	Plus	Polish and optimize a command template
commandit_suggest_tags	Plus	Suggest relevant tags for a command

MCP Resources

Your AI can also read these resources directly:

• commandit://snippets — your full snippet library
• commandit://snippets/{id} — a specific snippet with args schema
• commandit://history — recent execution history (Plus)

Advanced MCP Flags

commandit mcp --read-only          # Non-mutating tools only
commandit mcp --tools search,render  # Limit available tools

Supported Platforms

Platform	Setup	Type
Claude Code	CLI command	MCP server
Codex (OpenAI)	CLI command	MCP server
Gemini CLI	CLI command	MCP server
Cursor	JSON config	MCP server
Windsurf	JSON config	MCP server
VS Code	JSON config	MCP server

Troubleshooting

CLI not found after install

The installer automatically adds ~/.local/bin to your shell PATH. Restart your terminal for the change to take effect, then verify:

commandit version

If it’s still not found, check that your shell profile has the PATH entry:

grep ".local/bin" ~/.zprofile ~/.zshrc ~/.bash_profile 2>/dev/null

If missing, add it manually:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile

MCP server not connecting

1. Test the server directly: Run commandit mcp in Terminal. It should wait for input (no error). Press Ctrl+C to stop.
2. Check your config: Make sure the JSON is valid (no trailing commas). Use the setup instruction from Settings → Agent Integration.
3. Restart your editor: Most editors require a restart after changing MCP config.
4. Check your PATH: Run which commandit in Terminal. If not found, restart your terminal or re-run the CLI install from Settings > Developer Tools.
5. Use install-mcp: For maximum reliability, run commandit install-mcp --cursor (or --windsurf, --claude) which writes the absolute binary path to the config file.

Paste not working

CommandIt.app must be running for commandit paste to work. The CLI sends paste requests to the running app via macOS inter-process communication.

”Plus required” error

Read-only commands (search, list, describe) and free AI actions (detect-args, describe-command, categorize) are free. Render, paste, create, and Plus AI actions (generate, explain, enhance, improve, suggest-tags) require a Plus subscription.

AI commands not responding

AI CLI commands (generate, explain, enhance, etc.) require the CommandIt app to be running. They route through the app’s AI provider via inter-process communication, so make sure:

• CommandIt.app is open
• AI is configured in Settings (on-device or cloud provider)
• The request hasn’t timed out (30-second timeout for AI actions)

Removing the integration

CLI-managed agents — use the editor’s own CLI:

claude mcp remove commandit
codex mcp remove commandit
gemini mcp remove commandit

JSON-configured editors — delete the commandit entry under mcpServers in:

• ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop)
• ~/.cursor/mcp.json
• ~/.windsurf/mcp.json

Uninstall the CLI:

commandit install-cli --uninstall
rm -f ~/.local/bin/commandit
rm -rf ~/.local/Frameworks/SQLCipher.framework ~/.local/Frameworks/Sparkle.framework

For a complete uninstall (including app data, Keychain, and shell profile changes) see Uninstall.