agent-open

A utility similar to the open npm package, but for launching coding agents (CLI tools, editors, or web agents) with a prompt.

Installation

npm install -g agent-open
# or
npx agent-open <prompt>

Programmatic API

import { agentOpen, api } from 'agent-open';

// Auto-detect and launch the first available agent
await agentOpen('aider', 'Add unit tests');

// Launch Claude Code CLI with files
await agentOpen('claude', 'Explain this code', { files: ['index.ts'] });

// Open a browser-based agent
await agentOpen('browser', 'Write a React hook', { url: 'https://claude.ai/?q={prompt}' });

// With working directory
await agentOpen('aider', 'Refactor this module', { cwd: '/path/to/project' });

// Typed programmatic API via Padrone
await api.claude({ prompt: 'Explain this code', files: ['index.ts'] });
await api.aider({ prompt: 'Add unit tests' });
await api.ls({ all: true });

agentOpen(agent, prompt, options?)

| Parameter | Type | Description | |-----------|------|-------------| | agent | string | Agent identifier (see supported agents below) | | prompt | string | Prompt to send to the agent | | options | AgentOptions | Optional configuration |

AgentOptions

interface AgentOptions {
  cwd?: string;       // Working directory (default: process.cwd())
  files?: string[];   // Files to include (for agents that support it)
  terminal?: boolean; // Reserved for future use
  url?: string;       // URL template for browser agent ({prompt} placeholder)
}

CLI Usage

# Root command — auto-detects the first installed agent (respects configured default)
npx agent-open "Explain this code"

# Interactively pick an agent
npx agent-open -i "Explain this code"

# Launch a specific agent
npx agent-open claude "Explain this code"
npx agent-open aider "Refactor this module"
npx agent-open opencode "Add unit tests"
npx agent-open gemini "Write tests"
npx agent-open interpreter "Write a script to sort files"
npx agent-open cursor "Add type annotations"
npx agent-open windsurf "Review this function"
npx agent-open vscode "Review this PR"
npx agent-open zed "Add documentation"
npx agent-open copilot "Suggest a fix"
npx agent-open cody "Explain this code"
npx agent-open chatgpt "Write a React hook"
npx agent-open browser "Write a React hook" --url "https://claude.ai/?q={prompt}"

# With options
npx agent-open aider "Add tests" --files src/index.ts --cwd /path/to/project

# Generic run command (specify agent by name)
npx agent-open run aider "Add documentation"

# List installed agents
npx agent-open ls

# List all agents (including not installed), with install hints
npx agent-open ls -a

# Configure default agent
npx agent-open config -d aider

# Show current configuration
npx agent-open config

Supported Agents

| Agent | Command / Action | Description | |-------|-----------------|-------------| | claude | claude --prompt <prompt> | Claude Code CLI | | aider | aider --message <prompt> | Aider | | opencode | opencode <prompt> | OpenCode | | gemini | gemini <prompt> | Google Gemini CLI | | interpreter | interpreter -p <prompt> | Open Interpreter | | cursor | Opens Cursor editor | Cursor | | windsurf | Opens Windsurf editor | Windsurf | | vscode | code <cwd> | VS Code with Copilot | | zed | Opens Zed editor | Zed | | copilot | gh copilot suggest <prompt> | GitHub Copilot CLI | | cody | cody chat --message <prompt> | Sourcegraph Cody | | chatgpt | Opens browser | ChatGPT | | perplexity | Opens browser | Perplexity | | browser | Opens configurable URL | Custom browser-based agent |

Configuration

# Set default agent (used when no agent is specified in root command)
agent-open config -d aider

# Show current config
agent-open config

Config is stored at ~/.agent-open/config.json.

Architecture

src/
  index.ts          # Public API exports (agentOpen, api, program, registry)
  openAgent.ts      # Agent registry, agentOpen(), findFirstAvailableAgent()
  program.ts        # Padrone program definition (all CLI commands)
  cli.ts            # CLI entry point — calls program.cli()
  agents/
    aider.ts        # Aider launcher
    browser.ts      # Browser agent launcher
    claude.ts       # Claude Code launcher
    cody.ts         # Cody launcher
    copilot.ts      # GitHub Copilot launcher
    cursor.ts       # Cursor launcher
    gemini.ts       # Gemini CLI launcher
    interpreter.ts  # Open Interpreter launcher
    opencode.ts     # OpenCode launcher
    vscode.ts       # VS Code launcher
    windsurf.ts     # Windsurf launcher
    zed.ts          # Zed launcher
  utils/
    config.ts       # Config file management (~/.agent-open/config.json)
    detectBinary.ts # Binary detection utility
    runCommand.ts   # Command execution utility

License

MIT