Skip to content
DOCS — PRODUCT · AGENT TUI

Agent TUI

OpenMed's TUI is the main operator interface: a terminal chat surface with visible plans, tool calls, structured workflow cards, local session persistence, and model/skill switching.

Launch

openmed
openmed --model gpt-5.6-terra
openmed --models
openmed agent --model gpt-5.6-terra --reasoning-effort medium

What the interface shows

A normal run can include:

  • your prompt and attached files
  • a visible plan
  • inline tool calls and results
  • model text and optional reasoning summary
  • workflow cards and artifact references

The key idea is that work stays inspectable in the conversation instead of disappearing behind a background job.

Input model

The input box supports four modes:

Prefix or action What it does
plain text Normal chat request
@ Attach file paths inline
# MCP autocomplete
$ Skill autocomplete
/ Slash-command autocomplete

Useful behaviors:

  • Enter sends a message
  • Shift+Enter or Ctrl+J inserts a newline
  • Up and Down browse input history
  • Enter while a run is active steers the current run
  • Tab while a run is active queues a follow-up to send after the current run finishes
  • drag/drop files or folders pastes absolute paths

Keyboard shortcuts

Key Action
Ctrl+Q Quit
Ctrl+C or Esc Interrupt the current run
Ctrl+L Clear the current conversation view
Ctrl+P Open the command palette
Ctrl+O Switch or create a session
Ctrl+M Open the model picker
Shift+Tab Cycle agent mode
F1 Open help

Ctrl+K exists in the app bindings, but the tools panel is currently a placeholder rather than a finished operator surface.

Model picker

The model picker is a three-step flow:

  1. Choose a model
  2. Choose a model-specific reasoning effort
  3. On supported models, choose whether to show reasoning summaries

You can open it with Ctrl+M or /model.

GPT-5.5 exposes none, low, medium, high, and xhigh. GPT-5.6 Sol, Terra, and Luna also expose max. Choosing none skips the reasoning-summary step. The default GPT-5.6 Terra session applies medium reasoning with thinking display off.

Agent modes

The TUI can switch among four runtime agent profiles:

Mode Current behavior
clinical Full registered tool access
consumer Restricted safety-first allowlist for personal health workflows
coordination Restricted care-coordination lane for inbox triage, discharge handoff, and reviewer-safe patient drafts
plan Read-only planning mode with shell and grep only

You can switch modes with Shift+Tab or /agent.

The same four modes are available from the CLI with openmed agent --agent ....

Sessions

Sessions persist locally and keep:

  • conversation history
  • model and reasoning settings
  • active skill
  • agent mode
  • PHI mode label
  • plan history
  • durable global plan paths for long runs
  • tool and card output

Use Ctrl+O or /session to switch sessions or create a new one.

Long sessions

The TUI is built to keep a single session running for hours without getting heavy:

  • Scroll-up history. Opening a session mounts only the newest messages; older ones stream in automatically as you scroll toward the top — there is no "load more" button to click. During a live run the oldest rows are likewise pruned back into that scroll-up history so the widget count stays bounded no matter how many tool calls a turn makes.
  • Delta-journal saves. Checkpoints append only what changed to a sidecar <session>.delta.jsonl journal instead of rewriting the whole session JSON, so saving stays sub-millisecond at any transcript length. The journal folds back into the canonical file when the session closes.
  • Auto-compaction. When the model context approaches its window, the TUI warns once and then compacts automatically before the next request; a mid-turn overflow is self-healed by the provider SDKs. /compact remains available for manual runs.
  • Persistent input history. Submitted prompts are kept in ~/.openmed/history.jsonl (capped, local-only, skipped in DEID mode) so Up/Down recall works across restarts.

Plans, tools, and workflow cards

When the agent decides on a multi-step path, it records a plan in the chat and advances it as tools complete.

OpenMed now has two planning layers:

  • The visible phase plan is the compact checklist shown in the TUI. It is optimized for the current few steps.
  • The durable global plan is a Markdown/JSON ledger for long tasks with many requirements or deliverables. It is stored in the workspace or workflow output directory and is checked before the agent claims the full task is complete.

By default, repository-scoped ledgers are written to ./.openmed/OPENMED_PLAN.md and ./.openmed/OPENMED_PLAN.json. Workflow/output-scoped ledgers are written beside the generated artifacts as OPENMED_PLAN.md and OPENMED_PLAN.json.

Tool execution shows up inline with start/end states. Deterministic workflows can also emit cards using the current card types:

  • info
  • evidence
  • suggestion
  • uncertainty

Cards are part of the persisted session history and replay when you reopen the session.

Workflow tool receipts can also include recommended_skills and skill_hint. These fields are operator-facing guidance for loading companion overlays such as citing-evidence, handling-phi-disclosure, escalating-to-reviewer, or preparing-clinical-artifacts before summarizing, packaging, or finalizing a workflow result.

Review surfaces

There are three different review surfaces to understand:

  1. The inline conversation itself: plans, tool calls, results, and cards stay visible
  2. Deterministic workflows: draft previews can be inspected before finalization. The returned approval_token validates the workflow request parameters but is not authorization. The reviewed cards, evidence, and full artifact bytes are stored in a private, session-owned immutable snapshot identified by the draft run ID and SHA-256 digest. Snapshots expire after 24 hours by default and are removed after successful finalization, session clear/rollback, or session deletion; /drafts hides expired or missing snapshots and shows the expiry time for active ones. Missing, altered, expired, mismatched, or ambiguously selected snapshots fail closed. Reviewer-gated workflows also require review_metadata captured by the UI.

Finalized bundles are staged and committed atomically. The destination must be new, empty, or an existing OpenMed-owned bundle for the same workflow; filesystem roots, mount points, the live working directory, session state, and arbitrary nonempty directories are rejected before a draft becomes finalizable.

Delivery intent is request-scoped. If the user asks for finalized output, the app creates the immutable draft first and then finalizes that exact snapshot at turn settle. If the user asks for a draft, or does not name a delivery state, the draft is the completed result and the plan ends normally. A later message such as “looks good, send it” is interpreted by the same gpt-5.6-luna auxiliary-model path used for citation judgments and mapped to the active draft without asking for a run ID. Questions, edits, negations, classifier failures, and ambiguous targets never finalize. Reviewer-gated workflows open the reviewer-metadata form only when the final write is actually due.

  1. Approval-gated tools: the approval callback is wired on the OpenAI SDK path for tools such as edit_file

That means you should not assume every tool pauses for a modal approval, especially if you are using the Codex SDK path. Workflow delivery does not pause the plan: the host interprets delivery intent, while every draft_only=false call still requires the ephemeral one-use grant plus the verified immutable snapshot selected outside the agent model.

Slash commands

Core slash commands currently handled by the app:

Command Behavior
/clear Clear the current conversation view
/help Open help
/model Open the model picker
/skill Open the skill switcher
/agent Open the agent-mode switcher
/session Open the session switcher
/theme Open the theme picker
/phi Cycle PHI mode label
/autoapprove [on\|off] Toggle unattended auto-approval of tool prompts (each bypass is logged; workflow snapshot and reviewer safeguards are never bypassed; also openmed --auto-approve or OPENMED_AUTO_APPROVE=1 for scripted demos/tests)
/copy [n] Copy the newest message's last fenced code block to the clipboard (/copy n picks the nth); copies the original text, not the wrapped rendering. Selecting any text with the mouse also auto-copies it.
/plan Show the visible phase plan and global plan summary
/plan global Show the durable global plan summary
/plan pending Show pending or invalid global plan tasks
/plan open Print the Markdown and JSON global plan paths
/compact Compact older context
/compact thinking Remove thinking blocks only
/fork Fork the current session
/rollback N Undo the last N user turns
/undo Undo the last user turn
/mcp Show MCP server status
/workflows List deterministic workflows and required inputs
/drafts List active workflow drafts and human-readable destinations; ask naturally to finalize one
/config Show effective runtime configuration — permission mode, allow/deny/ask rules, project root, loaded settings sources, and persistence threshold
/audit Show audit status, destination, PHI payload mode, fallback path, and audit CLI commands
/reset Reset agent state

The command palette and autocomplete currently show a few entries that are not fully wired yet, such as /export and /history. Treat the table above as the stable slash-command surface.

Skills in the TUI

Type $ or use /skill to browse built-in and user-provided skills.

The current built-in library has 20 skills:

  • analyzing-clinical-text
  • analyzing-health-data
  • authoring-openmed-skills
  • auditing-medical-codes
  • care-coordination
  • citing-evidence
  • developing-fhir
  • documenting-clinical-visits
  • drafting-trial-protocols
  • escalating-to-reviewer
  • explaining-eob-claims
  • handling-phi-disclosure
  • managing-case-context
  • preparing-clinical-artifacts
  • processing-pii
  • researching-literature
  • reviewing-appeals
  • reviewing-prior-auth
  • running-clinical-workflows
  • special-pathogen-triage

See Skills for how they work and where custom skills live.

Native tools, web search, and MCP

The default registry currently includes 76 native tools. On supported Responses API models, OpenMed can also expose built-in web_search, which is separate from the registered native tools.

Those native tools cover:

  • file and artifact operations
  • extraction and PII tooling
  • consumer health imports and analysis
  • PubMed
  • ICD-10, CPT, SNOMED, LOINC, RxNorm, MedlinePlus, HCC, RAF, and crosswalks
  • workflow orchestration
  • planning and skill loading

Many of the medical tools use OpenMed's native medical service plane. They are still native OpenMed tools from the model's perspective, not MCP tools.

MCP remains optional. Use # or /mcp when you want to bring in external systems that are not already part of the native tool surface.

The newer consumer-import and care-coordination adapter paths remain local-only review flows. OpenMed does not auto-send patient messages or write back into external systems from those lanes.

Runtime settings and project instructions

OPENMED.md

Drop an OPENMED.md file in your project root (or git root) to inject per-project instructions into the system prompt. The file is loaded at SDK initialization and appended as a ## Project Instructions (OPENMED.md) section. This is useful for customizing agent behavior per workspace without modifying the built-in prompts.

Permission policy

OpenMed supports rule-based permission modes that control how tools are gated before execution:

Mode Behavior
auto Tools with requires_approval or is_destructive prompt for approval; others run freely
acceptall All tools run without approval unless blocked by a deny rule
denyall All tools are blocked outright
plan Only read-only, concurrent-safe tools are allowed; everything else is blocked

Set the mode in .openmed/settings.json at the project root or in ~/.openmed/settings.json for user-level defaults:

{
  "permission_mode": "auto",
  "allow_tools": ["read_file", "grep"],
  "deny_tools": ["edit_*"],
  "ask_tools": ["write_file"]
}

Settings cascade: CLI arguments take highest priority, then project settings, then user settings.

Use /config in the TUI to see the effective runtime configuration at any time.

Tool safety classification

Every registered tool carries safety metadata:

  • is_read_only — tool does not modify state
  • is_concurrent_safe — tool can run in parallel with others
  • is_destructive — tool may cause data loss (file writes, deletes)

These flags are used by the permission policy and will be used by future concurrent execution support.

Oversized tool result persistence

When a tool produces output exceeding the configured threshold (default 50,000 characters), the result is automatically written to disk. The model receives a compact stub with the file path, size, content type, and a 500-character preview, plus a hint to use read_file for the full content. Configure the threshold in project or user settings:

{
  "tool_result_persist_threshold_chars": 50000
}