Related Pages

Related topics: TUI (Textual UI) & Conversation Management, ACP Server & IDE Integration, Headless, Cloud, MCP & Operations

Project Overview & System Architecture

Purpose and Scope

OpenHands-CLI is the command-line distribution of the OpenHands agent. It packages the OpenHands agent so that it can be invoked from a terminal, an IDE, CI pipelines, or any context where a shell-friendly interface is preferred. According to README.md, the project is "feature-complete" in its V1 form and is maintained primarily for stability, with only major bug fixes and compatibility updates expected. Active feature development is tracked in the main OpenHands repository.

The CLI exposes a Textual-based Terminal User Interface (TUI), an Agent Client Protocol (ACP) endpoint for IDE integration, and a set of supporting subcommands for configuration, MCP management, and conversation lifecycle. It persists its settings under ~/.openhands/, including agent_settings.json, cli_config.json, and mcp.json.

System Architecture

The repository is organized as a layered system with the CLI shell acting as a thin orchestration layer over the openhands-sdk. The high-level component layout is:

graph TD
    User[User / Editor]
    Entry[openhands CLI entrypoint]
    TUI[Textual TUI - openhands_cli/tui]
    ACP[ACP server - openhands_cli/acp_impl]
    MCP[MCP config - cli mcp subcommand]
    SDK[openhands-sdk]
    Critic[Critic subsystem - tui/utils/critic]
    Storage[(~/.openhands/)]

    User --> Entry
    Entry --> TUI
    Entry --> ACP
    Entry --> MCP
    TUI --> Critic
    TUI --> SDK
    ACP --> SDK
    SDK --> Storage

Entrypoint and Command Surface

The CLI ships a single openhands command that branches into multiple subcommands. The default subcommand launches the interactive TUI, while openhands acp starts the JSON-RPC ACP server used by editors such as Zed. The ACP entry point is documented in openhands_cli/acp_impl/README.md, which provides example uvx and uv run invocations and references the Agent Client Protocol specification.

TUI Subsystem

The TUI is built on the Textual framework and is implemented under openhands_cli/tui/. It handles conversation rendering, slash command parsing, confirmation-mode toggling, and persistence of user preferences. A notable in-TUI subsystem is the Critic module, which surfaces a quality score for each agent response. Its public surface is re-exported from openhands_cli/tui/utils/critic/__init__.py:

• create_critic_collapsible — builds a collapsible widget showing a 5-star rating and categorized issues (visualization.py).
• send_critic_inference_event — forwards telemetry to PostHog when a critic result is rendered (feedback.py).
• build_refinement_message, get_high_probability_issues, and should_trigger_refinement — implement the iterative refinement pattern from the SDK (refinement.py). When the predicted success likelihood is below the configured threshold, or a specific issue (such as insufficient testing) exceeds the issue threshold, the TUI sends an automatic follow-up prompt to the agent.

The community has reported polish issues with this subsystem; for example, issue #641 describes a stray "accuracy" feedback row that appears in the conversation pane after subsequent events.

ACP Subsystem

The ACP implementation lets external editors drive the OpenHands agent through a standardized JSON-RPC protocol. The abstract base class is defined in openhands_cli/acp_impl/agent/base_agent.py, which exposes capability negotiation (AgentCapabilities, PromptCapabilities, McpCapabilities), session lifecycle (new_session, load_session, fork_session, list_sessions), and slash command processing. Subclasses specialize it for local vs. cloud execution by overriding agent_type, _setup_conversation, and _is_authenticated.

ACP utilities translate between ACP-shaped data and the SDK's internal types:

• acp_impl/utils/convert.py maps ACP prompt content blocks (text, image, resource links, embedded resources) to the SDK's TextContent and ImageContent objects.
• acp_impl/utils/resources.py materializes embedded resources: text resources are inlined into the message, supported image MIME types are returned inline as data URIs, and unsupported binaries are saved under ~/.openhands/cache/acp/.
• acp_impl/utils/mcp.py converts ACP MCP server configurations (stdio, HTTP, SSE) into the dict-of-dicts shape expected by the SDK agent, flattening the serialized EnvVariable lists into environment dictionaries.

The protocol variant requested in issue #66 — full Agent Client Protocol support for Zed and other non-VSCode editors — is delivered through this subsystem.

MCP, Critic Telemetry, and Configuration

The CLI exposes MCP server management through a dedicated subcommand. Community requests such as issue #694 propose extending it with openhands mcp test <name> for connectivity validation. Settings persistence uses three JSON files under ~/.openhands/, as documented in README.md. By default, environment variables such as LLM_API_KEY, LLM_MODEL, and LLM_BASE_URL are ignored; passing --override-with-envs opts in for the current session. Issue #673 notes that the CLI still prompts for an API key even when running against local LLMs that do not require one.

Critic telemetry is sent to PostHog using the key and host defined in feedback.py. The module degrades gracefully if posthog is not installed, so the TUI still functions in offline or minimal installs.

End-to-End Testing Infrastructure

The tui_e2e/ directory hosts an end-to-end testing harness that drives the real CLI against a mock OpenAI-compatible LLM server. As described in tui_e2e/README.md, tests load a recorded trajectory, replay its MessageEvent and ActionEvent entries through the mock server, and validate that the CLI's ObservationEvent outputs match expectations. This gives the project deterministic coverage of TUI behaviors without depending on a live model.

See Also

• ACP integration details: openhands_cli/acp_impl/README.md
• Critic iterative refinement reference: openhands_cli/tui/utils/critic/refinement.py
• Community discussion on LLM profile management: #68
• Community discussion on conversation history listing: #101
• Community discussion on planning mode: #613

Related Pages

Related topics: Project Overview & System Architecture, Headless, Cloud, MCP & Operations

TUI (Textual UI) & Conversation Management

Overview and Scope

The OpenHands CLI ships a Textual-based terminal UI that wraps an SDK conversation loop and provides rich, in-terminal feedback while an agent executes a task. The TUI is the primary interaction surface for openhands and is complemented by an ACP mode that reuses the same conversation primitives to talk to external editors (e.g. Zed) via JSON-RPC. Source: README.md.

Conversation management in this codebase covers:

• Conversation loop and confirmation — driving the SDK BaseConversation with confirmation gates before any agent action.
• Critic visualization — turning SDK CriticResult objects into collapsible, filtered, CLI-friendly panels.
• User feedback capture — letting the user rate the critic's predictions and reporting them to PostHog.
• Iterative refinement — feeding critic-detected issues back to the agent as a follow-up message until the score crosses a threshold or iterations are exhausted.
• Resumption and event history — rehydrating prior conversation events on resume (tracked as an enhancement in the community, see issue #204).

Critic Visualization in the TUI

The TUI renders critic results using a CLI-specific subset of the SDK's star-rating format. create_critic_collapsible builds a Collapsible widget whose title shows the score as a five-star rating and whose body lists only the categories that are actionable in a terminal — Potential Issues and Infrastructure. Sections such as *Likely Follow-up* and *Other* are intentionally suppressed. Source: openhands_cli/tui/utils/critic/visualization.py.

from openhands_cli.tui.utils.critic import create_critic_collapsible
widget = create_critic_collapsible(critic_result)

The collapsible is auto-expanded only when there is content to show, which keeps the transcript compact for clean runs. Source: openhands_cli/tui/utils/critic/visualization.py.

A known UX bug (community issue #641) is that the in-conversation "accuracy" feedback button row can appear above subsequent agent actions when the event ordering is not strictly enforced; the widget labels are [1] Accurate, [2] Too high, [3] Too low, [4] N/A, [0] Dismiss. Source: openhands_cli/tui/utils/critic/feedback.py.

User Feedback Capture and PostHog Reporting

send_critic_inference_event is fired as soon as a critic result is rendered — before the user has judged it — so the inference itself is tracked separately from the feedback signal. The widget exposes CriticFeedbackWidget whose BUTTON_LABELS map human-readable labels to internal codes (accurate, too_high, too_low, not_applicable, dismiss). Source: openhands_cli/tui/utils/critic/feedback.py.

PostHog is treated as an optional dependency: the module imports posthog inside a guarded try/except and short-circuits if POSTHOG_AVAILABLE is False, so TUI sessions never crash on missing analytics. Source: openhands_cli/tui/utils/critic/feedback.py.

Iterative Refinement Loop

Refinement is the bridge between passive critic display and active conversation steering. should_trigger_refinement decides whether the loop continues, get_high_probability_issues extracts agent-behavioural issues above the configured issue_threshold, and build_refinement_message produces a follow-up prompt that is sent back to the SDK conversation. Source: openhands_cli/tui/utils/critic/refinement.py.

Refinement is triggered in two ways:

1. The overall success score is below the critic threshold, or
2. Any specific behavioural issue has a probability above the issue_threshold (default 0.75), even if the overall score is acceptable.

Source: openhands_cli/tui/utils/critic/refinement.py.

flowchart LR
    A[Agent finishes turn] --> B[Critic evaluates result]
    B --> C{Core critic<br/>package}
    C --> D[TUI: create_critic_collapsible<br/>+ send_critic_inference_event]
    D --> E[User feedback widget<br/>PostHog event]
    C --> F{should_trigger_refinement?}
    F -- yes --> G[build_refinement_message<br/>get_high_probability_issues]
    G --> H[Send follow-up to SDK conversation]
    H --> A
    F -- no --> I[Conversation idle]

Conversation Plumbing: Runner and ACP Path

The same "drive a conversation, gate each action" pattern is shared between the TUI runner and the ACP server. BaseOpenHandsACPAgent is the abstract base used by both local and cloud ACP implementations and exposes a run_conversation_with_confirmation helper imported from openhands_cli.acp_impl.runner. Source: openhands_cli/acp_impl/agent/base_agent.py.

Slash commands (/confirm, /help, unknown-command handling, confirmation-mode toggling) are parsed and applied through helpers in openhands_cli.acp_impl.slash_commands and re-imported by the ACP base agent; this is the same surface that the TUI's input bar uses. Source: openhands_cli/acp_impl/agent/base_agent.py.

MCP and Content Conversion

When a client (TUI or ACP) supplies MCP servers or content blocks, they are normalised into the SDK's McpServer and TextContent/ImageContent shapes:

• convert_acp_mcp_servers_to_agent_format reshapes ACP McpServerStdio, HttpMcpServer, and SseMcpServer into the agent's dict-keyed format and flattens EnvVariable arrays into plain dicts. Source: openhands_cli/acp_impl/utils/mcp.py.
• convert_acp_prompt_to_message_content accepts strings, single blocks, or lists mixing text and image blocks and produces the list of TextContent | ImageContent that the SDK expects. Source: openhands_cli/acp_impl/utils/convert.py.
• Embedded resource blobs with unsupported image MIME types are converted via _convert_image_to_supported_format; otherwise they are written to disk and surfaced as TextContent references. Source: openhands_cli/acp_impl/utils/resources.py.

Conversation State, Configuration, and Persistence

CLI/TUI preferences live under ~/.openhands/:

By default, environment variables such as LLM_API_KEY, LLM_MODEL, and LLM_BASE_URL are ignored at the TUI layer; passing --override-with-envs makes them apply (without being persisted). Source: README.md. Note that community issue #673 reports the CLI still prompts for an API key when using local LLMs (e.g. Ollama) that do not require one.

Resuming a conversation should rehydrate the pane with prior events; this is the subject of enhancement issue #204 and is a recurring UX gap reported by users.

End-to-End Testing of the TUI

tui_e2e/ runs real conversations against a mock OpenAI-compatible /chat/completions server that replays scripted trajectories. Each trajectory is a directory of event JSON files (MessageEvent, ActionEvent, ObservationEvent) keyed by a stable UUID, and the mock server returns the next scripted response on each request while the CLI executes tool calls for real. Source: tui_e2e/README.md.

Adding a new TUI scenario is a three-step workflow: drop a trajectory under tests/trajectories/<name>/, write a test_<feature>.py that drives the CLI through MockLLMServer, and register the function in runner.py so it is picked up by the suite. Source: tui_e2e/README.md.

Common Failure Modes

• Terminal state on exit. Some commands leave residual escape sequences; users have to run reset or stty sane after exit (community issue #671).
• Missing API key prompt suppression for local LLMs. The TUI still asks for LLM_API_KEY when targeting providers like Ollama (community issue #673).
• Stale critic button row. The [1] Accurate button row can render above subsequent actions when event ordering is loose (community issue #641).
• No event rehydration on resume. When resuming a saved conversation, prior events are not always shown in the pane (community issue #204).
• Posthog missing. Analytics is optional; if posthog is not installed, both send_critic_inference_event and CriticFeedbackWidget silently no-op rather than failing.

See Also

• README.md — installation, configuration paths, and top-level usage.
• openhands_cli/acp_impl/README.md — Agent Client Protocol integration and editor wiring (e.g. Zed).
• tui_e2e/README.md — trajectory-based end-to-end testing for the TUI.

Related Pages

Related topics: Project Overview & System Architecture, Headless, Cloud, MCP & Operations

ACP Server & IDE Integration

Overview and Purpose

The Agent Client Protocol (ACP) integration allows OpenHands to act as a backend agent for code editors and IDEs that speak the standardized JSON-RPC 2.0 interface defined by the Agent Client Protocol. Concretely, the CLI exposes an openhands acp entry point that IDEs such as Zed can spawn as a subprocess; the IDE then drives conversations, mode changes, and session lifecycle through ACP, while OpenHands handles prompt execution, MCP servers, confirmation, and event streaming.

This integration is the implementation behind community feature request #66 — ACP support, which explicitly requests the ability to launch OpenHands in the Zed editor via ACP. The README documents that OpenHands-CLI is a slim wrapper around the SDK and exposes MCP servers, confirmation modes, cloud conversations, and headless mode (README.md); the ACP server is the same engine surfaced over a different transport.

Architecture and Agent Implementations

The ACP implementation lives under openhands_cli/acp_impl/ and is structured around a small inheritance hierarchy of agent classes plus a set of transport and content-conversion utilities.

flowchart LR
    IDE[ACP Client<br/>e.g. Zed] -- JSON-RPC 2.0 --> Server[openhands acp]
    subgraph CLI[acp_impl/]
        Server --> Launcher[agent/launcher.py<br/>run_acp_server]
        Launcher --> Base[BaseOpenHandsACPAgent]
        Base --> Local[LocalOpenHandsACPAgent]
        Base --> Remote[OpenHandsCloudACPAgent]
        Local --> SDKConv[SDK LocalConversation]
        Remote --> SDKConv2[SDK RemoteConversation<br/>+ OpenHandsCloudWorkspace]
    end
    Base --> Slash[slash_commands]
    Base --> Confirm[confirmation modes]
    Local --> MCP[MCP servers<br/>utils/mcp.py]
    Local --> Res[resources.py<br/>images / blobs / text]

• BaseOpenHandsACPAgent is an abstract class registered as an acp.Agent. It implements initialization, slash command processing, prompt handling with confirmation, and session management. It defines an agent_type property and a _setup_conversation() hook that subclasses must implement (base_agent.py).
• LocalOpenHandsACPAgent is the local workspace variant. It uses the SDK's LocalConversation with a Workspace rooted in the user's working directory, registers built-in subagents via register_builtins_agents(), loads MCP configuration from MCP_CONFIG_FILE, and persists conversations under the standard get_conversations_dir() location (local_agent.py).
• OpenHandsCloudACPAgent is the cloud variant. It uses RemoteConversation together with OpenHandsCloudWorkspace, requires an authenticated user (via TokenStorage and is_token_valid), and is reachable through a configurable cloud_api_url (default https://app.all-hands.dev) (remote_agent.py).
• run_acp_server is the entry point exposed from the package root (agent/__init__.py).

The base agent advertises its capabilities to the IDE through AgentCapabilities, PromptCapabilities, and McpCapabilities, and propagates confirmation-mode changes through SessionModeState constructed in get_session_mode_state() (agent/util.py).

Configuring an IDE (Zed)

ACP is launched through the CLI subcommand openhands acp. The ACP README documents two concrete ways to wire it into Zed's agent_servers configuration (acp_impl/README.md):

"OpenHands-uvx": {
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/OpenHands/OpenHands-CLI.git@xw/acp-simplification",
    "openhands",
    "acp"
  ],
  "env": {}
}

The first config uses uvx to install and run a specific PR branch, while the second uses a local checkout via uv run --project /YOUR_LOCAL_PATH/OpenHands-CLI openhands acp. The same acp subcommand is what the launcher ultimately invokes, so any ACP-compliant client that accepts a child-process command should be able to integrate OpenHands the same way. For debugging, the README recommends opening ACP logs in Zed with Cmd+Shift+P before starting a conversation.

Content, Resource, and MCP Conversion

ACP and the OpenHands SDK use different on-the-wire formats for prompts, resources, and MCP server definitions. The acp_impl/utils/ package bridges these formats.

• Prompt conversion. convert_acp_prompt_to_message_content() turns a list of ACP content blocks into the SDK's TextContent / ImageContent objects. It handles ACPTextContentBlock, ACPImageContentBlock, and resource blocks, and delegates to convert_resources_to_content() for embedded resources (utils/convert.py).
• Image handling. _convert_image_block() returns an ImageContent for natively supported MIME types, attempts a Pillow-based conversion for unsupported image types, and otherwise falls back to a TextContent describing the file path (utils/convert.py). The list of supported types lives in SUPPORTED_IMAGE_MIME_TYPES in utils/resources.py.
• Blob and text resources. _materialize_embedded_resource() expands an ACPEmbeddedResourceContentBlock into either an ImageContent (for supported or convertible images) or a temporary file on disk under ~/.openhands/cache/acp/ for binary blobs that cannot be inlined. Text resources are wrapped in a BEGIN/END USER PROVIDED ADDITIONAL CONTEXT envelope (utils/resources.py). The same module also injects a RESOURCE_SKILL so the agent knows how to interpret these user-provided blocks.
• MCP server conversion. ACP represents each MCP server as a Pydantic model with a name field and an env array, while the SDK agent expects a name-keyed dict with a transport field and a dict-formatted env. convert_acp_mcp_servers_to_agent_format() performs this translation and infers the transport from the server class (McpServerStdio → stdio, HttpMcpServer → http, SseMcpServer → sse) (utils/mcp.py). The function is re-exported from the package __init__ (utils/__init__.py).

The local agent injects RESOURCE_SKILL into its conversation and reads MCP configuration from MCP_CONFIG_FILE; the cloud agent performs the same wiring but on top of RemoteConversation and OpenHandsCloudWorkspace (local_agent.py, remote_agent.py).

See Also

• Agent Client Protocol specification
• OpenHands ACP user guide: <https://docs.openhands.dev/openhands/usage/run-openhands/acp#zed-ide>
• Community feature request: #66 — ACP support
• Related: MCP server management and openhands mcp commands (README.md)

Related Pages

Related topics: Project Overview & System Architecture, TUI (Textual UI) & Conversation Management, ACP Server & IDE Integration

Headless, Cloud, MCP & Operations

This page covers the operational surface area of OpenHands V1 CLI that extends beyond the interactive TUI: headless execution, cloud task delegation, MCP server configuration, and the Agent Client Protocol (ACP) integration that lets IDEs such as Zed drive the agent. It also documents the critic-driven refinement loop, which is the CLI's primary runtime quality gate.

Project status note: The README states *"OpenHands V1 CLI is feature-complete and primarily maintained for stability. Expect only major bug fixes and compatibility updates; new features are unlikely."* Source: README.md

Configuration Surface

All persistent state lives under ~/.openhands/:

By default, environment variables such as LLM_API_KEY, LLM_MODEL, and LLM_BASE_URL are ignored at startup; the flag --override-with-envs re-enables them (non-persistent). Source: README.md

MCP Server Management

The CLI exposes a top-level mcp namespace for managing Model Context Protocol servers:

openhands mcp list                                # show configured servers
openhands mcp add tavily --transport stdio \
  npx -- -y mcp-remote "https://mcp.tavily.com/mcp/?tavilyApiKey=<key>"
openhands mcp enable <server-name>
openhands mcp disable <server-name>

A community feature request (#694) is open for openhands mcp test <name> to validate a configured server before use.

When the agent is hosted inside an ACP-compliant IDE, the MCP definitions arrive in ACP's Pydantic format (McpServerStdio | HttpMcpServer | SseMcpServer) with name fields and serialized EnvVariable arrays. The CLI converts these to the agent's internal dict-keyed format using convert_acp_mcp_servers_to_agent_format, which flattens env vars via _convert_env_to_dict and adds the required transport discriminator. Source: openhands_cli/acp_impl/utils/mcp.py

Headless & Cloud Execution Modes

Headless Mode

Designed for CI/CD pipelines and automation, headless mode skips the Textual UI:

openhands --headless -t "Write unit tests for parser.py"

Confirmation Modes

The interactive entry point also accepts action-handling policies:

openhands                  # ask for confirmation on each action (default)
openhands --always-approve # auto-approve all actions (alias: --yolo)
openhands --llm-approve    # use an LLM-based security analyzer

Cloud Conversations

For sandboxed, hosted execution, the CLI delegates to OpenHands Cloud:

openhands login            # fetch and cache cloud settings
openhands cloud -t "Fix the login bug"

Source: README.md

ACP (Agent Client Protocol) Integration

ACP enables editors like Zed to drive the OpenHands agent over a JSON-RPC 2.0 interface. The CLI is launched as an ACP server via the openhands acp subcommand. Source: openhands_cli/acp_impl/README.md

flowchart LR
    Zed["Zed IDE (ACP client)"] -- JSON-RPC 2.0 --> Base["BaseOpenHandsACPAgent"]
    Base -- prompt --> Conv["run_conversation_with_confirmation"]
    Conv --> Agent["OpenHands SDK Agent"]
    Base -- convert --> Utils["acp_impl/utils"]
    Utils -- format --> Agent
    Agent -- events --> Base
    Base -- chunks --> Zed

Key responsibilities of the ACP layer:

• Session lifecycle — handled by BaseOpenHandsACPAgent, an abstract base that defines agent_type, _setup_conversation(), _cleanup_session(), and _is_authenticated(). Source: openhands_cli/acp_impl/agent/base_agent.py
• Prompt conversion — convert_acp_prompt_to_message_content accepts strings, lists of content blocks, or single ContentBlock objects and emits TextContent / ImageContent items. Source: openhands_cli/acp_impl/utils/convert.py
• Resource materialization — convert_resources_to_content handles inline EmbeddedResourceContentBlocks: supported image MIME types are returned as data-URI ImageContent, unsupported images are converted via Pillow, and other blobs are saved to ~/.openhands/cache/acp/ and referenced by URI. Source: openhands_cli/acp_impl/utils/resources.py
• MCP bridging — see previous section. Source: openhands_cli/acp_impl/utils/__init__.py

A persistent community request (#66) tracks upstream ACP support and additional editor integrations.

Critic-Driven Refinement Operations

The CLI embeds an SDK-supplied critic that scores each completed task and, when the score is low or a high-probability issue is detected, automatically issues a follow-up prompt to the agent. This is the CLI's iterative-quality loop.

The refinement module:

• Extracts high-probability issues via get_high_probability_issues(critic_result, issue_threshold) from agent_behavioral_issues and other categorized metadata.
• Builds a follow-up message via build_refinement_message(...) that reports the predicted success likelihood (e.g., *"predicted success likelihood: 62.3%"*) and lists specific issues above the threshold.
• Gates refinement using should_trigger_refinement(...).

Source: openhands_cli/tui/utils/critic/refinement.py

Visualization side:

• create_critic_collapsible renders a 5-star rating and a CLI-filtered list of Potential Issues / Infrastructure categories (Likely Follow-up and Other sections are intentionally omitted from the CLI). Source: openhands_cli/tui/utils/critic/visualization.py
• send_critic_inference_event and the CriticFeedbackWidget emit anonymized PostHog telemetry (POSTHOG_API_KEY, POSTHOG_HOST = https://us.i.posthog.com) when the user rates a prediction as *Accurate*, *Too high*, *Too low*, or *N/A*. Source: openhands_cli/tui/utils/critic/feedback.py

The critic surface is re-exported through openhands_cli.tui.utils.critic. Source: openhands_cli/tui/utils/critic/__init__.py

Common Operational Pitfalls

• Resumed conversations show no prior events — a known UI gap; the conversation pane must be rehydrated from the trajectory on resume. Tracking issue: #204.
• Terminal left in raw state on exit — users occasionally need stty sane or reset after exit. Tracking issue: #671.
• API key still requested for local LLMs — local/Ollama models do not require an API key; the CLI prompt has historically not reflected that. Tracking issue: #673.
• Critic button ordering — the *Accurate* feedback button can appear below subsequent events. Tracking issue: #641.

See Also

• OpenHands-CLI Repository
• OpenHands V1 Documentation
• Agent Client Protocol Specification
• OpenHands Software Agent SDK

Doramagic Pitfall Log

Found 13 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

1. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/694

2. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | github_repo:1049343369 | https://github.com/OpenHands/OpenHands-CLI

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/641

4. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/671

5. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | github_repo:1049343369 | https://github.com/OpenHands/OpenHands-CLI

6. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:1049343369 | https://github.com/OpenHands/OpenHands-CLI

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | github_repo:1049343369 | https://github.com/OpenHands/OpenHands-CLI

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | github_repo:1049343369 | https://github.com/OpenHands/OpenHands-CLI

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/68

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/409

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/673

12. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:1049343369 | https://github.com/OpenHands/OpenHands-CLI

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using OpenHands-CLI with real data or production workflows.

• [[CLI] Feature Request: LLM Profile Management for OpenHands CLI](https://github.com/OpenHands/OpenHands-CLI/issues/68) - github / github_issue
• [[UX] CLI does not clean up terminal state after exit, requiring manual r](https://github.com/OpenHands/OpenHands-CLI/issues/671) - github / github_issue
• [[UX] API key still required in CLI when not needed for local LLMs](https://github.com/OpenHands/OpenHands-CLI/issues/673) - github / github_issue
• Rehydrate conversation pane with event history for resumed conversation - github / github_issue
• [[M1] Plugin Loading and Command Invocation](https://github.com/OpenHands/OpenHands-CLI/issues/409) - github / github_issue
• [[Bug]: Critic button isn't showing up properly](https://github.com/OpenHands/OpenHands-CLI/issues/641) - github / github_issue
• [[Feature]: add openhands mcp test <name> to validate a configured MCP](https://github.com/OpenHands/OpenHands-CLI/issues/694) - github / github_issue
• GPT-5 is missing from OpenHands models - github / github_issue
• 1.16.0 - github / github_release
• 1.15.1 - github / github_release
• 1.15.0 - github / github_release
• 1.14.0 - github / github_release