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

Component	Purpose	Features
UI Toggles	Enable/disable external agents	Auto-detection, persistence, per-entry-point
External Agent Tools	Bridge to CLI tools	Streaming, workspace context, error handling
CLI Integration	Execute external commands	Subprocess management, JSON output, session continuation

---

Which Agent for Which Job

---

Per-Entry-Point Toggles

Entry point	How toggles appear	Persistence	Workspace
praisonai ui	aiui checkboxes (auto-shown for installed CLIs)	session	PRAISONAI_WORKSPACE
praisonai ui chat	Chainlit Switch widgets in sidebar	persistent (save_setting)	PRAISONAI_WORKSPACE
praisonai ui code	Chainlit Switch widgets (replaces old single Claude toggle)	persistent (save_setting)	PRAISONAI_CODE_REPO_PATH
praisonai ui agents	Chainlit Switch widgets per AgentTeam member	persistent + per-agent merging with YAML tools	PRAISONAI_WORKSPACE

Auto-Availability Detection

Only CLIs that resolve via shutil.which(...) show a toggle. The CLI → command mapping is:

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

Toggle IDs and Labels

Toggle ID	Label	CLI Command	Integration Class
claude_enabled	”Claude Code (coding, file edits)“	claude	ClaudeCodeIntegration
gemini_enabled	”Gemini CLI (analysis, search)“	gemini	GeminiCLIIntegration
codex_enabled	”Codex CLI (refactoring)“	codex	CodexCLIIntegration
cursor_enabled	”Cursor CLI (IDE tasks)“	cursor-agent	CursorCLIIntegration

Backward Compatibility: The legacy claude_code_enabled setting and PRAISONAI_CLAUDECODE_ENABLED=true environment variable still work and auto-migrate to claude_enabled on next save. No user action required.

---

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

Which Agent for Which Task

Choose external agents based on task requirements:

• Claude Code: File edits, refactoring, adding features
• Gemini CLI: Code analysis, documentation, search
• Codex CLI: Performance optimization, code quality
• Cursor CLI: IDE-integrated development workflows

You can enable multiple agents simultaneously for complex workflows.

Combining Multiple Toggles

Enable multiple external agents for comprehensive development support:

# 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")

Toggle Persistence and Migration

Toggle settings persist automatically:

• Chat/Code/Agents UI: Saved to Chainlit settings, persist across sessions
• Main UI: Session-based, reset on restart
• Migration: Legacy claude_code_enabled auto-migrates to claude_enabled

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

CLI Not Showing Up Troubleshooting

If a CLI toggle doesn’t appear:

1. Check Installation: Ensure CLI is installed and on PATH
2. Verify Command: Test CLI command manually in terminal
3. Restart UI: Refresh browser or restart PraisonAI UI
4. Check Logs: Look for integration errors in console

# 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

External CLI Integrations (Python API)

Use external agents programmatically in your code

External Agents (Code)

Python API reference for external agent integrations