lingma-proxy-compose/README.md

Lingma IPC Proxy

English | 简体中文

Lingma IPC Proxy exposes Tongyi Lingma's local IDE plugin capability as standard OpenAI-compatible and Anthropic-compatible HTTP APIs. It can be used as a CLI proxy service or as a cross-platform desktop app for macOS and Windows.

The project is designed for tools such as Claude Code, Cline, Continue, OpenCode, custom agents, and any client that can talk to OpenAI or Anthropic style APIs.

Current Version

The current desktop line is v1.3.2.

Release builds are produced by GitHub Actions for:

Asset	Platform	Purpose
lingma-ipc-proxy_<tag>_darwin_arm64.tar.gz	macOS	CLI proxy
lingma-ipc-proxy_<tag>_windows_amd64.zip	Windows	CLI proxy
lingma-ipc-proxy-desktop_<tag>_darwin_arm64.dmg	macOS Apple Silicon	Drag-to-install desktop app
lingma-ipc-proxy-desktop_<tag>_darwin_arm64.zip	macOS Apple Silicon	Raw .app archive
lingma-ipc-proxy-desktop_<tag>_windows_amd64.zip	Windows	Desktop app
lingma-ipc-proxy_<tag>_sha256.txt	all	Checksums

Which Package Should I Download?

Your system	Recommended asset	Notes
macOS on Apple Silicon (M1/M2/M3/M4)	lingma-ipc-proxy-desktop_<tag>_darwin_arm64.dmg	Open the DMG and drag Lingma IPC Proxy.app to Applications.
macOS on Apple Silicon, portable archive	lingma-ipc-proxy-desktop_<tag>_darwin_arm64.zip	Same app, but packaged as a zip instead of a drag-to-install DMG.
Windows x64 / x86_64 / AMD64	lingma-ipc-proxy-desktop_<tag>_windows_amd64.zip	This is the correct package for normal 64-bit Windows PCs, including Intel and AMD CPUs.
macOS CLI only	lingma-ipc-proxy_<tag>_darwin_arm64.tar.gz	Terminal-only proxy binary.
Windows CLI only	lingma-ipc-proxy_<tag>_windows_amd64.zip	Terminal-only proxy binary for 64-bit Windows.

There is currently no separate windows_arm64 package. On a normal x64 Windows machine, choose windows_amd64.

Desktop App

The desktop app wraps the proxy with a native-feeling control panel:

• Start, stop, and restart the proxy.
• Inspect health, latency, recent requests, models, settings, and logs.
• View full request and response bodies with internal scrolling and hidden scrollbars.
• Copy endpoint URLs, model IDs, request logs, and response logs with visible feedback.
• Detect Lingma IPC paths automatically on macOS and Windows, with manual fallback settings.
• Follow system theme automatically, or switch light/dark mode manually.
• Keep the proxy running when the window is closed; quit explicitly from the app/menu.

Screenshots

Light mode:

Dark mode:

Narrow window layout:

Supported APIs

API	Endpoint	Support
Health	GET / and GET /health	supported
Models	GET /v1/models	supported
Capability Discovery	GET /capabilities, GET /v1/capabilities	supported
LM Studio / Ollama Discovery	GET /api/v1/models, GET /api/tags, GET /props	supported
OpenAI Chat Completions	POST /v1/chat/completions	streaming and non-streaming
OpenAI Chat Alias	POST /api/v1/chat/completions	supported
Anthropic Messages	POST /v1/messages	streaming and non-streaming

What This Fork Adds

Compared with the original protocol proof of concept, this repository focuses on making the proxy usable as a complete local product:

• Function Calling / Tools for both OpenAI and Anthropic clients.
• Tool result continuation for multi-step agent loops.
• Tool stability hardening with proxy-side routing hints, core tool examples, missed-tool retry, and common alias mapping such as Bash to terminal and Read to read_file.
• Image input for OpenAI image_url and Anthropic image blocks.
• Local and remote image normalization for data URLs, HTTP URLs, file:// URLs, and absolute local paths, with automatic JPEG downscaling for large images.
• Request log image redaction so large base64 payloads are visible as image markers instead of breaking the desktop log view.
• More request parameter compatibility so stricter clients can connect without custom patches.
• Full request and response recording in the desktop app for debugging 400/500 errors.
• macOS and Windows desktop app with start/stop/restart, settings, logs, model discovery, themes, and window lifecycle handling.
• Cross-platform release packaging for CLI and desktop builds.

OpenAI Compatibility

The proxy accepts common OpenAI request fields:

• model, messages, stream
• temperature, top_p, stop
• max_tokens, max_completion_tokens
• presence_penalty, frequency_penalty
• tools, tool_choice, parallel_tool_calls
• response_format, seed, user, reasoning_effort
• image input through image_url data URLs, HTTP URLs, file:// URLs, and absolute local paths

Anthropic Compatibility

The proxy accepts common Anthropic request fields:

• model, system, messages, stream
• temperature, top_p, top_k, stop_sequences
• max_tokens, metadata
• tools, tool_choice
• image blocks through base64 sources
• tool result continuation blocks

Architecture

flowchart LR
  Client["OpenAI / Anthropic Client"] --> HTTP["HTTP API Layer"]
  Desktop["Desktop App"] --> AppBridge["Wails Go Bridge"]
  AppBridge --> Service["Proxy Service"]
  HTTP --> Service
  Service --> Session["Session Manager"]
  Service --> Tools["Tool Emulation"]
  Service --> Models["Model Discovery"]
  Service --> Transport["Lingma Transport"]
  Transport --> Pipe["Windows Named Pipe"]
  Transport --> WS["macOS / Windows WebSocket"]
  Pipe --> Lingma["Tongyi Lingma IDE Plugin"]
  WS --> Lingma

Module Layout

Path	Responsibility
cmd/lingma-ipc-proxy	CLI entrypoint, config loading, signal handling
internal/httpapi	OpenAI/Anthropic HTTP routes, streaming SSE responses, request recording
internal/service	request orchestration, sessions, model discovery, proxy lifecycle
internal/lingmaipc	Lingma JSON-RPC transport over Named Pipe and WebSocket
internal/toolemulation	tool definition injection, action block parsing, tool result projection
desktop	Wails desktop shell, native window commands, proxy control bridge
desktop/frontend	Vue UI for dashboard, requests, models, settings, and logs
.github/workflows/release.yml	CI release pipeline for macOS and Windows CLI/Desktop packages

Transport Detection

Platform	Default transport	Detection
macOS	WebSocket	reads Lingma SharedClientCache files under user application support paths
Windows	Named Pipe / WebSocket	scans Lingma named pipes and shared cache hints
Linux	WebSocket	manual --ws-url is recommended

If auto detection fails, set the path manually in the desktop Settings page or pass CLI flags:

lingma-ipc-proxy --transport websocket --ws-url ws://127.0.0.1:36510 --port 8095
lingma-ipc-proxy --transport pipe --pipe '\\.\pipe\lingma-ipc'

Quick Start

Desktop App

1. Install VS Code and the Tongyi Lingma extension.
2. Log in to Tongyi Lingma and verify the Lingma panel can chat normally.
3. Download the desktop asset from Releases.
4. Start Lingma IPC Proxy.
5. Click 探测模型 after the proxy is running.
6. Configure clients to use http://127.0.0.1:8095.

CLI

git clone https://github.com/Lutiancheng1/lingma-ipc-proxy.git
cd lingma-ipc-proxy
go build -o ./dist/lingma-ipc-proxy ./cmd/lingma-ipc-proxy
./dist/lingma-ipc-proxy --host 127.0.0.1 --port 8095 --session-mode auto

Windows:

.\scripts\build.ps1
.\dist\lingma-ipc-proxy.exe --host 127.0.0.1 --port 8095 --session-mode auto

Client Configuration

Claude Code

export ANTHROPIC_BASE_URL="http://127.0.0.1:8095"
export ANTHROPIC_API_KEY="any"

Then select a model in Claude Code:

/model MiniMax-M2.7

Cline

• Provider: OpenAI Compatible
• Base URL: http://127.0.0.1:8095/v1
• API Key: any
• Model ID: MiniMax-M2.7

Continue

{
  "models": [
    {
      "title": "Lingma Proxy",
      "provider": "openai",
      "model": "MiniMax-M2.7",
      "apiKey": "any",
      "apiBase": "http://127.0.0.1:8095/v1"
    }
  ]
}

Models

The proxy reports the models exposed by the Lingma plugin. The desktop app does not force a global model switch; the calling client should specify the model field. Clicking a model in the desktop app copies its model ID.

Observed model IDs include:

• Auto
• Kimi-K2.6
• MiniMax-M2.7
• Qwen3-Coder
• Qwen3-Max
• Qwen3-Thinking
• Qwen3.6-Plus

Model Metadata and Recommendation

The proxy only reports models actually exposed by your Lingma plugin. The table below combines official model information where available with local proxy testing. If Lingma exposes a model name without public model-card metadata, the README marks it as observed rather than inventing a context length.

Model	Best use	Context / capability basis
MiniMax-M2.7	Default recommendation for third-party agents	NVIDIA's MiniMax M2.7 model card describes a language MoE model with 200K input context and agentic use cases; local proxy testing passed read/search/terminal/web/patch/vision smoke tests.
Kimi-K2.6	Multimodal and long-context agent work	Kimi's official API docs describe native text/image/video input, a 256K context window, and multi-step tool invocation support.
Qwen3-Coder	Code-specialized fallback	Qwen's official blog describes 256K native context, up to 1M with extrapolation, and agentic coding/tool protocols.
Qwen3.6-Plus	General/vision fallback	Exposed by Lingma and passed local smoke tests, but this repository does not have an official Lingma-specific context-length source for it.
Qwen3-Max	Fast general/vision model	Exposed by Lingma and strong in simple tests, but less stable on forced edit/read tool calls in this proxy.

Default model when the client omits model: MiniMax-M2.7.

Configuration

Default config file:

./lingma-ipc-proxy.json

Example:

{
  "host": "127.0.0.1",
  "port": 8095,
  "transport": "auto",
  "mode": "agent",
  "shell_type": "zsh",
  "session_mode": "auto",
  "timeout": 120,
  "cwd": "/Users/you/project",
  "current_file_path": ""
}

Priority order:

1. built-in defaults
2. JSON config file
3. environment variables
4. command-line flags
5. desktop Settings page updates

Concurrency

Older builds rejected concurrent chat requests with a rate_limit_error saying the proxy handled one request at a time. Current builds use a small execution pool instead:

• default max concurrent chat requests: 4
• override with LINGMA_PROXY_MAX_CONCURRENT
• allowed range: 1 to 16
• session_mode=auto uses fresh Lingma sessions so parallel editor requests do not share one sticky session

Example:

LINGMA_PROXY_MAX_CONCURRENT=8 lingma-ipc-proxy --port 8095

Function Calling / Tool Calling

Lingma does not expose a native public OpenAI/Anthropic tool-call protocol, so this proxy emulates tool calling:

1. Normalize OpenAI or Anthropic tool definitions.
2. Inject tool contracts into the Lingma prompt.
3. Parse model action blocks from the response.
4. Convert parsed actions back into OpenAI tool_calls or Anthropic tool_use.
5. Feed tool results back into Lingma for continuation.

Current proxy hardening includes:

• a generated tool routing table based on the client's actual tool names
• dedicated examples for read_file, search_files, terminal, and web_search
• automatic retry when the model says it cannot access files, terminal, or web despite tools being present
• common tool alias normalization such as Bash -> terminal, Read -> read_file, Grep -> search_files, and Edit -> patch

In local smoke tests after this hardening, MiniMax-M2.7, Kimi-K2.6, Qwen3.6-Plus, and Qwen3-Coder all completed read/search/terminal/web/patch/vision checks, with MiniMax-M2.7 having the lowest average latency in the tested set.

Local Desktop Build

Install Wails:

go install github.com/wailsapp/wails/v2/cmd/wails@v2.12.0

Build macOS:

npm ci --prefix desktop/frontend
cd desktop
wails build -platform darwin/arm64 -clean

Build Windows on Windows:

npm ci --prefix desktop/frontend
cd desktop
wails build -platform windows/amd64 -clean

The desktop bundle name is always Lingma IPC Proxy.

Release Plan

The release workflow is triggered by:

• pushing a tag such as v1.3.2
• manually running the Release workflow with a tag input

Planned improvements:

• macOS signing and notarization
• Windows installer packaging
• configurable log retention
• request export/import
• richer model metadata display
• optional Linux desktop packaging after the Lingma transport story is stable

Acknowledgements

This project is based on the protocol insight and initial discovery work from coolxll/lingma-ipc-proxy. The core idea of connecting to Lingma's private local IPC protocol and exposing standard API endpoints came from that project. This fork extends the implementation with broader OpenAI/Anthropic compatibility, tool emulation, image handling, desktop app support, request/log inspection, cross-platform packaging, and release automation.