docs: External agents (Claude/Gemini/Codex/Cursor) toggles in all UI entry points

[MervinPraison]

Background

MervinPraison/PraisonAI PR #1423 (merged 2026-04-17, fixes #1418) ships external agents (Claude Code, Gemini CLI, Codex CLI, Cursor CLI) as togglable subagents in every PraisonAI UI entry point via a new shared helper:

• New file: src/praisonai/praisonai/ui/_external_agents.py
• Updated: praisonai ui (ui_chat/default_app.py), praisonai ui chat (ui/chat.py), praisonai ui code (ui/code.py), praisonai ui agents (ui/agents.py)
• Removed: ~95 lines of duplicate Claude Code subprocess logic from ui/code.py
• Backward-compat: legacy claude_code_enabled setting and PRAISONAI_CLAUDECODE_ENABLED env var still work and auto-migrate to claude_enabled

Existing PraisonAIDocs coverage is only the Python API (/docs/code/external-agents.mdx, /docs/features/external-cli-integrations.mdx, per-CLI pages in /docs/code/ and /docs/cli/). The UI side of this feature is currently undocumented.

What Needs Doc Work

1. Create new page: docs/features/external-agents-ui.mdx (NEW)

A user-facing, agent-centric page that explains: "Flip a switch in the UI sidebar and your agent gains a Claude/Gemini/Codex/Cursor sub-agent." Must follow AGENTS.md rules: place in docs/features/ (not docs/concepts/), include a hero Mermaid diagram, Steps Quick Start, AccordionGroup Best Practices, CardGroup Related.

Required sections:

• Hero diagram (graph LR): User → UI Toggle → PraisonAI Agent → External Sub-agent (Claude/Gemini/Codex/Cursor) → Result. Use the standard color palette (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1, #fff text).

• Quick Start (Steps):

  1. Install one of the CLIs (claude, gemini, codex, cursor-agent)
  2. Run praisonai ui chat (or ui / code / ui agents)
  3. Open the sidebar settings — the toggle for the installed CLI appears automatically
  4. Toggle on → agent now delegates coding/analysis tasks to the external sub-agent

• How It Works (sequence diagram): Settings → chainlit_switches() → external_agent_tools() → Agent(tools=[...])

• Choice diagram (graph TB): a "which agent for which job" flowchart — Claude Code = file edits/coding, Gemini CLI = analysis/search, Codex CLI = refactoring, Cursor CLI = IDE-style tasks. Per AGENTS.md §6.1 ("If multiple options in one page, people might be confused on what to choose, so create the mermaid diagram to choose what option at what instance").

• Per-entry-point matrix table:

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

• Auto-availability note: only CLIs that resolve via shutil.which(...) show a toggle. CLI → command map: claude_enabled→claude, gemini_enabled→gemini, codex_enabled→codex, cursor_enabled→cursor-agent.

• Backward Compatibility callout (<Note>): claude_code_enabled setting and PRAISONAI_CLAUDECODE_ENABLED=true env var still work and auto-migrate to claude_enabled on next save. No user action required.

• Workspace note: subagents run against PRAISONAI_WORKSPACE (chat/agents) or PRAISONAI_CODE_REPO_PATH (code).

• Best Practices (AccordionGroup): which agent for which task; combining toggles; persistence/migration; CLI not showing up troubleshooting (= CLI not on PATH).

• Related (CardGroup cols=2): /docs/code/external-agents (Python API) and /docs/features/external-cli-integrations (registry pattern).

Frontmatter:

---
title: "External Agents in UI"
sidebarTitle: "External Agents (UI)"
description: "Toggle Claude / Gemini / Codex / Cursor sub-agents from any PraisonAI UI"
icon: "toggle-on"
---

2. Update existing UI pages (each gets a short "External Agents" section + link to new page)

• docs/ui/code-ui.mdx — Currently mentions nothing about Claude/external agents. Add an "External Agents" section after "Key Features" explaining the new sidebar toggles replace the old single "Enable Claude Code" switch, with backward-compat note. Link to new /docs/features/external-agents-ui.
• docs/ui/chat.mdx — Add an "External Agents" section explaining the sidebar Switch widgets that appear when CLIs are installed. Link to the new page.
• docs/ui/ui.mdx — Add an "External Agents" section explaining AgentTeam members get external-agent tools when toggles are flipped. Link to the new page.

3. Update existing external-agents pages with a UI cross-link

• docs/code/external-agents.mdx — Add a <Tip> or new short section "Using from PraisonAI UI" that links to the new /docs/features/external-agents-ui page so Python-API readers know they can also flip toggles instead of writing code.
• docs/features/external-cli-integrations.mdx — Same: add a short cross-link section pointing to the UI page.

4. Update docs.json navigation

Add features/external-agents-ui under the existing Features group in docs.json. Per AGENTS.md §1.8: do not add to Concepts; the new page lives in docs/features/.

Source-of-Truth References (read these before writing)

• praisonai/ui/_external_agents.py — the new shared helper (EXTERNAL_AGENTS map, installed_external_agents(), external_agent_tools(), chainlit_switches(), aiui_settings_entries(), load_external_agent_settings_from_chainlit(), save_external_agent_settings_to_chainlit())
• praisonai/ui/chat.py — usage in praisonai ui chat
• praisonai/ui/code.py — usage in praisonai ui code, including dynamic instructions block built from enabled agents
• praisonai/ui/agents.py — usage in praisonai ui agents, including merging external tools with YAML-resolved role_tools
• praisonai/ui_chat/default_app.py — usage in praisonai ui via aiui.set_settings(...) and per-session agent cache
• praisonai/integrations/{claude_code,gemini_cli,codex_cli,cursor_cli}.py — the integration classes the helper imports

(All paths above are repo-root praisonai/ per AGENTS.md §1.4 — "SDK Location paths are under repo root praisonaiagents/ (not src/)" — and the praisonai/ tree is daily-synced via update_repos.sh.)

EXTERNAL_AGENTS Map (must match SDK exactly — extract from _external_agents.py)

toggle id	label	CLI	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

Acceptance Criteria

• docs/features/external-agents-ui.mdx created, follows AGENTS.md template (frontmatter, hero Mermaid, Steps, AccordionGroup, CardGroup, standard colors)
• Choice/decision Mermaid diagram included (per AGENTS.md §6.1)
• All four toggles documented with their exact *_enabled ids and CLI commands
• Backward-compat (claude_code_enabled, PRAISONAI_CLAUDECODE_ENABLED) called out
• Auto-availability behavior (shutil.which) documented
• Cross-links added to /docs/ui/{code-ui,chat,ui}.mdx
• Cross-links added to /docs/code/external-agents.mdx and /docs/features/external-cli-integrations.mdx
• docs.json updated under Features group (NOT Concepts)
• No file placed in docs/concepts/ (per AGENTS.md §1.8 — human-only folder)
• All code samples use friendly imports (from praisonaiagents import Agent) per AGENTS.md §6.1

Out of Scope

• No SDK reference changes (auto-generated section)
• No edits to docs/js/ or docs/rust/ (parity-managed)
• No rewrite of existing /docs/code/external-agents.mdx Python API content (already accurate)

Branch

Per instructions, develop on claude/admiring-euler-605Hu.

Source PR

MervinPraison/PraisonAI#1423 — "feat: External agents integration across all UI entry points"

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-166-20260417-0605 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-166-20260417-0605?quick_pull=1&title=Issue%20%23166%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23166%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

I've successfully created comprehensive documentation for the external agents UI toggles feature across all PraisonAI UI entry points!

Todo List

• Read AGENTS.md to understand documentation standards
• Read source code from praisonai/cli/features/external_agents.py and related files
• Create main new page: docs/features/external-agents-ui.mdx
• Update docs/ui/code-ui.mdx with External Agents section
• Update docs/ui/chat.mdx with External Agents section
• Update docs/ui/ui.mdx with External Agents section
• Add cross-links to docs/code/external-agents.mdx
• Add cross-links to docs/features/external-cli-integrations.mdx
• Update docs.json navigation under Features group
• Commit and push changes
• Create pull request

Summary

Created comprehensive documentation for the external agents UI toggles feature following AGENTS.md standards:

New Documentation Page

• docs/features/external-agents-ui.mdx - Complete guide with hero diagram, Quick Start, choice diagram, per-entry-point matrix, and best practices

Updated Existing Pages

• UI Documentation: Added External Agents sections to code-ui.mdx, chat.mdx, and ui.mdx
• Cross-links: Added UI alternatives to external-agents.mdx and external-cli-integrations.mdx
• Navigation: Updated docs.json to include new page in Features group

Key Features Documented

• Auto-detection of installed CLIs (Claude Code, Gemini CLI, Codex CLI, Cursor CLI)
• Toggle behavior across different UI entry points
• Backward compatibility with legacy claude_code_enabled setting
• Workspace integration and persistence models
• Troubleshooting and best practices

All documentation uses proper Mintlify components, standard color schemes, and agent-centric examples as required.

Pull Request: #170

---