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 agent --model gpt-5.4 --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:

Choose a model
Choose low, medium, high, or extra_high reasoning
On supported models, choose whether to show reasoning summaries

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

gpt-5.3-codex-spark skips the reasoning-summary step.

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
tool and card output

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

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.

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.

Review surfaces¶

There are three different review surfaces to understand:

The inline conversation itself: plans, tool calls, results, and cards stay visible
Deterministic workflows: draft previews can be inspected before finalization, final writes require approval_token, and care-coordination finalization also requires review_metadata
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. The stable, universal review surface is the visible conversation and the workflow draft/finalize pattern.

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
`/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
`/config`	Show effective runtime configuration — permission mode, allow/deny/ask rules, project root, loaded settings sources, and persistence threshold
`/reset`	Reset agent state

The command palette and autocomplete currently show a few entries that are not fully wired yet, such as /export, /audit, 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 13 skills:

analyzing-clinical-text
analyzing-health-data
auditing-medical-codes
care-coordination
developing-fhir
documenting-clinical-visits
drafting-trial-protocols
explaining-eob-claims
processing-pii
researching-literature
reviewing-appeals
reviewing-prior-auth
running-clinical-workflows

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

Native tools, web search, and MCP¶

The default registry currently includes 62 native tools. On supported Responses API models, OpenMed can also expose built-in web_search, which is separate from the 62 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 call configured remote services such as OPENMED_INFERENCE_URL and OPENMED_MED_CODES_API_URL. 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, except destructive tools which still prompt
`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
}