docs: add CLI Backend Protocol documentation#240
Conversation
- Create comprehensive docs/features/cli-backend-protocol.mdx - Document all three configuration surfaces: CLI flag, YAML string, YAML dict - Include complete ClaudeCodeBackend configuration reference - Add Mermaid diagrams with standard color scheme - Follow AGENTS.md structure with Steps, AccordionGroup, CardGroup - Document backends subcommand and mutual exclusion with --external-agent - Add to docs.json navigation under Features group 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>
📝 WalkthroughWalkthroughA new documentation page for the CLI Backend Protocol has been added to explain how to run agent tasks via external CLI tools using a pluggable backend mechanism. The page is registered in Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the CLI Backend Protocol, which enables external CLI tools such as Claude Code to serve as first-class agent backends. The changes include updating the documentation structure and adding a comprehensive guide on configuring these backends via CLI flags, YAML, and Python. Review feedback highlights the need to correct placeholder model identifiers for Claude and suggests adding clarification regarding the sanitization of environment variables in the CLI subprocess.
| | `input` | `str` | `"stdin"` | How to pass prompts to CLI | | ||
| | `live_session` | `str` | `"claude-stdio"` | Live session mode | | ||
| | `model_arg` | `str` | `"--model"` | CLI argument for model selection | | ||
| | `model_aliases` | `Dict[str, str]` | `{"opus": "claude-opus-4-5", "sonnet": "claude-sonnet-4-5", "haiku": "claude-haiku-3-5"}` | Model name shortcuts | |
There was a problem hiding this comment.
The model identifiers claude-opus-4-5, claude-sonnet-4-5, and claude-haiku-3-5 appear to be placeholders or incorrect, as Claude 4.5 has not been released. It is recommended to update these to valid Claude 3.5 identifiers (e.g., claude-3-5-sonnet-20241022) to ensure the documentation is accurate. Note that this change should also be reflected in the DEFAULT_CONFIG of praisonai/cli_backends/claude.py to maintain consistency.
| | `system_prompt_arg` | `str` | `"--append-system-prompt"` | CLI argument for system prompts | | ||
| | `system_prompt_when` | `str` | `"first"` | When to add system prompts | | ||
| | `image_arg` | `str` | `"--image"` | CLI argument for images | | ||
| | `clear_env` | `List[str]` | `["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_OAUTH_TOKEN", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CONFIG_DIR", "CLAUDE_CODE_OAUTH_TOKEN", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_RESOURCE_ATTRIBUTES", "GOOGLE_APPLICATION_CREDENTIALS", "AWS_PROFILE", "AWS_REGION", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"]` | Environment variables sanitized before subprocess | |
There was a problem hiding this comment.
The clear_env list includes critical variables like ANTHROPIC_API_KEY and AWS_ACCESS_KEY_ID. While this is a good security practice for sanitization, it means these variables will be unavailable to the CLI subprocess by default. It would be helpful to explicitly mention that users may need to re-provide these via the env override if their CLI tool requires them and does not manage its own authentication state.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/features/cli-backend-protocol.mdx (1)
84-86: Consider adding a one-sentence introduction.The section jumps directly to the diagram. Adding a brief one-sentence introduction would improve readability and match the pattern used in other sections.
✨ Suggested addition
## How It Works +The backend resolution flow starts at the CLI or YAML layer and delegates execution to the external subprocess. + ```mermaid🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/features/cli-backend-protocol.mdx` around lines 84 - 86, Add a brief one-sentence introductory line under the "## How It Works" header and before the mermaid code block to explain what the diagram illustrates (e.g., "The following diagram shows the high-level interaction between the CLI and backend protocol."). Locate the "## How It Works" heading and the opening "```mermaid" block in the document and insert the single-sentence intro there so it matches the pattern used in other sections.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/features/cli-backend-protocol.mdx`:
- Line 8: The page docs/features/cli-backend-protocol.mdx is missing the
required agent-centric code example at the top; move the simplified Quick Start
YAML example (the agent-centric CLI backend example currently shown later in the
file) to immediately after the frontmatter and before the prose line that begins
"CLI Backends let you run an agent's turn...", so the page begins with a
concrete agent/Task API example demonstrating how to use a CLI backend; ensure
the relocated snippet remains intact and update any surrounding headings or
references so the intro prose now follows that example.
- Around line 19-27: The Mermaid diagram uses the wrong hex colors for concept
types: update the classDef entries so that classDef input uses Dark Red `#8B0000`
(for Agent Input/agents/outputs) and classDef resolver uses Teal `#189AB4` (for
tools/processes); keep classDef backend as `#189AB4`, classDef result as `#10B981`
and classDef warning/other as `#F59E0B` per the project's Mermaid color scheme,
and ensure the class declarations (e.g., "class A input", "class B resolver")
continue to reference those classDef names.
---
Nitpick comments:
In `@docs/features/cli-backend-protocol.mdx`:
- Around line 84-86: Add a brief one-sentence introductory line under the "##
How It Works" header and before the mermaid code block to explain what the
diagram illustrates (e.g., "The following diagram shows the high-level
interaction between the CLI and backend protocol."). Locate the "## How It
Works" heading and the opening "```mermaid" block in the document and insert the
single-sentence intro there so it matches the pattern used in other sections.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 6bb9d1a4-a449-43e7-97cd-908fa16e39b3
📒 Files selected for processing (2)
docs.jsondocs/features/cli-backend-protocol.mdx
| icon: "plug" | ||
| --- | ||
|
|
||
| CLI Backends let you run an agent's turn through an external CLI tool (like Claude Code) instead of a Python LLM client, while keeping the same `Agent`/`Task` API. |
There was a problem hiding this comment.
Missing agent-centric code example at the top.
The page starts with a prose description, but per the documentation guidelines, pages must begin with an agent-centric code example showing how to implement from the agent perspective. Consider moving a simplified Quick Start code example (e.g., the YAML example from lines 40-53) to the top of the page, immediately after the frontmatter and before this description line.
Based on learnings: "Documentation pages must start with an agent-centric code example at the top, showing how to implement from the agent perspective"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/features/cli-backend-protocol.mdx` at line 8, The page
docs/features/cli-backend-protocol.mdx is missing the required agent-centric
code example at the top; move the simplified Quick Start YAML example (the
agent-centric CLI backend example currently shown later in the file) to
immediately after the frontmatter and before the prose line that begins "CLI
Backends let you run an agent's turn...", so the page begins with a concrete
agent/Task API example demonstrating how to use a CLI backend; ensure the
relocated snippet remains intact and update any surrounding headings or
references so the intro prose now follows that example.
| classDef input fill:#6366F1,stroke:#7C90A0,color:#fff | ||
| classDef resolver fill:#F59E0B,stroke:#7C90A0,color:#fff | ||
| classDef backend fill:#189AB4,stroke:#7C90A0,color:#fff | ||
| classDef result fill:#10B981,stroke:#7C90A0,color:#fff | ||
|
|
||
| class A input | ||
| class B resolver | ||
| class C,D backend | ||
| class E result |
There was a problem hiding this comment.
Fix Mermaid diagram color scheme to match guidelines.
The diagram uses incorrect colors for the concept types:
Agent Input(line 24) uses Indigo#6366F1, but inputs should use Dark Red#8B0000Resolver(line 25) uses Amber#F59E0B, but process/tool components should use Teal#189AB4
As per coding guidelines: "Use exact Mermaid color scheme for diagrams: #8B0000 (Dark Red) for agents/inputs/outputs, #189AB4 (Teal) for tools/processes, #10B981 (Green) for success, #F59E0B (Amber) for warnings, #6366F1 (Indigo) for configuration"
🎨 Proposed fix for color scheme
- classDef input fill:`#6366F1`,stroke:`#7C90A0`,color:`#fff`
- classDef resolver fill:`#F59E0B`,stroke:`#7C90A0`,color:`#fff`
+ classDef input fill:`#8B0000`,stroke:`#7C90A0`,color:`#fff`
+ classDef resolver fill:`#189AB4`,stroke:`#7C90A0`,color:`#fff`
classDef backend fill:`#189AB4`,stroke:`#7C90A0`,color:`#fff`
classDef result fill:`#10B981`,stroke:`#7C90A0`,color:`#fff`🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/features/cli-backend-protocol.mdx` around lines 19 - 27, The Mermaid
diagram uses the wrong hex colors for concept types: update the classDef entries
so that classDef input uses Dark Red `#8B0000` (for Agent Input/agents/outputs)
and classDef resolver uses Teal `#189AB4` (for tools/processes); keep classDef
backend as `#189AB4`, classDef result as `#10B981` and classDef warning/other as
`#F59E0B` per the project's Mermaid color scheme, and ensure the class
declarations (e.g., "class A input", "class B resolver") continue to reference
those classDef names.
Fixes #239
Summary
Implementation
SDK Source Coverage
Read all required SDK files:
Generated with Claude Code
Summary by CodeRabbit