Even Terminal

even-terminal is designed to be used with the Even App.

Building glasses-native apps instead of mirroring your laptop? See @evenrealities/even_hub_sdk.

Supports macOS, Linux, Windows.

Requirements

• Node.js 18+ — check with node --version. Install from nodejs.org, or brew install node (macOS), or your distro's package manager (Linux).
• An Even Realities G2 + R1 ring, paired through the Even app (iOS/Android).
• Optional but recommended: a Tailscale account signed in on both your laptop and phone — gives you a stable private network without needing the public-tunnel providers below.

Install

npm install -g @evenrealities/even-terminal

Verify the install:

even-terminal --version

Update to the latest release:

npm install -g @evenrealities/even-terminal@latest

Quick Start

even-terminal

On the first run, a four-step setup wizard covers the default agent, project directory, and phone connection, then generates a persistent pairing token. It stores the result in ~/.even-terminal/config.json, then starts the foreground server. Later runs reuse that configuration.

Use the arrow keys, k/j, or w/s to move through wizard choices, then press Enter to confirm. Project-directory input accepts ~ for the home directory and prints the resolved absolute path after confirmation.

The configured project directory becomes the working directory for new sessions when the client omits cwd. Session listing remains unfiltered unless the client explicitly supplies a cwd filter.

The default server port is 3456.

Useful startup options:

even-terminal --cwd /path/to/project
even-terminal --port 8080
even-terminal --token mytoken123
even-terminal --name my-laptop
even-terminal --provider codex
even-terminal --lan
even-terminal --allow-cors
even-terminal --claude-use-system-cli
even-terminal --claude-allowed-tools Read,Glob,Grep,ToolSearch
even-terminal --config ~/.even-terminal/work.json
even-terminal --expose pinggy
even-terminal --expose bore
even-terminal --expose ngrok

How it works

even-terminal runs a local HTTP server on :3456 (configurable through setup, even-terminal config, or --port), spawns your AI agent (Claude Code or Codex) as a child process, captures its streaming output, renders it onto the G2's 576×288 canvas, and translates R1 ring gestures back into keyboard events for the agent.

The Even app connects to your laptop over your chosen transport. By default the server listens on all interfaces and advertises your detected LAN address (same Wi-Fi). Pass --tailscale to bind external access to your Tailscale IPv4 address (stable across networks, end-to-end WireGuard), or -i <interface> to bind external access to a specific network interface. Both modes retain a loopback listener for the local Claude/Codex CLI integrations. Use --expose pinggy / --expose bore / --expose ngrok to open a temporary public tunnel.

                       ┌──────────────────┐
                       │   your laptop    │
   [ claude / codex ] ─│   even-terminal  │
                       │   :3456          │
                       └────────┬─────────┘
                                │
                ┌───────────────┴───────────────┐
                │   transport (pick one)        │
                │   default: LAN (same Wi-Fi)   │
                │   --tailscale                 │
                │   --expose pinggy             │
                │   --expose bore               │
                │   --expose ngrok              │
                └───────────────┬───────────────┘
                                │
                       ┌────────┴─────────┐
                       │     Even app     │
                       └──┬────────────┬──┘
                       (display)     (input)
                       BLE ↓          ↑ BLE
                     ┌────┴────┐  ┌────┴────┐
                     │   G2    │  │   R1    │
                     │ 576×288 │  │  ring   │
                     └─────────┘  └─────────┘

The agent runs locally on your laptop, using either a bundled or system executable as described below. even-terminal is a renderer + input bridge.

CLI

even-terminal [command] [options]

Commands:
  even-terminal start
  even-terminal config [key] [value]
  even-terminal complete <shell>

Local network options:
  --lan
  --tailscale
  -i, --interface, --if <name>

Quick public expose options:
  --expose <provider>   Quick public expose provider (`pinggy`, `bore`, `ngrok`)

Options:
  -p, --port <n>
  -t, --token <str>
  -n, --name <str>
  -d, --cwd <path>
  --provider <name>   claude, claude-sync, codex (default: claude)
  --config <path>     Use another persistent config file
  --allow-cors        Allow cross-origin browser requests
  --use-original-claude  Use the original Claude SDK provider without terminal/app synchronization
  --claude-use-system-cli  Use the system Claude CLI for SDK sessions
  --claude-allowed-tools <csv|none>  Replace Claude SDK auto-approved tools
  --log-file <path>  Write logs to a file
  --log-level <debug|info>  Control log-file detail only (default: debug)
  --verbose  Print raw diagnostics to stdout only; does not change log files
  -h, --help
  -v, --version

Examples:
  even-terminal
  even-terminal -p 8080
  even-terminal -t mytoken123
  even-terminal --expose pinggy
  even-terminal --expose ngrok

Setup and persistent configuration

The first-run wizard writes a versioned configuration file with permissions 0600 on macOS and Linux. The pairing token remains stable across restarts. The wizard stores claude or codex as the default provider. Claude uses Claude Sync by default; pass --use-original-claude to opt out.

Run the interactive config menu at any time:

even-terminal config
even-terminal config --reset

Scripts can update one parsed value without opening the menu:

even-terminal config provider codex
even-terminal config cwd /path/to/project
even-terminal config token 'new-token'
even-terminal config network tailscale
even-terminal config network interface:en0
even-terminal config network expose:pinggy
even-terminal config port 4567
even-terminal config claudeUseSystemCli on
even-terminal config claudeAllowedTools Read,Glob,Grep,ToolSearch
even-terminal config claudeAllowedTools default

config --reset reruns the wizard while retaining the existing pairing token. To rotate it, run even-terminal config token '<new-token>'. The next server start prints a new QR code; use it to pair the client again.

Use --config <path> for another profile. Relative paths resolve from the current directory; ~/... paths resolve from the home directory.

Startup values follow this precedence:

CLI flag > environment variable > config file > built-in default

Flags and environment variables affect the current process without rewriting the selected config file. Invalid JSON, unknown fields, unsupported providers, and malformed network values fail before the server starts.

Cross-origin browser requests are disabled by default. Native Flutter clients and same-origin web clients are unaffected; pass --allow-cors only when a different browser origin must call the server.

The setup wizard does not install or start a background service. Start the foreground server yourself with even-terminal; stop it with Ctrl+C. even-terminal claude and even-terminal codex connect to an already-running server and report an error when none is available.

Logging

Log files use debug detail by default, preserving raw SDK, app-server, SSE, permission, and question payloads. Opt into a smaller file with:

even-terminal --log-level info

info retains server and provider lifecycle events, HTTP and prompt summaries, session state, usage, retries, warnings, and errors. --verbose is independent: it controls raw diagnostics on stdout only. For example, this keeps verbose stdout while writing an info log file:

even-terminal --verbose --log-level info

Quick public expose helpers are intended for simple temporary sharing, not long-term use. For stable setups, prefer a proper network path such as Tailscale or a production tunnel configuration.

Current quick expose providers:

pinggy

No install required — uses your system's SSH client. Just pass --expose pinggy.

Behind the scenes:

ssh -p 443 -R0:localhost:<port> a.pinggy.io

Pinggy is a hosted SSH-tunnel service; the public URL appears in your terminal once the tunnel is up.

bore

Self-hostable, written in Rust. GitHub: ekzhang/bore.

Install:

• macOS: brew install bore-cli (or) cargo install bore-cli
• Linux: cargo install bore-cli (or) download a prebuilt binary from releases and put bore on your $PATH
• Windows: download bore-vX.Y.Z-x86_64-pc-windows-msvc.zip from releases, extract bore.exe, add its folder to your PATH

Verify with bore --version. Then --expose bore runs:

bore local <port> --to bore.pub

ngrok

Hosted tunnel service, free tier available. Site: ngrok.com.

Install:

• macOS: brew install ngrok/ngrok/ngrok
• Linux: see the apt/yum repos at ngrok.com/download — or download the tarball, extract, and put ngrok on your $PATH
• Windows: download the zip from ngrok.com/download, extract ngrok.exe, add its folder to your PATH

One-time setup — sign up at ngrok.com, copy your authtoken from the dashboard, then:

ngrok config add-authtoken <your-token>

Verify with ngrok --version. Then --expose ngrok runs:

ngrok http <port>

Shell completion (example usage):

even-terminal complete zsh
even-terminal complete bash
even-terminal complete fish
even-terminal complete powershell

Each form prints the completion script for that shell.

Flow

1. Start the foreground server with even-terminal. On first run, finish the setup wizard; the server then prints a connection URL, the persistent token, and a QR code.
2. Open the Even app on your phone and scan the QR code — or paste the URL and token manually if scanning isn't convenient.
3. Your G2 glasses and R1 ring connect via BLE through the Even app. The agent's output streams onto the glasses, and ring gestures route back to the agent as keyboard events.

Providers

Even Terminal can run all supported providers concurrently. --provider <name> selects the default provider; clients may still choose another provider for each session.

Install and authenticate the corresponding system CLI before using even-terminal claude or even-terminal codex.

Claude

Sessions started from the Even app normally use the claude provider through Claude Agent SDK.

To use the familiar Claude terminal interface while allowing the Even app to join the same session, run:

even-terminal claude
even-terminal claude --resume <session-id>

Normal Claude arguments pass through to the system claude CLI. The command automatically discovers a running Even Terminal server and prompts for one when multiple instances are available.

Experimental terminal and app synchronization

The claude-sync provider remains experimental. It relies on a compatibility layer around the Claude CLI rather than a native shared-session protocol. Expect occasional edge cases around CLI input, session resume, output timing, permissions, and compatibility with future Claude CLI releases.

Given the integration surface Anthropic has chosen to expose, this remains about the best shared-session experience Even Terminal can provide.

Claude Sync runs under the claude provider name by default. Start the server:

even-terminal

Then open Claude in another terminal:

even-terminal claude

To use the original Claude SDK provider without terminal/app synchronization, start the server with even-terminal --use-original-claude. The explicit claude-sync provider remains available.

Selecting a server port

The Claude wrapper normally discovers the server automatically. To connect it to a specific Even Terminal port:

even-terminal --port 4567
env EVEN_TERMINAL_PORT=4567 even-terminal claude
env EVEN_TERMINAL_PORT=4567 even-terminal claude --resume <session-id>

PowerShell:

$env:EVEN_TERMINAL_PORT = "4567"
even-terminal claude --resume <session-id>

Claude executable compatibility

Agent SDK sessions use the SDK-bundled Claude executable by default. If that version behaves differently from the system installation, start Even Terminal with:

even-terminal --claude-use-system-cli

This compatibility option may help with version-specific problems, though it cannot guarantee identical behavior. even-terminal claude always launches the system claude CLI.

Claude automatic tool approval

Even Terminal's default list appears in even-terminal --help:

Read, Glob, Grep, ToolSearch, WebSearch, WebFetch, TaskOutput, ExitPlanMode,
ListMcpResources, ReadMcpResource, TodoWrite, TaskUpdate

WebSearch and WebFetch can access the network without an app confirmation. To replace the list, pass comma-separated, case-sensitive tool names; use none to clear the entries supplied by Even Terminal:

even-terminal --claude-allowed-tools Read,Glob,Grep,ToolSearch
even-terminal --claude-allowed-tools none

Empty names and none mixed with other names are rejected. Unknown names are accepted because Claude can load custom tools from user/project MCP settings and plugins; fully qualified MCP names normally look like mcp__<server>__<tool>. Native allow rules in Claude user or project settings may approve additional tools independently of this option.

Codex

Even Terminal integrates with Codex through its native app-server protocol. The app-server runs locally and starts lazily when a Codex session first needs it.

even-terminal codex

This command discovers a running Even Terminal instance and launches the system Codex CLI with codex --remote, connecting it to the same app-server used by the Even app. Normal Codex arguments pass through to the CLI.

When the terminal and app use the same Codex thread, prompts entered from either side and streamed responses appear on both sides in real time. Codex provides an actual multi-client shared-session protocol, giving Even Terminal a direct and considerably more reliable synchronization path. Claude currently offers no equivalent interface, hence the experimental compatibility layer described above.

In practice, Codex synchronization provides the stronger experience by design: native real-time events, direct bidirectional input, and fewer version-sensitive edge cases.

Selecting the Codex app-server port

The Codex app-server uses port 8765 by default. To use another port, start the server and Codex CLI with CODEX_APP_SERVER_PORT:

env CODEX_APP_SERVER_PORT=8766 even-terminal
env CODEX_APP_SERVER_PORT=8766 even-terminal codex

PowerShell:

$env:CODEX_APP_SERVER_PORT = "8766"
even-terminal
even-terminal codex

This port belongs to the local Codex app-server. The main Even Terminal HTTP port remains controlled by --port.

Common problems

For anything else: even-terminal --verbose --log-file ./debug.log, reproduce, attach the log to an email to [email protected] .

Changelog

0.10.3

• make Claude Sync the default implementation of claude
• replace --claude-sync-as-claude with --use-original-claude to opt out

0.10.2

• disable Pinggy's rich terminal UI to prevent interference with startup text and QR codes
• select a non-loopback private IPv4 address for LAN mode without filtering interface names
• bind LAN access to the selected address while preserving IPv4 loopback; use loopback alone for tunnel-only mode or when no LAN address qualifies
• reject combinations of --lan, --tailscale, and --expose before startup without changing saved configuration

0.10.1

• preserve loopback access for local Claude/Codex integrations when binding to a restricted external address
• retain the original working directory when resuming Claude sessions after a server restart
• make explicit network flags clear conflicting inherited network settings

0.10.0

• Setup and persistent configuration
  • add a keyboard-driven first-run wizard for the default agent, project directory, network, and pairing token
  • store versioned profiles and stable pairing tokens with owner-only file permissions on macOS and Linux
  • add interactive and non-interactive config commands, alternate profiles through --config, and explicit CLI > environment > config > default precedence
  • persist network selection, including the new --lan mode
  • use the configured project directory for new sessions while resumed sessions retain their original working directory
• Claude and Claude Sync
  • use the Claude Agent SDK as the shared backend for claude and headless claude-sync sessions, while preserving wrapped interactive CLI sessions
  • upgrade Claude Agent SDK to 0.3.231 for compatibility with newer Claude CLI session transcripts
  • mark Claude Sync as experimental and add --claude-sync-as-claude for clients that cannot select it directly
  • add --claude-use-system-cli as an SDK/CLI compatibility fallback
  • expose and configure the default automatically approved tool list, while accepting custom and MCP tool names
• CLI, security, and diagnostics
  • accept documented dashed option names without generating camelCase aliases
  • synchronize shell completion for wrapper commands, configuration keys and values, aliases, and newly added options
  • document wrapper discovery and explicit Claude/Codex port selection
  • separate stdout verbosity from log-file detail with --verbose and --log-level
  • bind Tailscale/interface modes to the selected address, require explicit --allow-cors for permissive CORS, and redact query-string token values while preserving other request parameters

0.9.0

• Internal release; not published publicly.

0.8.1

• optimize codex session history performance for large session (windows)
• add --expose ngrok support (need to sign in elsewhere first)

0.8.0

• codex now only starts a background process when necessary

0.7.9

• add debug timing for codex history api
• fix middle deny behavior in multiple permission requests

0.7.8

• add update check api

0.7.7

• improve codex support with even-terminal codex wrapper which can sync messages between codex cli and glasses
• internal refactoring

License

MIT