ShellX Manual

Install and update

Use a signed installer for your platform. Settings → About checks the updater feed on Windows, macOS, and Linux AppImage installs; Linux deb and rpm packages update manually.

1. Download an installer from the ShellX GitHub releases page.
2. Download SHA256SUMS from the same release and verify the installer digest before launch; platform signing or notarization must pass separately.
3. Launch ShellX and open Settings → About to confirm the running version.
4. Treat a locally built candidate and the latest public release as different artifacts until their hashes and installed behavior are verified.

First session

Choose a project folder, connection, agent, and permission mode before sending the first prompt.

1. Create a tab and choose a project-scoped working folder with the folder pill.
2. Choose Local, WSL, or a saved SSH connection with the correct POSIX, native Windows, or Windows-plus-WSL runtime.
3. Choose Grok, Codex, Claude, or another available provider and send a focused prompt.

BoundaryDo not point a Full Auto agent at an entire home directory or an untrusted repository.

Know what is actually ready

The Tools and Environment surfaces distinguish an installed CLI, a connected session, healthy host tooling, and a finished task.

1. Scan agent CLIs for the selected environment.
2. Open Tools to inspect provider, MCP, Preview, and environment readiness.
3. Use receipts and installed behavior—not a source build alone—as completion evidence.

Tabs and session identity

Each tab owns its connection, working folder, agent session, permission mode, and recent activity.

1. Check the connection and folder pills before sensitive or destructive work.
2. Use a new tab when changing projects or authority boundaries.
3. Reopen saved conversations from history without assuming the old environment is still available.

Files and Git

Browse project files, preview common formats, inspect diffs, and create local checkpoints without leaving ShellX.

1. Use Files for the active project tree and safe previews.
2. Use Git for status, diffs, checkpoints, and worktree visibility.
3. Keep unrelated or other-agent changes out of a scoped commit.

Attachments and media

Paste, drop, attach, or send files into a session, then review generated images and videos in the Assets board.

1. Add attachments as chips before sending the prompt.
2. Open Assets to review pending and generated media for the current session.
3. Use Preview Center for markdown, code, images, video, PDF, and generated web apps. Video previews keep native media controls and add a visible Play/Pause control whose state is exposed to assistive technology.

Create a task from chat

Ask the current agent to create, schedule, or create and run a task. ShellX fills the definition from the conversation and uses the exact current environment and available agents.

1. Say what should happen and when, for example: Set this up as a task every weekday at 09:00 and run it now.
2. That explicit request authorizes the agent to save the Task; ShellX verifies the current environment and ordered agents before it writes anything.
3. Open Tasks in the header to review the saved definition and results. Use Edit details only when you want to change the prepared values.
4. Use Create task below the composer when the Task must carry reviewed attachments, a Browser workflow, or Vault requirements.

Open Task Manager

The header Tasks button opens a concise review panel for saved definitions, schedules, ordered agents, run history, and attention.

1. Use the Tasks header button from any session.
2. Filter definitions by attention, scheduled, paused, or recent state and select one row to review What, When, Agents, Where, Run time limit, permissions, notifications, and receipts.
3. Use Run now, Pause or Resume, Duplicate, Delete, Open run, and Cancel run only when the selected state enables that exact action.
4. Select Edit details when you need the full schedule, environment, or agent editor; otherwise the saved Task stays read-only.

BoundaryThe Tasks right-rail tab remains the live process monitor. Task Manager is the definition and scheduling surface.

Choose agents for an environment

ShellX checks Grok, Codex, Claude, and Antigravity on the Task's computer or saved connection and shows the order it will try them.

1. Select This computer or one of your named saved connections before choosing agents.
2. Review each agent's current ready, unavailable, authentication-needed, or inconclusive status.
3. When asking an agent to create the Task, name any backup agents you want or let ShellX use the current ready agent.
4. Use Edit details to change the order. ShellX moves to the next only when the earlier agent proves the task never started; an uncertain start becomes attention instead of duplicate work.

Schedule one-time or recurring work

Choose manual, once, daily, weekdays, weekly, or monthly execution with a simple date or local time picker. ShellX uses the execution computer's clock by default.

1. Choose Run now for an immediate manual occurrence or select a named schedule.
2. Choose the date and time as you normally would on that computer; the summary stays in familiar local time.
3. Open Advanced timing and notifications only when you need to keep another location's timezone, choose missed-run behavior, change the per-run safety limit, or change notifications.
4. Keep ShellX and the execution host available at the scheduled time; the foreground scheduler records missed, deferred, and attention states explicitly.

Review runs and attention

Every occurrence keeps a compact timeline for provider preflight, selected route, start, progress, terminal result, evidence, and any attention that needs an operator decision.

1. Open a run to return to its normal private ShellX conversation when the Trace receipt says the archive is reviewable.
2. Compare the saved definition snapshot with the fresh execution scan before trusting a provider or target claim.
3. Acknowledge an attention item only after reviewing its exact occurrence and receipt-backed reason.

Create a task from Browser Teach

An approved, exported, and zero-skip rehearsed Browser workflow can open a paused Task draft with its workflow digest and reviewed Vault grant identities.

1. Complete Teach review, approval, export, and rehearsal for the exact workflow revision.
2. Open the Task draft from the Browser handoff and review the workflow and Vault identities in the originating ShellX session.
3. Choose the provider route and schedule, then save explicitly.

Local

Local sessions run the provider CLI on the same operating system as ShellX and use native paths.

1. Install and sign in to the provider CLI for the current OS user.
2. Scan CLIs in the connection editor.
3. Choose a project folder that the provider is allowed to modify.

WSL

WSL sessions use wsl.exe, Linux paths, and the selected distribution's agent installations. When ShellX tooling exposure is enabled, host-tool calls use the ShellX bridge to reach the parent desktop host.

1. Add a WSL preset with the exact distribution name.
2. Install and authenticate the agent CLI inside that distribution.
3. Use the environment scan to confirm the Linux-side binary and version.

SSH to Linux, macOS, or WSL

Use the direct POSIX runtime for Linux, macOS, or an sshd running inside WSL. ShellX keeps POSIX paths and commands in that remote environment; with ShellX tooling exposure enabled, host-tool calls use its reverse bridge to reach the parent desktop host.

1. Complete host-key and key-agent setup in a normal terminal first; ShellX uses BatchMode.
2. Save the SSH host, optional port, and optional Vault reference to a private-key path.
3. Test the connection and scan remote CLIs before starting a session.

Native Windows OpenSSH

ShellX can run Windows-installed CLI agents directly through Windows OpenSSH with encoded PowerShell commands, streamed setup input, and Windows paths. WSL is not required.

1. Choose Windows OpenSSH, run Windows agents when the CLI and project live on Windows, then use a Windows absolute project path such as C:\Users\you\project.
2. Test the connection and scan the destination. ShellX uses PowerShell-safe discovery and setup recipes for Windows Codex, Claude, Grok, and Antigravity installations; an explicit Grok path must be a bare command or absolute Windows path and never falls back to a different binary.
3. Start the provider normally. The Windows runtime supports native provider/Grok launch, stdin setup, cwd validation, ACP file reads and writes, Files, Preview Center reads, Git, session archives, activity evidence, vision reads, marketplace health checks, Work Preview servers and tunnels, and ShellX-managed Grok subagent launch.

BoundaryTest Connection verifies the transport; Scan CLIs refreshes the destination binary and version; starting a session verifies provider authentication and the live protocol path. A passing transport check alone does not prove that a provider is installed or signed in.

Windows OpenSSH plus WSL

ShellX can connect through native Windows OpenSSH and run the tab inside an explicitly selected WSL distro.

1. Choose Windows OpenSSH, run agents in WSL as the SSH remote runtime and enter the exact distro name from wsl.exe -l -q.
2. Use Linux paths for the tab, including a bare command or absolute POSIX Grok path. WSL can reach Windows files under /mnt/c and can invoke Windows executables when interop is enabled, but ShellX rejects Windows paths in this runtime and never switches to another binary silently.
3. Enable mirrored WSL networking on the remote PC so the WSL agent can reach ShellX's reverse host-MCP tunnel on Windows localhost. Connection testing fails closed with setup guidance when this loopback path is unavailable.

BoundaryThis optional runtime executes agents inside WSL. It does not replace the required native-Windows runtime for ordinary Windows PCs without WSL; using a WSL sshd endpoint is also supported.

Header: About ShellX

Click the ShellX wordmark to open the canonical About surface with the running version, source link, update status, and diagnostics entry points.

Header: Find

Find searches the available conversation corpus and opens the selected chat without changing its project or connection identity.

Header: Browser

Browser opens the separate ShellX Browser workspace; it does not silently create, focus, or navigate an agent task.

Header: Vault Request Center

The request badge opens pending Browser, Vault, session, and client approval requests so the operator can inspect and decide each exact operation.

Header: Connector inbox

The connector inbox appears when configured Telegram or Discord events need attention and opens the recent inbound-event surface.

Header: Plugins

Plugins opens the global MCP server and connector catalog. Installation, enablement, required Vault keys, and current session health are separate states.

Header: Theme

The moon or sun control switches between dark and bright ShellX themes and persists the chosen appearance.

Header: Settings

Settings opens the tabbed application preferences dialog; changes save automatically and Escape closes it.

Left rail: Projects

Projects groups open and stored chats under operator-named labels. The plus button creates a label; expanding a row reveals its filed chats.

Left rail: Open chats

Open chats lists live tabs for quick focus, rename, move, or deletion without confusing a UI project label with a filesystem folder.

Left rail: Past chats

Past chats lists closed on-disk sessions. Reopening restores conversation history but does not guarantee that the old connection or provider is still available.

Right rail: Tasks

Tasks shows running and recent background processes for the active session, including attribution when ShellX can identify the owning tab or agent.

1. Agent runs separates tab sessions, provider runs, ShellX host subagents, and provider-native subagents exposed by the provider stream.
2. A provider-native subagent row follows its structured child identity from active to terminal status and shows an exposed parent identity instead of duplicating each event.
3. Pause, Resume, and Kill act on the exact visible task row; use the disclosure arrow to inspect its bounded recent output before stopping it.
4. The red Host MCP cleanup control appears only when the active tab owns live Host MCP children. Click once to arm it, review the changed warning state, then click again within five seconds to clean only that tab's process trees.
5. When a provider does not expose native subagents, ShellX says not exposed rather than inferring hidden work.

Right rail: Tools

Tools reports the selected connection, provider CLI, ShellX host exposure, MCP configuration, environment checks, capability health, and a typed ShellX Cut status for the selected session without showing Cut's full generated catalogue.

1. Select Check to query the parent desktop-host Cut bridge. Check never opens the Cut editor.
2. Select Open only as an explicit operator action when the current Cut status says an installed desktop editor can be opened.

Right rail: Git

Git shows status, diffs, local checkpoints, branches, and worktrees for the active project-scoped working directory.

Right rail: Preview

Preview starts and inspects supported local web work, including process output, loopback URL, screenshots, and Preview Doctor evidence.

Right rail: Plan

Plan displays the active build or goal scratchboard and routes review actions to the current tab rather than treating a stale plan file as live state.

Right rail: Files

Files browses the active tab's project tree, opens supported previews, and lets files be attached to the current prompt.

Bottom panel: Chat

Chat shows the streamed provider conversation and the composer for the active session tab.

Bottom panel: Terminal

Terminal provides a persistent operator-owned shell for the active session tab. Provider-originated ACP terminal requests stay disabled and cannot attach to this shell.

Bottom panel: Trace

Trace opens the session activity browser for recorded files, tools, commands, searches, and media references.

Trace: Files

Files groups recorded activity into a searchable folder and file tree with read, write, delete, search, command, Git, and media counts.

Trace: Graph

Graph visualizes the session, action kinds, folders, and files as a movable evidence graph with weighted links and a selected-node detail panel.

Trace: Evidence

Evidence separates changes, reads and searches, commands, and Git activity into resizable panes while preserving verified, observed, and inferred confidence.

Trace: Timeline

Timeline orders the recorded session activity by time so file, command, search, Git, and media events can be correlated without implying missing telemetry never occurred.

Trace: Summary

Summary condenses source status, action totals, current build state, and recent build receipts for handoff or review.

Bottom panel: Assets

Assets opens the full attachment and generated-media board for the active session rather than switching to one media-type tab.

Bottom panel: Images

Images opens the active session's image gallery even when it is empty, then collects generated or detected image artifacts for preview as they arrive.

Bottom panel: Videos

Videos opens the active session's video gallery even when it is empty, then collects generated or detected video artifacts for preview as they arrive.

Bottom panel: Logs

Logs shows the recent structured ACP and ShellX event stream for diagnosis; it is evidence, not a replacement for final output or Git state.

Bottom panel: Stderr

Stderr isolates recent provider and process error output so failures are not hidden inside normal chat rendering.

Composer: Connection

The connection pill selects Local, WSL, or a saved SSH environment for this tab and exposes connection testing and CLI scanning.

Composer: Agent

The agent picker selects the provider runtime installed in the tab's chosen environment; changing it does not migrate an existing provider process.

Composer: Working folder

The folder pill selects the tab's working directory. Confirm it before granting write authority or sending a destructive request.

Composer: Branch

The branch picker shows and changes Git branches for the active working directory while preserving the tab's connection frame.

Command palette: Connect agent session

Connect starts the selected agent in this tab's current connection, working folder, and autonomy frame; confirm all three before running it.

Command palette: Abort current session

Abort requests cancellation of the active provider startup or turn in this tab; startup cleanup may finish asynchronously, and it does not silently terminate unrelated tabs or background agents.

Command palette: New session tab

New session tab creates another ShellX tab while preserving existing sessions, so connection and provider choices remain independently reviewable.

Command palette: Close current tab

Close current tab removes only the selected ShellX tab after the normal session-close path; it does not close the whole application.

Command palette: Open settings

Open settings displays the complete tabbed Settings dialog, beginning on its current or General tab, without changing provider state by itself.

Command palette: Desktop integrations

Desktop integrations opens Settings directly on the Desktop tab, where file-send and operating-system integration status can be reviewed.

Command palette: Attach file

Attach file opens the platform picker and adds the selected path as a visible composer chip; the file is not sent until the prompt is submitted.

Command palette: Attach app screenshot

Attach app screenshot captures the current ShellX window into an owned image file and adds that exact image as a removable composer attachment.

Command palette: Attachment and media board

Attachment and media board opens the session's full attachment, image, and video workspace so generated and pending media can be inspected together.

Command palette: Open Work Preview

Open Work Preview selects the Preview right rail and opens the Preview Center in work mode for the active tab's current preview state.

Command palette: Preview Doctor

Ask active agent to fix current preview appears only after a preview URL exists or preview startup fails; it collects bounded diagnostics and sends the repair request to the active agent.

BoundaryThis conditional action appears between Open Work Preview and Toggle Chat / Terminal. The highlighted image shows its Preview destination because the idle palette capture correctly omits unavailable actions.

Command palette: Toggle Chat / Terminal

Toggle Chat / Terminal switches the active bottom panel between the conversation and terminal views without changing any other session tab.

Command palette: Create pull request

Create pull request opens the local review dialog for the active repository; opening the dialog does not publish or mutate a remote repository.

Command palette: Open Vault

Open Vault displays the Vault workspace at its overview without reading or revealing secret values merely because the panel was opened.

Command palette: Keyboard shortcuts

Show keyboard shortcuts opens the full shortcut dialog, which is separate from the smaller composer help popover beside the prompt.

Command palette: Autonomy Auto

Autonomy Auto selects bypassPermissions for the active tab; use it only when the requested work and environment justify unattended actions.

Command palette: Agent slash commands

The Slash rows list commands actually advertised for the active agent and environment; choosing one inserts it into the composer rather than executing it immediately.

Composer: Attachments

Attach or drag files into the prompt as visible chips; inspect the paths and remove unintended files before sending.

Composer: ShellX screenshot

Captures the current ShellX window and adds it as a visible prompt attachment; it does not capture another desktop window.

Composer: Voice

Voice records speech for the active tab only, shows unavailable or credential states, and prevents a stale voice owner from leaking across tabs.

Composer: Keyboard help

The inline help popover lists composer shortcuts and interaction hints without taking permanent space from the chat.

Composer: Send or stop

Send submits the visible prompt and attachments to the active tab. While work is running, the same action surface exposes the applicable stop behavior.

Settings: General

General controls chat typography, density, appearance, downloads, and optional new-session defaults. Choose an agent and starting folder when you want every new tab ready to type and send; leave the agent unset to choose per session, and leave the folder unset to reuse the last one. Model and reasoning choices remain with the selected provider.

Settings: Vault

Vault manages passwords and keys, typed resources, active grants, and profile setup through the current shared Vault backend.

Vault: Passwords & keys

Passwords & keys opens the stored-resource list and editor area while keeping secret values hidden unless the operator explicitly reveals or copies one.

Vault: Active grants

Active grants lists current mediated permissions and lets the operator inspect or revoke access without exposing the underlying secret value.

Vault: Setup

Setup configures the shared Vault backend, unlock and recovery state, remembered-device behavior, and standalone Vault connection details.

Vault resource: Password/key

The Password/key editor stores a named secret with optional safe metadata, user-only visibility, and an integrated strong-password generator.

Vault resource: Profile

The Profile editor groups contact and identity fields into a reusable profile card for approved, mediated form-filling workflows.

Vault resource: Agent wallet

The Agent wallet editor stores reference-only Stripe configuration, budget constraints, allowed origins and categories, and an explicit operating status.

Settings: Connections

Connections reviews saved Local, WSL, and SSH presets; editing and environment-specific CLI scans remain available from the connection picker.

Settings: Connectors

Connectors configures supported outside messaging surfaces and shows their availability and setup state.

1. Delivery and Session chat approval are independent: choosing Session chat preserves Review first by default, while Auto-dispatch is a separate explicit choice.
2. For Telegram, allowlisting a group chat authorizes every participant in that group; keep per-message approval enabled or use a private chat when Session chat can dispatch agent work.
3. Discord Session chat accepts allowlisted direct-message user IDs rather than channel or guild IDs.

Settings: Desktop

Desktop controls host operating-system integrations and handoff behavior that do not belong to an individual agent tab.

Settings: shellXagent

shellXagent configures the authenticated local API and agent-facing ShellX integration status; it does not globally enable the ShellX host skill.

Settings: Data

Data shows storage and retention controls for local ShellX state and provides explicit maintenance actions.

Settings: About

About shows the running version, source and issue links, update diagnostics, and release-readiness information.

Browser tabs: New tab

Creates a normal tab in the currently selected Browser profile. The visible profile marker and ownership banner identify its authority.

Browser tabs: New disposable tab

Creates a task-disposable tab with separate per-task web storage. Finishing or aborting the task, or closing its tab, retires that storage so a later disposable task starts empty.

Browser tabs: Agent tab lock

Locks or unlocks the active tab for the current agent lease so another actor cannot silently take control.

Browser tabs: Personal Browser Lock

Locks personal Browser content immediately or opens lock setup when no personal lock has been configured.

Browser tabs: Hand off

Opens a ShellX-owned review of the sanitized page context, profile persistence, current owner, selected task, and separate Vault boundary before handing the exact active tab to the agent task.

Browser tabs: Take back

Returns a delegated tab to the operator without changing its URL, profile, or task history.

Browser tabs: Show or hide right panel

Shows or hides the agent cowork panel without changing the Browser task, tab owner, or page.

Browser toolbar: Back

Moves the active tab backward in its navigation history when a Browser tab is available.

Browser toolbar: Forward

Moves the active tab forward in its navigation history after a backward navigation.

Browser toolbar: Reload

Reloads the active page without changing the selected tab, profile, or ownership.

Browser toolbar: Home

Navigates the active tab to the configured Browser homepage.

Browser toolbar: Trust and shields

Opens the current page security and shields summary so transport trust, filtering, and compatibility state are visible.

Browser toolbar: Address

The address field navigates to a URL or search target in the active Browser tab.

Browser toolbar: Copy address

Copies the current page URL without copying page content or changing Browser state.

Browser toolbar: Bookmark current page

Adds the active page to Browser bookmarks using the current title and URL.

Browser toolbar: Vault fill

Opens matching Vault fill candidates for the visible page; it stays disabled when no approved or eligible match exists.

Browser toolbar: Downloads

Opens current and recorded transfer intents, completion state, final paths, and the default download folder control.

Browser toolbar: Bookmarks

Opens the bookmark list or manager for navigation, folders, pinning, rename, URL editing, sorting, and deletion.

Browser toolbar: History

Opens Browser history with separate User and Agent scopes, search, date filtering, and an explicit clear action.

Browser toolbar: Save page

Opens local artifact and queued copy choices; each Save page item below is documented separately.

Browser toolbar: Ads filter

Opens the three visible ad-filter policies—Balanced, Strict, and Off—without exposing the legacy internal compatibility value.

Browser toolbar: Browser settings

Opens Browser-specific appearance, homepage, profile, sidebar, personal-lock, and agent-engine preferences.

Save page: Full-page screenshot

Writes a PNG of the complete scrolling page to ShellX-owned Browser artifacts.

Save page: Window screenshot

Writes a PNG of the currently visible Browser window.

Save page: Markdown

Writes readable extracted page text as a local Markdown artifact.

Save page: Links JSON

Writes the visible rendered-page links as structured JSON.

Save page: Snapshot bundle

Writes a bounded bundle of Markdown, links, and screenshot metadata for review.

Save page: Queue media copy

Queues a copy job for eligible images, video, and audio instead of pretending the material is already saved.

Save page: Queue code copy

Queues a copy job for eligible HTML, CSS, and script resources.

Save page: Queue site copy

Queues an offline-site copy job whose progress and final result must be reviewed.

Ads filter: Balanced

Blocks common advertising noise while prioritizing site compatibility.

Ads filter: Strict

Blocks matching advertising and tracker requests before load, with a greater chance of site breakage.

Ads filter: Off

Loads the page without ShellX ad filtering; normal Browser and network security boundaries still apply.

Browser settings: Color mode

Chooses System, Light, or Dark appearance for the Browser workspace.

Browser settings: Homepage

Sets the URL used by the Browser Home button for the active Browser profile.

Browser settings: Default profile

Chooses the default Browser profile for new normal tabs; the visible profile marker confirms the active choice.

Browser settings: Right sidebar

Controls whether the agent cowork sidebar is shown by default.

Browser settings: Enable Personal Browser Lock

Enables or disables the personal-tab lock and exposes the immediate Lock or Unlock action.

Browser settings: Lock timeout

Chooses the inactivity period before personal Browser tabs lock.

Browser settings: Unlock method

Chooses device authentication when available or a ShellX session PIN.

Browser settings: Personal lock PIN

Sets or updates the session PIN used when PIN unlock is selected or device authentication is unavailable.

Browser settings: Cover locked personal tabs

Covers locked personal-tab content so it is not left readable in the Browser workspace.

Browser settings: Pause delegated tabs

Pauses delegated Browser tabs when Personal Browser Lock engages.

Browser settings: Lock after system sleep

Locks personal Browser tabs when the operating system resumes from sleep.

Browser settings: Lock when minimized

Optionally locks personal Browser tabs whenever the Browser window is minimized.

Browser settings: Parallel agents

Chooses automatic or explicit Browser agent concurrency limits without granting additional tab ownership.

Browser right panel: Chat

Shows the human-agent Browser cowork conversation, task goal, and page-explanation prompt for the active task.

Browser right panel: Requests

Shows pending Vault and sensitive Browser prompts that require a direct operator decision.

Browser right panel: Actions

Shows current task controls, recent Browser actions, console information, and receipts in collapsible sections.

Browser Actions: Tasks section

Tasks expands or collapses the current Browser task controls and recent task state without changing task ownership or lifecycle by itself.

Browser Actions: Receipts section

Receipts expands or collapses the recent bounded Browser action receipts used to review what the active task actually attempted.

Browser right panel: Evidence

Records a bounded, redacted attempt for the current Browser task and reviews Flight Recorder identities, hashes, completeness, and comparisons. Developer Inspection summarizes the live task; after completion, Teach workflow selects the most recent complete attempt for review, approval, and zero-action rehearsal. Private artifact paths and page content stay out of the panel.

Browser right panel: Errors

Shows current Browser/runtime errors separately from normal action and chat history.

Browser Errors: Page errors section

Page errors expands or collapses the bounded page-console records, including level, message, time, and source location when available.

History sidecar: User and Agent

Switches between personal browsing history and agent/task history so the two are not silently blended.

History sidecar: Search and date filter

Filters the selected history scope by text and date without deleting stored entries.

History sidecar: Clear history

Clears the selected User or Agent history scope. Choosing All opens a dedicated confirmation, while search and date filtering leave stored entries unchanged.

Bookmarks sidecar: List

Browses bookmarks and folders and opens the chosen saved URL.

Bookmarks sidecar: Manage

Creates persistent links, folders, toolbar pins, and workflow bookmarks; rename, URL, order, and deletion changes remain in place after ShellX restarts.

Downloads sidecar: Default folder

Shows and changes the default download folder before future transfers are accepted.

Downloads sidecar: Transfer list

Shows pending, completed, and failed Browser transfers with truthful destination and status information.

Provider sessions

ShellX can host Grok over ACP and run supported provider CLIs with streamed output and per-tab continuity.

1. Sign in to each provider in the target environment before selecting it.
2. Use the provider's native file, patch, terminal, and MCP tools for ordinary project work.
3. Use explicit ShellX handoffs when a workflow needs another provider or the desktop host.

Agent CLIs status

The right-rail Agent CLIs card scans the active local, WSL, or SSH target when the tab opens instead of trusting only the version saved by an older connection scan.

1. Read each provider row as target-specific: the Windows and WSL sides of one PC can have different binaries, versions, and sign-ins.
2. On Windows, ShellX scans the official OpenAI Codex install directory as well as the supported user-local Grok, Claude, Antigravity, Bun, Cargo, and npm roots before reporting readiness.
3. Use Refresh after installing or updating a CLI while ShellX is already open.
4. A saved scan is only a picker hint; the active-tab scan is the current binary readiness result. Provider authentication is negotiated when the session starts and may still require sign-in on that exact target.

Session capabilities

Session Tools derives readiness from the current agent's advertised catalog instead of assuming every provider has the same native features.

1. Search capabilities separately report native web search, native page fetch, and ShellX-hosted X search.
2. Advanced capabilities separately report provider-native image generation, Browser control, subagents, and code search, plus ShellX-hosted desktop and LSP tools.
3. Read NATIVE as functionality advertised by the selected CLI in this session; read HOST as a ShellX-hosted capability. A waiting row is not presented as working.

Grok CLI

Grok uses a persistent ACP session with native approvals, tools, images, MCP servers, and provider-native continuation where the installed CLI advertises them.

1. Use Grok-native tools for ordinary work and X search when the installed ACP capability handshake exposes it.
2. ShellX negotiates Grok ACP as initialize, headless authenticate, then session creation. It reuses an advertised cached login or API-key method and never strands the session in an interactive browser flow.
3. Run grok login in the target environment before connecting; for remote or headless targets use grok login --device-auth.
4. ShellX attaches its host MCP only to the launched session; legacy global ShellX Grok guidance and MCP registrations are removed on upgrade.
5. Treat the Windows host and a WSL Grok installation as separate connection targets.
6. On Windows, ShellX adds supported user-local CLI directories to its provider launches and terminal children without rewriting the account's persistent PATH.

Codex CLI

The Codex CLI uses structured JSON output with provider-native continuation, approvals, tools, and a per-process ShellX instruction/MCP override.

1. Sign in to Codex in the selected target environment.
2. ShellX passes compact session rules and a tab-bound MCP token only to the launched Codex process.
3. Use Codex-native project tools first and ShellX Browser, Vault, evidence, and handoff tools only when the task needs the desktop host.

Claude Code

Claude Code uses bidirectional stream-json with native tool events, continuation, permission modes, and a private ShellX MCP config for the selected tab.

1. Sign in with the installed Claude Code CLI; ShellX does not route subscription credentials through the Agent SDK.
2. ShellX adds its compact instruction only for the launched process and stores the tab-bound MCP file outside Claude's global discovery paths.
3. Use Claude-native tools for normal code work and verify final file and Git state before completion.

Antigravity CLI

Antigravity 1.1.8+ streams typed text, tool, subagent, conversation, and usage events while retaining its native Browser, web search, image generation, and coding tools.

1. Install and sign in to Antigravity in the selected environment.
2. ShellX attaches a unique private additional workspace and named agent only to this launched session; direct Antigravity sessions do not inherit ShellX activation.
3. Prefer native Antigravity tools, including generate_image when available. ShellX host MCP is disabled because 1.1.8 through 1.1.11 print-mode canaries never produced a real MCP tools/call; return to ShellX for host Vault, evidence, or handoff work.

BoundaryThe 1.1.11 CLI discovered the exact canary schema, but its execution backend rejected four attempted invocation spellings as unknown tools; the MCP server received no tools/call. The tiny failed probe consumed about 71k tokens, so ShellX does not advertise this as working functionality.

Session-scoped ShellX host activation

ShellX host guidance and tools are injected only into agents launched by ShellX; direct CLI sessions do not inherit a global skill, MCP server, or instruction block.

1. ShellX passes compact runtime rules and a tab-bound, session-scoped host MCP configuration when it launches a provider.
2. The full reference remains in ShellX-owned agent docs and the authenticated Debug API, outside global provider skill discovery.
3. Upgrades remove exact legacy global ShellX skill leaves and ShellX-marked Grok config or AGENTS blocks while preserving unrelated user content.

Provider execution authority

ShellX coding-agent sessions run in provider-native Full Auto.

1. Treat Full Auto as project-scoped trust, not blanket machine approval.
2. Operator-gated Browser and Vault actions remain separately gated even when the coding provider is automated.
3. Use a trusted project folder and environment because provider-native shell and file tools can execute without ShellX confirmation prompts.

Host MCP

Confirmed ShellX sessions can receive tab-bound host tools for status, Browser, Vault, ShellX Cut video editing, previews, processes, media, and provider handoffs.

1. Start with the compact capability summary when it is advertised.
2. Browser automation is advertised through two routed tools: browser_read for bounded observations and browser_act for permission-gated changes; verbose compatibility schemas remain on-demand instead of entering every prompt.
3. ShellX Cut is advertised through cut_read for bounded typed status/search/schema discovery and cut_act for permission-gated use of one exact video-editing verb; Cut's generated catalog stays out of the default prompt, and status checks never open the editor.
4. When ShellX tooling exposure is enabled, WSL and SSH agents use the WSL relay or SSH reverse tunnel to reach the parent desktop host for ShellX tools, including Cut.
5. Browser observations default to a 3,000-byte structured-response budget and expose their serialized byte and approximate token counts; use extraction or an explicit larger/full request only when necessary.
6. Prefer provider-native file tools for the selected remote cwd; ShellX host file tools address the parent host filesystem.
7. Use mutating host tools only when the ShellX UI and active tab make the authority visible.

Open the Browser workspace

Use the Browser header entry for human browsing or let a confirmed ShellX-hosted agent start a disposable task.

1. Use personal tabs for your own browsing and task-disposable tabs for agent work.
2. Check the visible profile, URL, task, and lock state before acting.
3. A background health check must not open, focus, navigate, or mutate Browser state.

Human-agent cowork

A human can delegate an exact tab/task while ShellX keeps ownership, locks, prompts, and receipts visible.

1. Start or select a Browser task and choose the intended profile.
2. Delegate only the tab and scope needed for the current objective.
3. Resolve personal-tab permissions, dialogs, and sensitive decisions in the operator UI.

Observe and act with stable references

Agents observe bounded DOM/accessibility state, then act on stable references with stale-target and motion checks.

1. Observe the page and use returned refs instead of inventing selectors.
2. Re-observe after navigation or when a stale fingerprint blocks an action.
3. Use coordinate actions only for visual-only controls and never to bypass a Vault-mediated credential path.

Sensitive actions

Sign-ins, purchases, uploads, downloads, account changes, secret use, and other consequential actions remain explicit and reviewable.

1. Review the target site, exact operation, and data being submitted.
2. Approve or deny the corresponding Browser/Vault request in ShellX.
3. Inspect the redacted receipt and final page state before calling the task complete.

Fill from Vault

Browser fills use an approved Vault grant so durable secret values stay out of the agent transcript.

1. The agent lists safe Vault metadata and requests one exact use.
2. The operator approves a bounded grant in the Vault Request Center.
3. ShellX injects the value into the intended Browser field and returns redacted evidence.

Downloads, workflows, and recovery

Downloads expose final paths, reusable workflows keep scope metadata, and failed actions retain truthful step results.

1. Review download path and completion state before consuming an artifact.
2. Save a workflow only when its replay steps, domain scope, and permission assumptions are clear.
3. On failure, inspect the stopped step, recovery evidence, page state, and receipt instead of treating continued execution as success.

Create or connect a Vault

ShellX resolves the canonical Vault profile, migrates legacy profile locations, and can connect to an existing standalone Vault profile.

1. Open Settings → Vault or the Vault header entry.
2. Create a local Vault or connect to the intended existing profile.
3. Save recovery material and verify the selected profile before importing secrets.

Lock, unlock, and recovery

Vault data is encrypted at rest; remembered-device unlock and recovery behavior belong to the Vault profile, not an agent session.

1. Unlock in the operator UI when a grant-backed operation requires it.
2. Lock manually before leaving the machine or changing operator context.
3. Test recovery material before depending on the Vault as the only copy of a credential.

Secrets and typed resources

Store API keys, logins, identities, cards, wallets, and other typed resources with descriptions and visibility policy.

1. Use a stable resource name and a description that is safe for an agent to see.
2. Choose user-only, ask-each-use, or policy-allowed behavior deliberately.
3. Avoid copying durable values through chat when the user can enter them directly in Vault.

One integrated Vault backend

ShellX sessions, SSH keys, subagents, marketplace connectors, diagnostics, and host tools resolve the same current Vault profile.

1. Add or update a resource in the integrated or compatible standalone Vault profile.
2. ShellX active consumers read and write through the shared backend rather than reopening legacy vault.enc storage.
3. Use legacy vault.enc only as an explicit import source; after migration, verify the current profile before deleting any old backup.

Agent grants and Request Center

An agent can request one mediated operation, but cannot approve its own grant or raw-reveal a Vault value.

1. Review the actor, resource, operation, destination, and expiration.
2. Approve once, deny, or revoke from the Request Center.
3. Verify that the resulting tool receipt is redacted and scoped to the approved operation.

Run a command with Vault resources

An agent can queue one exact absolute executable with selected Vault resources injected as child-process environment variables, but only a trusted ShellX operator can run it.

1. The agent discovers vault_agent_request through a targeted Host MCP tool search, then chooses agent-visible resources, an absolute program on the ShellX desktop host, exact arguments, an optional absolute working directory, and safe environment names.
2. In the Request Center, review the actor, purpose, complete program, arguments, working directory, bindings, and expiry; Run and Deny require a real trusted user action.
3. On approval, ShellX rechecks the digest and current resource policy, clears the child environment, injects only the approved values, bounds runtime and output, and redacts exact secret values from the result.

BoundaryThe command runs on the machine hosting the ShellX desktop app, not automatically inside the active WSL or SSH destination. Inline shell/interpreter evaluation, user-only resources, legacy pass-store refs, and loader-altering environment variables are refused. Review the complete request in ShellX, and verify redacted output and cleanup before treating the operation as complete.

Standalone Vault compatibility

The integrated client shares the current broker profile rules and compatibility resource schema with standalone ShellX Vault.

1. Close or lock one client before profile migration or recovery maintenance.
2. Use either owner UI for digest-bound executable requests, but approve only after checking that the displayed host path and environment bindings match the intended machine.
3. Do not run two incompatible versions against the same profile during a migration.

BoundaryBroker/profile parity includes the owner-approved executable-request flow. Compatibility does not make concurrent profile migration safe; use one current client as the migration owner and retain recovery material until the result is verified.

Build Mode

The /build command runs a long-horizon Grok workflow with an approved scratchboard, checkpoints, review, and completion gates.

1. Start /build with one concrete objective and review the scratchboard.
2. Use /pause, /resume, or /stop without discarding the current evidence.
3. Accept completion only after code, review, verification, and checkpoint receipts satisfy the plan.

Work Preview and Preview Doctor

Run static sites and supported web apps on loopback, inspect logs and screenshots, and send failures back to the active agent.

1. Start Preview from the selected project and inspect the bound URL.
2. Run Preview Doctor for HTTP, process-log, browser-error, and screenshot evidence.
3. Exercise important in-app controls; a first-page screenshot alone is not a complete UI test.

Trace and activity

Current Trace surfaces session file/search/write/delete activity, tools, commands, and generated-media references when providers expose them.

1. Use Trace to understand what changed and which provider/tool produced it.
2. Correlate activity with Git diffs, task state, and verification receipts.
3. Treat missing provider telemetry as unknown, not proof that no action occurred.

Flight Recorder status

Bounded Flight Recorder export and evaluation route through the Browser Evidence panel, compact Browser gateway, and CLI. Attempts retain monotonic source sequence, explicit sanitizer/selection truncation and task-owned retention gaps, completeness, first-evidence/action/network timing, operation coverage, and task-local handoff lineage; HTTP path/query/fragment values are removed, while unknown duration and parent/child lineage stay visibly partial. The Evidence panel can record the current task directly and marks gapped attempts instead of presenting every export as complete.

1. Use current Browser receipts, Trace, and Debug API evidence for production decisions.
2. In ShellX Browser, select a current task, open Evidence, and choose Record attempt. ShellX writes the bounded redacted artifact, validates its identity response, refreshes the receipt list, and reports whether evidence gaps remain.
3. The authenticated development export is task-owner/session bound, keeps only bounded sanitized receipts and events, and returns the artifact byte count and SHA-256.
4. Start a fresh caller-owned Browser task for every baseline or candidate attempt, then use browser_act action=flightRecorderExport; one task cannot populate multiple comparison cohorts.
5. Use browser_act action=evaluationWrite with a fixed evaluatedAtMs and exact attempt identities; the artifact suite/group must match, task identities must be distinct, and missing or incomplete evidence and unsafe candidates fail closed. Treat submitted duration, step, and safety fields as evaluator declarations bound to verified attempt artifacts, not independently observed Browser facts.
6. Use browser_read action=evidence for caller-scoped recent receipts, or the flight-recorder-export and workflow-evaluate CLI fallbacks, then review the same bounded identities in the Browser Evidence panel.

ShellXagent and Debug API

The installed app exposes authenticated loopback-only endpoints for sessions, prompts, screenshots, diagnostics, Browser, Vault, previews, and settings.

1. Use ShellX-owned clients or a private process-local credential integration; never hard-code or print bearer values.
2. Use health and bounded summary endpoints before broad state capture.
3. Keep tokens, raw Browser state, and Vault values out of logs and project folders.

Data and security boundaries

ShellX stores sessions and configuration under the active profile, binds services to loopback, and keeps Vault values encrypted and operator mediated.

1. Back up important project files and Vault recovery materials independently.
2. Review connection presets, provider permissions, Browser profiles, and pending Vault grants after environment changes.
3. Do not publish private evidence, tokens, hostnames, or machine paths with the public repository.

Connection failures

Separate network reachability, SSH shell compatibility, CLI installation, authentication, cwd, and host-tool health.

1. Run Test Connection and inspect the exact platform or authentication error.
2. Scan CLIs in the same Local, WSL, or SSH target used by the tab.
3. For a Windows PC, distinguish native port 22 from the WSL sshd port before changing provider settings.

Browser or Vault failures

Check task ownership, tab/profile identity, locks, pending dialogs, grant state, Vault lock state, and final receipts in that order.

1. Use a bounded Browser state summary and confirm the intended task/tab.
2. Resolve operator prompts or unlock Vault rather than retrying the same blocked action.
3. Clean up only the task, profile, process, or test fixture owned by the current run.