Skip to main content
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

ComponentPurposeFeatures
UI TogglesEnable/disable external agentsAuto-detection, persistence, per-entry-point
External Agent ToolsBridge to CLI toolsStreaming, workspace context, error handling
CLI IntegrationExecute external commandsSubprocess management, JSON output, session continuation

​
Which Agent for Which Job

​
Per-Entry-Point Toggles

Entry pointHow toggles appearPersistenceWorkspace
praisonai uiaiui checkboxes (auto-shown for installed CLIs)sessionPRAISONAI_WORKSPACE
praisonai ui chatChainlit Switch widgets in sidebarpersistent (save_setting)PRAISONAI_WORKSPACE
praisonai ui codeChainlit Switch widgets (replaces old single Claude toggle)persistent (save_setting)PRAISONAI_CODE_REPO_PATH
praisonai ui agentsChainlit Switch widgets per AgentTeam memberpersistent + per-agent merging with YAML toolsPRAISONAI_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 IDLabelCLI CommandIntegration Class
claude_enabled”Claude Code (coding, file edits)“claudeClaudeCodeIntegration
gemini_enabled”Gemini CLI (analysis, search)“geminiGeminiCLIIntegration
codex_enabled”Codex CLI (refactoring)“codexCodexCLIIntegration
cursor_enabled”Cursor CLI (IDE tasks)“cursor-agentCursorCLIIntegration
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

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

External CLI Integrations (Python API)

Use external agents programmatically in your code

External Agents (Code)

Python API reference for external agent integrations