Skip to content

UPai Assistant

The UPai Assistant is a chat view embedded in UPstudio that brings an AI coding agent directly into the IDE — with access to the UP model through the integrated MCP server. Unlike the UPai Terminal, which emulates a full terminal (TUI), the Assistant drives the AI CLI headless over structured JSON and renders the conversation as a native chat.

This is the same mechanism used by IDE integrations such as VS Code: the CLI runs as a plain subprocess and exchanges JSON messages over its standard input/output — there is no pseudo terminal, no resize handshake, and no terminal key routing. As a result the Assistant behaves identically on Windows and macOS, and it can present the conversation as rich content: streamed answers, collapsible tool calls, and clickable model links.

Assistant or Terminal? Use the Assistant for a focused, readable chat about the UP model — questions, explanations, guided edits. Use the Terminal when you need the raw interactive CLI (for example the first-time /login) or arbitrary shell usage.

Opening the View

The UPai Assistant can be opened via Window → Show View → Other… → UP → UPai Assistant. It appears by default at the bottom of the UPstudio perspective (below the editor area).

No Active Session

When no session is running, the view shows a prominent start screen (empty transcript) or a warning banner at the top (when a previous conversation is still visible). Both offer:

  • ▶ Start Session — begin a fresh AI session
  • ↺ Continue Last Session — resume the most recent session in the working directory

While no session is running, the message input and Send button are disabled. They become active as soon as the session is up.

Toolbar

The toolbar is arranged in two rows.

Row 1 — context:

Element Description
Folder: (text field) The working directory of the AI session. Read-only — set via Browse….
Browse… Opens a directory selection dialog. Selecting a folder starts a new session in it.
MCP status indicator A colored circle plus label showing the live readiness of the UP MCP server: grey = off (remote access disabled), yellow = starting (enabled but not answering yet), green = ready (MCP :8088). Polled continuously while the view is open.

Row 2 — session actions:

Element Description
New Starts a fresh AI session.
Resume Continues the most recent session in the working directory.
Stop Interrupts the current turn. The session keeps running — only the in-progress answer is cancelled.
Clear Clears the chat transcript (does not end the session).
Settings… Opens the Assistant preferences.

Starting a Session

  1. Make sure a working directory is set (or let the Assistant use the workspace root).
  2. Click ▶ Start Session (or New), or enable Auto-start in preferences.
  3. If the MCP server is active, the Assistant waits for it to become ready and shows a live counter:
Waiting for MCP server on port 8088… (6 s)
  1. Once the CLI process is up, the input field is enabled and you can start chatting.

For a new Claude session with MCP active, the Assistant automatically loads the UP startup prompt (/mcp__up__startup) as the first action, so the agent starts already grounded in the UP model context. Because a CLI connects to its MCP servers asynchronously, the command is retried until the MCP tools are registered — this happens transparently.

Chatting

  • Type your message in the input field at the bottom.
  • Enter sends the message; Shift+Enter inserts a line break.
  • Type / at the start of the input (or press Ctrl+Space) to get content assist for slash commands. The list is provided by the CLI itself, so it always reflects the installed commands and plugins.

While the agent is working, a pulsing indicator shows whether it is thinking or working. Use Stop to interrupt.

The Transcript

The conversation is rendered as formatted content:

  • Markdown — headings, lists, bold, inline code, fenced code blocks, links, and GFM tables.
  • Tool calls appear as collapsible chips showing the tool name, its input, and — once finished — a status (✅ done / ❌ error) with the result. Click a chip to expand it.
  • Clickable GUIDs — any Actifsource GUID in the output is rendered as an underlined link; clicking it opens the corresponding resource in the UPstudio editor. GUIDs are never wrapped or shortened.
  • Auto-scroll sticks to the bottom while the answer streams in. Scroll up to read earlier content and it stops following; scroll back down to re-engage.

Tool Permissions

  • Claude asks before running a tool it is not pre-approved for. A native dialog offers Allow, Always Allow (this session), or Deny, and shows the tool input. The UP MCP tools are pre-approved and never prompt.
  • Copilot runs headless with all tools allowed — there is no interactive approval step in this mode.

Supported AI Tools

The Assistant is tool-independent; the AI backend is chosen in the preferences.

Tool Status Notes
Claude Full support Long-lived process, streaming; interactive tool-permission dialogs; auto UP startup prompt.
GitHub Copilot Full support One process per turn (multi-turn via --resume); runs with all tools allowed (headless mode has no interactive approval).
Gemini Planned Selecting it reports that support is not available yet.
Codex Planned —
Other Custom A Claude-compatible command or absolute path.

MCP Integration

The Assistant is tightly integrated with the UP MCP server. Once Actifsource remote access is active (Window → Preferences → Actifsource → Remote access), the server configuration is passed directly to the CLI at session start:

{
  "mcpServers": {
    "up": {
      "url": "http://localhost:8088/mcp/actifsource",
      "type": "http"
    }
  }
}

Unlike the Terminal, the Assistant does not write a .mcp.json into your working folder — the configuration is handed over on the command line and scoped strictly to the UP server, so no other MCP servers leak into the session. The port is read from the UPstudio preferences (default: 8088).

Context Menu Integration

Every resource in the Actifsource Model Navigator has an Ask AI context menu entry. It opens the UPai Assistant and asks the agent to explain the selected resource (asr://<guid>), which the agent reads through the MCP server.

Preferences

Assistant preferences are shared with the Terminal and accessible via:

  • The Settings… button in the toolbar
  • Window → Preferences → UPai Assistant
Setting Description
AI Tool Which CLI to launch: Claude (default), Copilot, Gemini (planned), or Other (custom/Claude-compatible command).
Auto-start Start an AI session automatically when the view opens.
Working directory Eclipse workspace root (default) or a custom path. Can be overridden with Browse….

Theme

The Assistant automatically adapts to the active Eclipse theme (dark / light). Background, text, code, table, and tool-chip colors are derived from the SWT view theme.

Technical Notes

  • No PTY: the CLI runs in headless mode over plain stdin/stdout pipes (claude -p … --output-format stream-json; copilot -p … --output-format json). This removes the terminal-emulation, resize, and keyboard-routing problems entirely and makes behavior identical across operating systems.
  • Per-turn model (Copilot): copilot -p exits after each turn, so the Assistant runs one process per turn and chains them with --resume <sessionId> to preserve context.
  • Login-shell PATH: an IDE launched from the Finder/Dock or Start menu does not inherit the user's shell PATH. The Assistant passes the login-shell PATH to the CLI so it (and the tools it runs) resolve correctly — for example Copilot obtaining its GitHub authentication via gh.
  • Rendering: the transcript is an embedded browser used purely for display; all keyboard input goes through a native SWT field, so none of the Terminal's input-routing paths are involved.