MemoMind Terminal

MemoMind Terminal is a local connector that bridges Codex and Claude Code sessions to the MemoMind App. Pair by scanning a QR code, then browse sessions, start tasks, receive live output, and respond to approvals or follow-up questions.

Connections are intended only for trusted local networks or Tailscale. This is not a hosted public service and does not relay pairing traffic through Gateway, MQTT, or the ChatGPT/Claude web apps. --expose can create a temporary public tunnel when required.

Features

• Supports Codex and Claude Code
• Prints a WebSocket address, a per-launch pairing token by default, and a pairing QR code at startup
• Lists recent sessions globally or for a selected project directory
• Streams text, tool activity, and results to the MemoMind App
• Supports history, reconnect replay, tool approvals, and user questions
• Advertises an application heartbeat so the App can detect silent network loss
• Supports Tailscale for private use beyond the same physical LAN

Supported Environments and Prerequisites

| Item | Requirement | | --- | --- | | Operating system | Designed for macOS, Linux, and Windows; see the WSL note below | | Node.js | Version 20.10 or later (node --version) | | Codex provider | An installed and authenticated codex CLI (codex --version) | | Claude provider | An installed and authenticated Claude Code CLI (claude --version) | | Network | Your phone and computer are on the same trusted LAN, or in the same Tailscale tailnet | | Glasses terminal mode | Your phone is paired with the glasses over Bluetooth |

--expose pinggy requires a local ssh client. --expose ngrok requires an installed and authenticated ngrok CLI. --expose bore requires the bore CLI.

Install

Install globally and verify the installation:

npm install -g @memomind/memomind-terminal
memomind-terminal --version

Update to the latest version:

npm install -g @memomind/memomind-terminal@latest

Quick Start

1. Start the connector on your computer:

   memomind-terminal --provider codex --cwd /path/to/project

   To use Claude Code instead:

   memomind-terminal --provider claude --cwd /path/to/project

2. The terminal prints a network address, complete pairing token, and QR code. If the selected address is not on the same network as your phone, restart with --interface to select the correct network adapter.

3. Scan the QR code in the MemoMind App and select a session.

4. The app can request history first, then the user explicitly starts a task. Pairing alone never creates a session or consumes provider usage.

Without --cwd, Codex and Claude expose recent sessions from all directories. With --cwd, both providers use that directory as the default session filter. The app can override it with cwd when listing sessions or starting the first task. --cwd must point to an existing directory.

Command-Line Options

memomind-terminal [command] [options]

| Option | Description | Default | | --- | --- | --- | | --provider codex\|claude | Coding assistant to connect | codex | | --port, -p | Local WebSocket port (1–65535) | 3680 | | --token, -t | Pairing token; a random token is generated when omitted | Random token | | --name, -n | Connector name displayed on the pairing screen | — | | --cwd, -d | Default directory for session filtering and new sessions | All recent sessions | | --tailscale | Bind to and advertise the IPv4 address from tailscale ip -4 | Off | | --interface, -i, --if | Bind to and advertise the first IPv4 address of an interface | — | | --expose pinggy\|ngrok\|bore | Create a temporary public tunnel; the server listens only on loopback | Off | | --verbose | Print safe diagnostic metadata to the console | Off | | --log-file [PATH] | Write privacy-filtered diagnostic metadata as JSONL; an omitted path generates a file in the current directory | No file | | --help | Show help | — | | --version, -v | Show the version | — |

Commands:

• memomind-terminal start: Start the connector; the same as omitting a command.
• memomind-terminal complete <bash|zsh|fish|powershell>: Print a shell completion script.
• memomind-terminal codex [args...]: Connect the Codex CLI to the connector's Codex App Server.

Examples:

# Expose Codex sessions for the current project
memomind-terminal --provider codex --cwd "$PWD"

# Expose Claude Code sessions for the current project
memomind-terminal --provider claude --cwd "$PWD"

# Pair through Tailscale
memomind-terminal --provider codex --tailscale

# Use a specific network interface (often en0 on macOS)
memomind-terminal --provider codex --interface en0

# Create temporary tunnels
memomind-terminal --provider codex --expose pinggy
memomind-terminal --provider codex --expose ngrok
memomind-terminal --provider codex --expose bore

# Set a connector name, choose a port, and write diagnostics
memomind-terminal --provider codex --name "My Computer"
memomind-terminal --provider codex --port 4680
memomind-terminal --provider codex --verbose --log-file

Without --interface, the connector prefers the IPv4 address of the default-route interface and falls back to the first non-loopback IPv4 address. In multi-adapter or VPN environments, use --interface to select the adapter on the same network as your phone. Inside WSL, the connector can see only WSL's eth0 and cannot automatically discover the Windows Wi-Fi address. Run it natively on Windows or use --expose instead.

--expose cannot be combined with --tailscale or --interface. Pinggy and ngrok produce a temporary wss:// pairing endpoint; ngrok requires ngrok config add-authtoken <token> first. Bore creates a raw TCP tunnel and produces ws://host:port; use BORE_SERVER=host:port for a self-hosted Bore server. Bore does not encrypt traffic, so prefer a trusted LAN, Tailscale, Pinggy, or ngrok.

QR Rendering

On interactive Windows terminals and graphical Linux sessions (DISPLAY or WAYLAND_DISPLAY), the Connector opens a black-and-white pairing QR code in the default browser. The page is served only from a random 127.0.0.1 URL, does not use an external QR service, and remains available until the Connector exits. If the browser or local page is unavailable, the Connector also prints a terminal QR fallback; when the page was created successfully, its local URL remains available for manual opening. macOS, headless Linux, and redirected output keep the existing compact terminal QR code.

Open the Codex CLI Through the Connector

When the connector is running with --provider codex, connect to its local Codex App Server with:

memomind-terminal codex

You can append normal Codex arguments. If you do not pass -C or --cwd, the command uses the current working directory.

Troubleshooting

| Problem | What to do | | --- | --- | | The phone cannot reach the connector | Confirm that the phone and computer are on the same trusted network. Use --tailscale for a tailnet, or --interface <name> on multi-adapter systems. | | The displayed WSL address is unreachable | Run the connector natively on Windows or use --expose for a temporary tunnel. | | The port is already in use | Start with --port <another-port>, then scan the new QR code. | | codex command not found | Install and authenticate the CLI, then run codex --version in the same terminal. | | Claude Code is not authenticated | Run claude in the same terminal and complete authentication, then retry with --provider claude. | | The token changes after every restart | This is the default security behavior. Use --token <fixed-value> only in a controlled pairing workflow. | | Pinggy, ngrok, or Bore cannot create a tunnel | Confirm the required CLI is installed; ngrok also requires an authtoken. Prefer a trusted LAN or Tailscale whenever possible. |

If the issue persists, collect diagnostics with --log-file and email the generated JSONL file to [email protected]. Add --verbose only when console diagnostics are also useful. The two options are independent. --log-file diagnostics.jsonl accepts a relative or absolute path; omitting the path generates a name in the current directory.

Each JSONL record includes a schema version, a random per-run ID, a monotonically increasing log index, wall-clock time, and process uptime. Connection IDs correlate authorization, inbound messages, local outbound write attempts, and disconnects within one run. Session, turn, request, message, tool, and interaction identifiers are replaced by process-local HMAC references, so related records can be correlated without storing the original identifiers. Replay records include the requested and retained sequence boundaries, replay count, detected cache gaps, and whether a snapshot resync was required.

An outbound record means that the Connector attempted a local WebSocket write in that order. It does not prove that the App received, processed, or displayed the message; the protocol has not been changed and no acknowledgement was added.

Security

• The default LAN endpoint uses plain ws:// and must only be used on a trusted personal LAN or tailnet. Public access should use a temporary encrypted Pinggy or ngrok tunnel; Bore remains plain ws://.
• Do not expose the port directly to the public internet or include a token in screenshots, logs, or support tickets.
• The Connector binds to the selected IPv4 address. --tailscale binds to the Tailscale IPv4 address, --interface binds to the selected interface IPv4 address, and --expose binds only to loopback before creating the tunnel.
• A new token is generated on every startup by default. A fixed --token can be retained in shell history or exposed to processes under the same user account; use one only in a controlled pairing process.
• A QR code and complete token are remote-control credentials. Do not share or upload them.
• Tool details can include commands, working directories, file paths, diffs, tool parameters, and output, which may contain business data or credentials.
• Pending approvals remain fail-closed while the app is disconnected and automatically decline when their approval timeout expires.

The diagnostic log contains only allowlisted metadata such as event type, provider, sequence boundaries, byte counts, state, and process-local correlation references. It never contains original session/turn/request identifiers, pairing tokens, QR codes or deep links, prompts, response text, tool parameters or output, credentials, URLs, or full paths. Do not start the connector with > output.log 2>&1, because that writes the complete token, deep link, and QR code to disk.

Local Data in Claude Mode

When started with --provider claude, the connector keeps a local session cache at ~/.memomind-pc-connector/claude-sessions.json. Claude Code's native session remains the source of truth; the cache retains Connector metadata and up to 300 recent user or assistant messages per session across Connector restarts. Message text is stored without character truncation.

On macOS and Linux, the connector creates the cache directory with owner-only permissions and writes the cache file with owner read/write permissions. To remove this connector cache, stop all running Connector processes and delete the ~/.memomind-pc-connector/ directory. This does not delete Claude Code's own session history.