wingman
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Wingman
Your coding agent's wingman — a TypeScript MCP bridge + pair CLI so Grok Bot, Cursor, Muse Code (and other MCP hosts) can talk to live Codex and Claude Code sessions on your machine while you still see the session.
Dual-provider: Codex (app-server) + Claude Code (Agent SDK).
See ROADMAP.md for positioning, backlog, and non-goals.
Why Wingman?
Cloud assistants are great copilots — until they need to touch the session you're already in. Wingman sits on your machine, pairs with a one-command CLI, and exposes a small MCP surface so a remote host can list threads, read transcripts, send messages, and interrupt turns — without hijacking your TTY or pretending to be the agent UI.
Think of it as a radio link between the bot in the cloud and the agent on your desk. You're still flying; Wingman just rides shotgun.
Related MCP server: opencode-codex-mcp
Quickstart
Clone and run (recommended)
git clone https://github.com/juangurdian/wingman.git
cd wingman
npm install
npm run pairSet CODEX_MOCK=1 or CLAUDE_MOCK=1 for mock mode (no real agent required).
npm status: the
wingman-mcppackage is not published to npm yet, sonpx wingman-mcpandnpm install -g wingman-mcpwill not work today. Use the clone-and-run steps above. This section will switch back tonpxonce the package is published.
After pairing
Pair —
wingman-pairgenerates a bearer token, writes~/.wingman/config.json, and starts MCP on127.0.0.1:3847/mcp.Tunnel — remote hosts cannot reach localhost. Pick a tunnel option (ranked by durability):
# Option 1: Tailscale Serve (stable, loopback to your network) tailscale serve --bg 3847 # Option 2: Tailscale Funnel (stable, public URL) tailscale funnel 3847 # Option 3: Cloudflare named tunnel (stable, custom domain) # Run 'wingman-tunnel' for one-time setup instructions cloudflared tunnel run wingman # Option 4: Cloudflare quick tunnel (ephemeral, for demos) cloudflared tunnel --url http://127.0.0.1:3847For detailed setup help, run
wingman-tunnel(ornpm run tunnel).Add MCP server (Grok Bot / Cursor
AddMcpServer):Field
Value
name
wingmanurl
https://YOUR-TUNNEL-HOST/mcpAuthorization
Bearer <token printed by pair>
Then ask the host to call list_sessions → read_transcript / send_message / interrupt.
Host-specific guides
Different MCP hosts have different configuration methods. See the detailed guides:
Host | Support | Guide |
Grok Bot | ✅ Full | |
Cursor IDE | ✅ Full | |
Muse Code | ✅ Full | |
Claude Desktop | ⚠️ Limited | |
Other clients | Varies |
Note: Wingman is a remote HTTP MCP server. Hosts that support HTTP + bearer auth work natively. Stdio-only hosts (like Claude Desktop) require a bridge — see the Claude Desktop guide for workarounds.
Real provider modes
Codex — Requires codex on PATH. Wingman speaks Codex app-server JSON-RPC (codex app-server over stdio).
npm run pair # unset CODEX_MOCKClaude Code — Uses the @anthropic-ai/claude-agent-sdk. Sessions are created and resumed through the SDK.
npm run pair # unset CLAUDE_MOCKDocs: Codex App Server · Claude Agent SDK
Can / Can't
Can
Pair in mock mode with no agent install (
CODEX_MOCK=1orCLAUDE_MOCK=1)Bridge Grok Bot ↔ local Codex threads via app-server once tunneled
Bridge Grok Bot ↔ local Claude Code sessions via Agent SDK once tunneled
Discover existing Claude sessions via SDK's
listSessions()(sessions you created viaclaudeCLI or Claude Code IDE)Resume discovered sessions by ID — the SDK reads session state from
~/.claude/projects/Send messages to sessions asynchronously (returns
acceptedquickly; turn runs in background)Check session status (idle vs running) via
get_sessionorlist_sessionsBearer-protect the MCP HTTP endpoint
Create / list / read / message / interrupt sessions (real or mock) for both providers
Keep you in the loop — the session stays visible on your machine
Can't (scope / v1 limits)
Reach the bridge from a remote host without a tunnel (binds loopback only)
Type into an open TTY — SDK resume ≠ injecting keystrokes into a Claude/Codex terminal you're watching; Wingman calls SDK APIs that operate on session state files, not terminal processes
Hijack arbitrary Claude / Codex TTYs you already have open elsewhere — Wingman manages sessions via SDK, not by attaching to interactive shells
Interrupt a discovered session reliably unless Wingman started the current turn (no active query handle)
Auto-approve sandbox prompts (approvals still belong to the local agent client)
Use legacy
codex mcp-server(removed / not used here)
Architecture
flowchart LR
subgraph cloud [Cloud]
Grok[Grok Bot]
Cursor[Cursor IDE]
Muse[Muse Code]
end
subgraph user [User machine]
Tunnel[cloudflared / Tailscale]
Bridge[Wingman MCP\n127.0.0.1:PORT]
Codex[Codex app-server\nJSON-RPC stdio]
Claude[Claude Agent SDK\ndiscovery + resume]
end
Grok -->|HTTPS + Bearer| Tunnel
Cursor -->|HTTPS + Bearer| Tunnel
Muse -->|HTTPS + Bearer| Tunnel
Tunnel --> Bridge
Bridge --> Codex
Bridge --> ClaudeMCP tools
Tool | Args | Notes |
|
| Lists sessions. |
|
| Get detailed session info including status ( |
|
| Recent messages (newest at end) |
|
| Codex: |
|
| Codex: |
|
| Codex: |
|
| Wait for a Codex or Claude turn to complete, fail, or time out. Returns early while a permission prompt is waiting. |
|
| Add guidance to an in-flight turn. Codex: |
|
| List pending Codex or Claude approval requests. |
|
| Accept, accept for the session, decline, or cancel a Codex or Claude approval. |
|
| Set session name/tags for easier discovery (Wingman-owned sessions) |
|
| Export transcript as |
| (none) | This process is up: pid, uptime, and how to read a later failure. See Operations. |
| (none) | Interactive Claude sessions from the inbox registry and |
|
| Send text to a live interactive session by id, name, or pid. Past sessions are refused. |
|
|
|
|
| Headless |
|
| Long Claude run. Prompt is an SDK string, not a PowerShell command. Returns a run id. |
|
| Poll a headless run: status, exit code, output tail, RSS |
|
| Interrupt a session or kill a headless run. Reports memory use. |
create_session behavior
For Claude sessions, create_session returns immediately:
Without prompt: Returns
{ sessionId, status: "created", resumeMode: "new", maxTurns, permissionMode }. The session is registered and no turn is running.With prompt: Returns
{ sessionId, status: "accepted", turnId, ... }and the initial prompt runs in the background, so the MCP HTTP call does not wait for the model.
Optional Claude fields: model, max_turns (default 50), permission_mode (default default), allowed_tools, disallowed_tools, approval_timeout_ms (default 120000). Omit model and Claude Code chooses its own default. Do not pass an old model id unless you mean that exact id.
For Codex sessions, create_session calls thread/start and returns { sessionId, status: "created" | "accepted", model? }.
Codex model override
By default, Wingman does not override the Codex model — it uses whatever is configured in ~/.codex/config.toml or Codex's built-in defaults. Override only when you intentionally need a different model for Wingman-created sessions:
Via environment variable:
export WINGMAN_CODEX_MODEL="your-preferred-model"
npm run pairVia create_session argument (per-session):
{ "provider": "codex", "model": "your-preferred-model", "prompt": "Hello" }Priority order: create_session.model > WINGMAN_CODEX_MODEL env > user's ~/.codex/config.toml > Codex defaults
Note: Some models may require API access rather than a ChatGPT subscription. If session creation fails due to model access, either ensure you have the required access level, or let Codex pick its default by not setting a model override. Run wingman-doctor to check for models that may require API access.
send_message behavior
For a live interactive Claude session (registry file plus a running pid), send_message delivers the text on that session's inbox socket or Windows named pipe and returns { status: "delivered_via_inbox", attachedToTerminal: true }. It does not start a headless resume. If the inbox rejects the message, Wingman falls back to the headless path below.
For other Claude sessions, send_message returns immediately with { status: "accepted", turnId, resumeMode, maxTurns, permissionMode, model?, modelSource, attachedToTerminal: false, note } while the SDK query runs in the background. Use wait_turn, get_session, or read_transcript to observe progress. This keeps the MCP HTTP call from waiting on the model.
If a Wingman turn is already active, send_message throws turn already active; use steer or interrupt and does not replace that turn. Approval timeout values, including WINGMAN_CLAUDE_APPROVAL_TIMEOUT_MS, are capped at 600000 ms so a huge timer cannot collapse to 1 ms.
Per-call fields override the WINGMAN_CLAUDE_* defaults below. max_turns defaults to 50 (not 1). permission_mode defaults to default, and Wingman sets permissionPrompts: "host" so tool prompts reach list_approvals instead of being auto-denied.
Model priority for a Claude turn:
send_message.modelorcreate_session.modelWINGMAN_CLAUDE_MODELThe model already stored for that session (resume)
Omit the flag and let Claude Code use its own default
Wingman never substitutes a built-in model id. Passing the session model on resume is what stops a headless query from falling through to the CLI default.
For Codex sessions, send_message blocks until turn/start returns (typically fast), then returns { status: "completed" | "inProgress" }. Claude-only fields are ignored.
Resume, fork, and open terminals
send_message on Claude resumes that session id with forkSession: false unless you pass fork_session: true.
| Meaning |
| Same session id. The headless query continues the session file. |
| A new session id is copied from the original. The original is left unchanged. |
|
|
attachedToTerminal is true only for inbox delivery. A headless Agent SDK query does not attach to an already-open interactive Claude Code terminal, so that turn will not appear there. That limit is in the CLI: Wingman can read and resume the session file, and it cannot type into a TUI that already holds the session unless the inbox socket is bound. --bare sessions do not bind an inbox. If that terminal has the transcript open, the CLI may still fork a new id even when fork_session is false. Check actualSessionId on get_session and wait_turn. To watch relayed turns, read them with read_transcript, or reopen the session id in Claude Code after the turn finishes.
list_claude_live_sessions and send_to_claude_session talk to that inbox directly. get_status still reports idle, working, awaiting_approval, or errored, and also includes live, processPid, and liveStatus when the session record has them. See Live session injection.
Codex can attach to a shared app-server socket (WINGMAN_CODEX_SOCKET=auto or a path) instead of spawning its own process. The WebSocket client disables permessage-deflate. If the socket is missing, Wingman spawns a private app-server and logs the reason. wingman-live-setup prints the daemon and TUI steps. See Codex shared server.
interrupt behavior
For Claude sessions, interrupt works when Wingman owns the active turn (you called send_message or create_session through Wingman for the current turn). It aborts the query, calls Query.interrupt() on the streaming headless process, and denies any permission prompt that is still open. Returns { status: "interrupted", turnId } on success, or { status: "no_active_turn" } if the session is idle.
Limitation: Interrupting a turn that was started outside Wingman (for example in the Claude CLI directly) does not work. Wingman has no query handle to abort. Use Ctrl+C in that terminal.
For Codex sessions, interrupt requires a known active turnId tracked from turn/started notifications.
Session tags/names
Sessions can have human-friendly names and tags for easier discovery and filtering:
create_session: Pass name and/or tags when creating a session:
create_session({ provider: "claude", cwd: "/project", name: "Auth Refactor", tags: ["refactor", "auth"] })set_session_meta: Update name/tags on existing Wingman-owned sessions:
set_session_meta({ provider: "claude", session_id: "sess_123", name: "Updated Name", tags: ["new", "tags"] })Sessions returned by list_sessions and get_session include name and tags fields. For discovered Claude sessions, the legacy tag field is also converted to tags.
Note: In real mode, set_session_meta only works for Wingman-owned sessions (sessions created via Wingman's create_session). Codex real mode does not support custom metadata.
wait_turn (Codex and Claude)
wait_turn provides long-poll waiting instead of busy-polling read_transcript. It works for both Codex and Claude sessions.
For Claude sessions, wait_turn polls until the turn completes, times out, or the session is idle. Real Claude cold starts can take 1-3+ minutes. Use wait_turn so the MCP client does not hit its HTTP timeout. If a tool prompt is waiting, wait_turn returns immediately with status: "inProgress" and a message that approvals are pending. Resolve them, then call wait_turn again.
Example Claude workflow:
1. create_session(prompt: "Build a web scraper") → { status: "accepted", turnId: "turn_1" }
2. wait_turn(timeout_ms: 180000) → { status: "completed", latestMessage: "I've created..." }For Codex sessions, wait_turn returns when the turn completes, fails, is interrupted, times out, or when approvals are pending.
Example response:
{ "sessionId": "thr_123", "turnId": "turn_456", "status": "completed", "latestMessage": "Done!" }steer
steer adds guidance to an in-flight turn without starting a new one.
Codex: Uses
turn/steer.Claude: Queues a user message on the active headless query (
priority: "now") so the CLI can fold it into the running turn. This only reaches a query Wingman started. It does not steer an interactive terminal. If no Wingman turn is active, the tool returns an error telling you tosend_message, or tointerruptand thensend_message.
list_approvals and resolve_approval
Both tools work for Codex and Claude.
Codex: JSON-RPC approval requests for sandbox commands, file changes, or network access.
Claude: The Agent SDK
canUseToolcallback parks each prompt until the supervisor resolves it.list_approvalsreturns the tool name, kind (command,fileChange, ornetwork), and a short summary. Decisions:accept: allow this call onceacceptForSession: allow this call and the same tool action for the rest of the Wingman sessiondecline: deny the toolcancel: deny the tool and interrupt the turn
If nobody resolves a Claude prompt before approval_timeout_ms (default 120000, or WINGMAN_CLAUDE_APPROVAL_TIMEOUT_MS), Wingman denies it. permission_mode: "dontAsk" still denies without a prompt, because that mode has no approval surface. bypassPermissions skips prompts and requires the SDK's explicit bypass flag, which Wingman sets only when you choose that mode.
Example approval flow:
1. send_message("update the lockfile") → { status: "accepted" }
2. wait_turn() → { status: "inProgress", latestMessage: "Waiting for 1 approval(s)" }
3. list_approvals() → { approvals: [{ id: "appr_1", kind: "command", toolName: "Bash", command: "git status" }] }
4. resolve_approval("appr_1", "accept") → { resolved: true }
5. wait_turn() → { status: "completed" }Note: In Codex mock mode (CODEX_MOCK=1), commands containing sudo or rm -rf trigger simulated approval requests. In Claude mock mode (CLAUDE_MOCK=1), a message shaped as [approval-request ToolName] args parks the turn on a prompt so you can test list_approvals without a real CLI.
Environment variables
General
Variable | Default | Description |
| (generated) | Bearer token for MCP auth |
|
| MCP server port |
|
| MCP server bind address |
|
| Default timeout for |
|
| Default poll interval for |
|
| Set to |
Codex
Variable | Default | Description |
| unset | Set to |
|
| Path to Codex CLI binary |
|
| Args passed to Codex binary |
|
| JSON-RPC timeout |
| unset | Override Codex model for Wingman sessions (optional; defaults to Codex config/defaults) |
Claude
Variable | Default | Description |
| unset | Set to |
|
| Set to |
| (all) | Directories to search, separated by the OS path delimiter ( |
|
| Timeout for Claude SDK send operations |
|
| Agent turns allowed in one Claude query (cap 500). Per-call |
|
|
|
| unset | Comma-separated Claude tools that skip the permission prompt |
| unset | Comma-separated Claude tools removed from the session |
| unset | Optional model override. Unset inherits the session model, then Claude Code's own default. Never set this to pin an old model by accident. |
|
| Deny a Claude permission prompt that is not resolved in time |
The Claude provider uses the bundled Agent SDK binary automatically. No separate claude CLI install is required unless you override pathToClaudeCodeExecutable in code.
Multi-Host
Variable | Default | Description |
| hostname | Machine identifier for multi-host setups |
| hostname | Human-friendly host name for display |
|
| Caller id used when a tool omits |
| unset | Project roots this process may touch, split on the OS path delimiter ( |
See docs/hosts/multi-host.md for running Wingman on multiple machines.
Session management
Wingman-managed sessions
Wingman tracks sessions it creates in a local registry (~/.wingman/claude-sessions.json for Claude). This ensures:
Isolation — Only sessions started through Wingman's
create_sessionare visible to MCP clients by defaultNo TTY hijack — We don't scan for or attach to Claude/Codex processes you started elsewhere
Resumable — Sessions can be resumed by ID across Wingman restarts
Claude session discovery
Wingman can also discover existing Claude Code sessions via the Agent SDK's listSessions(). This allows list_sessions to find sessions the user created via claude CLI or Claude Code IDE — not only sessions created through Wingman.
How discovery works:
list_sessionsmerges Wingman's registry with sessions discovered via SDKIf the same session ID exists in both, the Wingman registry entry takes precedence
read_transcript,send_message, andinterruptwork for discovered sessions by resuming viaquery({ options: { resume: sessionId, forkSession: false } })When you interact with a discovered session, it's auto-registered in Wingman's registry
What discovery is NOT: This is not TTY hijacking. Wingman does not attach to terminal processes, scrape windows, or take over interactive sessions. Discovery reads session files on disk via official SDK APIs. A headless resume is not visible in an already-open interactive terminal. See Resume, fork, and open terminals.
Set CLAUDE_DISCOVER=0 to disable discovery and only show Wingman-created sessions.
SessionSummary fields
Sessions returned by list_sessions include:
Field | Type | Description |
|
| Origin of the session |
|
| Human-friendly session name |
|
| User-set tags for categorization/filtering |
|
| Git branch at end of session (discovered) |
|
| Legacy single tag (discovered sessions only) |
Claude session storage
Claude sessions are stored by the Agent SDK in ~/.claude/projects/<project-key>/<session-id>.jsonl. Wingman's registry maps session IDs to their working directories so listSessions() and readTranscript() can locate them.
Scripts & CLI
From a checkout, run these through npm run (the bare commands below are what a global npm install will provide once the package is published):
Command | Purpose |
| Generate token, save config, start MCP, print pair instructions |
| Check environment: Node version, config, port, Claude SDK / Codex binary |
| Detect tunnel tools, print ranked setup commands, persist tunnel state. |
| Install a Windows scheduled task that restarts on crash and reuses the bearer token |
For local development:
Script | Purpose |
| Same as |
| Same as |
| Same as |
| Same as |
| Start MCP only (needs existing config/token) |
| Compile TypeScript → |
| Vitest unit tests (mocked providers) |
Config
~/.wingman/config.json (new installs). If you still have a legacy ~/.session-bridge/config.json, Wingman will read it as a fallback.
{
"token": "...",
"host": "127.0.0.1",
"port": 3847,
"mcpPath": "/mcp",
"createdAt": "...",
"mock": true
}Health Endpoint
Wingman exposes a /healthz endpoint for monitoring and tunnel health checks.
Default behavior: Requires bearer authentication (same token as /mcp).
Auth-free mode: Set WINGMAN_HEALTHZ_AUTH_FREE=1 to allow unauthenticated access to /healthz. This is useful for:
Cloudflare Tunnel health checks
Load balancer probes
Uptime monitors that can't send auth headers
# Enable auth-free healthz (document the security tradeoff)
WINGMAN_HEALTHZ_AUTH_FREE=1 npm run pairSecurity tradeoff: An auth-free /healthz reveals that Wingman is running but exposes no secrets, session data, or MCP functionality. The /mcp endpoint always requires bearer auth.
Example response while the process is alive:
{ "ok": true, "service": "wingman", "state": "server_up", "pid": 123, "uptimeMs": 1000 }/status returns the same body. If the call fails, the client has to classify the error itself. get_bridge_status repeats the rules, and wingman-tunnel diagnose can see them from the machine. Full table: docs/operations.md.
What the client sees | State |
HTTP 200 from |
|
HTTP 401 or 403 |
|
Cloudflare 1033 or HTTP 530 |
|
HTTP 502 or 504 |
|
|
|
Doctor / Health Check
Run npm run doctor (or wingman-pair --doctor) to verify your environment:
npm run doctorChecks:
Node.js version (20+ required)
Config file (
~/.wingman/config.json)Port availability (3847 by default)
Claude Agent SDK availability (unless
CLAUDE_MOCK=1)Codex binary on PATH (unless
CODEX_MOCK=1)
The doctor prints clear next steps if any check fails.
Agent skill
See skills/pair-coding-sessions/SKILL.md for setup / pair / operate steps aligned with this CLI.
Security
See SECURITY.md for security policy, bearer token handling, and best practices.
Community
Open-source. MVP — Codex and Claude providers work (mock + real); APIs may shift before 1.0.
Issues and PRs welcome — see CONTRIBUTING.md. Ideas for tunnel helpers, provider improvements, and other MCP-host guides are especially useful.
If Wingman helped you pair a session, star the repo or open an issue with what you tried. Good wingmen share the checklist.
Develop
git clone https://github.com/juangurdian/wingman.git
cd wingman
npm install
npm run doctor # check environment
npm test # run tests
npm run build # compile TypeScript
CODEX_MOCK=1 npm run pair # or CLAUDE_MOCK=1Node 20+. Success criteria: install, test, build succeed; mock pair prints URL + token.
License
MIT © Juan Gurdian and contributors
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to spawn and control Codex CLI and Claude Code sessions on the host machine, with session management and filesystem access.4MIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP-compatible hosts such as OpenCode to drive the Codex CLI through codex app-server over stdio, exposing tools to run prompts, inspect status, list threads, and interrupt running turns.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients and external AI supervisors to oversee and steer native Codex sessions through a thin local stdio bridge. It exposes eleven codex_* supervisory tools for tasks such as listing threads, starting turns, observing progress, steering, responding to approvals, interrupting, checkpointing, and rolling over work.MIT
- AlicenseNot gradedqualityBmaintenanceEnables local discovery, reading, and messaging between running Codex and Claude Code sessions through MCP.216 npmMIT