External Agents in UI

Toggle Claude / Gemini / Codex / Cursor sub-agents from any PraisonAI UI

Flip sidebar toggles to attach Claude Code, Gemini CLI, Codex CLI, or Cursor CLI as sub-agents — no code changes required.

from praisonaiagents import Agent

agent = Agent(name="dev-assistant", instructions="Help with coding tasks")
# Enable Claude Code or Codex in the UI sidebar — tools attach automatically
agent.start("Refactor the auth module and add error handling")

The user toggles an external CLI in the sidebar; the PraisonAI agent delegates work to that sub-agent and returns the result.

Quick Start

1. Install External CLI

   Install one of the supported CLIs:

   # Claude Code
   npm install -g @anthropic-ai/claude-code
   
   # Gemini CLI  
   npm install -g @google/gemini-cli
   
   # Codex CLI
   npm install -g @openai/codex-cli
   
   # Cursor CLI
   # Download from cursor.com

2. Launch PraisonAI UI

   Run any PraisonAI UI entry point:

   praisonai ui chat         # Chat interface with sidebar toggles
   praisonai ui code         # Code interface with sidebar toggles
   praisonai ui agents       # Agent team interface with toggles per agent
   praisonai ui              # Multi-agent interface with auto-shown checkboxes

3. Enable External Agent

   Open the sidebar settings — toggles for installed CLIs appear automatically. Flip the toggle for your desired external agent:

   • Claude Code: Enable for file edits and coding tasks
   • Gemini CLI: Enable for analysis and search tasks
   • Codex CLI: Enable for refactoring and optimization
   • Cursor CLI: Enable for IDE-style development tasks
4. Start Coding

   With toggles on, your agent delegates coding tasks to the external CLI:

   from praisonaiagents import Agent
   
   agent = Agent(name="dev-assistant", instructions="Help with coding tasks")
   agent.start("Refactor the auth module and add error handling")
   # → Delegates to Claude Code or Codex CLI based on your toggles

How It Works

Which Agent for Which Job

Per-Entry-Point Toggles

Auto-Availability Detection

Only CLIs that resolve via shutil.which(...) show a toggle. The CLI → command mapping below is a view of the registry (EXTERNAL_AGENTS, a _RegistryAgents Mapping), so a registered plugin gets a "{name}_enabled" toggle automatically. Toggles are built from the same catalog as --external-agent choices, so a plugin that fails to load simply does not appear as a toggle — it never shows up as a dead switch:

• claude_enabled → claude command
• gemini_enabled → gemini command
• codex_enabled → codex command
• cursor_enabled → cursor-agent command

Toggle IDs and Labels

These are the built-in toggles. A registered external agent gets a "{name}_enabled" toggle automatically — its label comes from display_label and its CLI from cli_command.

External Agent Tools Implementation

When you enable an external agent toggle, the UI automatically adds the corresponding tool to your agent:

from praisonaiagents import Agent
from praisonai.integrations import ClaudeCodeIntegration

# What happens when you flip the Claude Code toggle:
claude_integration = ClaudeCodeIntegration(workspace="/path/to/workspace")

agent = Agent(
    name="Development Assistant",
    tools=[claude_integration.as_tool()]  # Added automatically
)

# Agent can now delegate to Claude Code:
agent.start("Fix the authentication bug in auth.py")

The integration tools provide:

• Workspace Context: Operate against PRAISONAI_WORKSPACE or PRAISONAI_CODE_REPO_PATH
• Streaming Output: Real-time feedback from external CLIs
• Error Handling: Graceful fallbacks when external CLIs fail
• Session Management: Continuation across multiple requests

Dynamic Instructions (Code UI)

In praisonai ui code, enabled external agents also modify the agent’s instructions dynamically:

# Base instructions
instructions = "You are a helpful coding assistant..."

# When Claude Code is enabled:
instructions += "\n\nYou have access to Claude Code for file editing and code analysis."

# When multiple agents are enabled:
instructions += "\n\nAvailable external agents: Claude Code, Gemini CLI"

Best Practices

# All four external agents enabled
agent = Agent(
    name="Full Stack Assistant",
    tools=[
        claude_code.as_tool(),    # File editing
        gemini_cli.as_tool(),     # Analysis
        codex_cli.as_tool(),      # Refactoring  
        cursor_cli.as_tool()      # IDE tasks
    ]
)

# Agent intelligently delegates based on task type
agent.start("Analyze the codebase, then refactor the auth module")

# Environment variable override (all UIs)
PRAISONAI_CLAUDECODE_ENABLED=true praisonai ui chat
# → Automatically enables claude_enabled toggle

# Test CLI availability
which claude        # Should return path
which gemini        # Should return path  
which codex         # Should return path
which cursor-agent  # Should return path

Related