glm-acp-agent

An Agent Client Protocol (ACP) agent written in TypeScript that uses the Z.AI / Zhipu AI GLM model family (GLM-5.1, GLM-4.7, GLM-4.6, …) as its reasoning core.

The agent connects to any ACP-compatible IDE or client over stdio, streams responses back in real time, and can call a rich set of tools to interact with the user's file system, terminal, and the web.

Coding Plan Only

glm-acp-agent is intentionally built for the Z.AI GLM Coding Plan. It is not a general-purpose Z.AI Open Platform API client.

By default, model calls use the Coding Plan endpoint:

https://api.z.ai/api/coding/paas/v4

The same Coding Plan API key is used for the agent's GLM model calls and supported Coding Plan tools. General Z.AI API/resource-package billing surfaces, such as direct /api/paas/v4 Tool API calls, are intentionally out of scope for this ACP agent.

Built-in web tools use Coding Plan-compatible MCP endpoints, not the general /api/paas/v4 Tool API. If you need general Z.AI API billing, separate resource packages, or non-Coding Plan endpoints, use a different provider configuration or fork this agent for that purpose.

Features

Full ACP compliance – implements initialize, authenticate, session/new, session/set_mode, session/prompt, session/cancel, session/close, session/list, session/load, session/fork, session/resume, and session/set_model
Streaming – assistant text and reasoning tokens are forwarded as incremental ACP chunks
Tool calling – agentic loop with up to 20 turns of GLM function calling
Thinking mode – GLM's reasoning_content tokens are surfaced as agent_thought_chunk blocks so the client can show the model's chain of thought
Per-session model switching – session/set_model lets clients change the active GLM model mid-conversation; session/new returns the curated availableModels list
Image input via Coding Plan Vision MCP – promptCapabilities.image is advertised; pasted ACP image blocks are routed through Z.AI Vision MCP (@z_ai/mcp-server) and the resulting analysis is fed into the main coding model. Direct chat-image (e.g. glm-4v-plus) calls are intentionally not used.
Session persistence – conversations are written to ~/.local/state/glm-acp-agent/sessions/ and can be reloaded via session/load, branched via session/fork, or resumed without replay via session/resume
Six built-in tools (see below)
Capability-aware – every tool is gated on the client capabilities advertised at initialize time; tools the client can't run return a clear error to the model instead of crashing
Permissioned writes / commands – every write_file and run_command call asks the user via session/request_permission before doing anything
Protocol-correct stop reasons – maps model and runtime conditions to ACP end_turn, max_tokens, max_turn_requests, refusal, and cancelled
Protocol-correct tool statuses – pending → in_progress → completed / failed
Token usage reporting – aggregated usage is returned on the session/prompt response

Architecture

ACP Client (IDE plugin, CLI, …)
        │  stdio (ndjson)
        ▼
  GlmAcpAgent          ← ACP protocol layer  (src/protocol/)
        │
        ├─ GlmClient   ← Z.AI / Zhipu AI Coding Plan Chat Completions  (src/llm/)
        │
        ├─ ToolExecutor ← executes tool calls  (src/tools/)
        │    ├─ read_file / write_file       → ACP client (fs.*)
        │    ├─ list_files / run_command     → ACP client (terminal)
        │    ├─ web_search / web_reader      → Z.AI Coding Plan Web MCP (HTTP)
        │    └─ image_analysis               → Z.AI Coding Plan Vision MCP (stdio)
        │
        └─ VisionMcpClient ← spawns `npx @z_ai/mcp-server` on demand

The agent process needs network access to api.z.ai for chat completions and Web MCP, plus npx available on PATH so it can launch @z_ai/mcp-server for vision. Filesystem and shell operations remain delegated to the ACP client; the agent itself only writes to the OS temp directory when it needs to materialize a pasted image for Vision MCP, and those temp files are removed once the prompt completes.

Available Tools

Tool	Runs on	Requires client capability	Description
`read_file`	ACP client	`fs.readTextFile`	Read the text content of a file
`write_file`	ACP client	`fs.writeTextFile`	Write or overwrite a text file (asks for permission)
`list_files`	ACP client	`terminal`	List a directory via `ls -la` (POSIX shell required)
`run_command`	ACP client	`terminal`	Run an arbitrary shell command via `sh -c` (asks for permission)
`web_search`	Agent (Z.AI Coding Plan MCP)	–	Search the web — returns titles, URLs, and summaries
`web_reader`	Agent (Z.AI Coding Plan MCP)	–	Fetch and parse a web page (markdown or plain text)
`image_analysis`	Agent (Z.AI Vision MCP, stdio)	–	Analyze a local image path or remote URL using `@z_ai/mcp-server`

Prerequisites

Node.js 20 or later (native fetch and Web Streams required)
npm 9 or later
A Z.AI API key — obtain one at https://z.ai/manage-apikey/apikey-list

Installation

git clone https://github.com/stefandevo/glm-acp-agent.git
cd glm-acp-agent
npm install
npm run build

Configuration

The agent reads its configuration from environment variables, plus an optional credentials file written by glm-acp-agent --setup.

Variable	Required	Default	Description
`Z_AI_API_KEY`	One of env / `--setup`	—	API key for the Z.AI / Zhipu AI service. If unset, the credentials file is consulted.
`ACP_GLM_MODEL`	No	`glm-5.1`	Default GLM model for new sessions
`ACP_GLM_AVAILABLE_MODELS`	No	built-in list	Comma-separated list of model ids advertised in `session/set_model`
`ACP_GLM_BASE_URL`	No	`https://api.z.ai/api/coding/paas/v4`	Override the API base URL
`ACP_GLM_MAX_TOKENS`	No	`8192`	Cap on `max_tokens` for each completion
`ACP_GLM_THINKING`	No	auto-detected	Force thinking mode `true` / `false`
`ACP_GLM_SESSION_DIR`	No	`$XDG_STATE_HOME/glm-acp-agent/sessions`	Where session JSON files are persisted
`ACP_GLM_DEBUG`	No	—	Set to `true` or `1` to enable verbose debug logging to stderr (shows model selection, API key resolution, tool calls, and usage stats)
`XDG_CONFIG_HOME`	No	`~/.config`	Where the credentials file is read/written

One-time setup

If you'd rather not pass Z_AI_API_KEY through your ACP client's environment block, run the interactive setup once and the agent will read the key from disk on subsequent launches:

# From the project directory (after npm run build)
node dist/index.js --setup

# Or, if you installed globally
glm-acp-agent --setup

The key is written to $XDG_CONFIG_HOME/glm-acp-agent/credentials.json (default: ~/.config/glm-acp-agent/credentials.json) with 0600 permissions. The Z_AI_API_KEY environment variable, when set, always wins over the file.

Supported models

The agent advertises only the models on the current Z.AI Coding Plan allowlist:

Model	Notes
`glm-5.1`	Default. Long-horizon coding model; thinking mode auto-enabled
`glm-5-turbo`	Faster Coding Plan reasoning model
`glm-4.7`	200K-context reasoning model
`glm-4.5-air`	Lightweight, lower-latency model

ACP_GLM_AVAILABLE_MODELS still lets you advertise custom IDs, but custom IDs sit outside the supported Coding Plan list — the Coding Plan endpoint will reject any model code Z.AI hasn't whitelisted (business code 1211).

Vision (glm-4v-plus etc.) is not advertised as a chat model: vision on the Coding Plan flows through the Vision MCP section below instead.

When the model name matches glm-4.5, glm-4.6, glm-4.7, or glm-5.x, the agent enables Z.AI's thinking: { type: "enabled" } extension and forwards reasoning tokens to the client as agent_thought_chunk blocks. Override with ACP_GLM_THINKING=false if you want plain completions only.

Vision MCP

Pasted ACP image blocks are not sent to the chat-completions endpoint. Instead, the agent boots @z_ai/mcp-server over stdio (via npx -y @z_ai/mcp-server@latest) and calls its image_analysis tool. The text result is spliced into the user message as <image_analysis index="N">…</image_analysis> so the regular Coding Plan model can reason about it.

Prerequisites:

npx on PATH (Node 18+ / npm 9+).
The same Z_AI_API_KEY used for chat completions; the agent forwards it to the MCP server as Z_AI_API_KEY plus Z_AI_MODE=ZAI.

The model can also call image_analysis explicitly with { image_source: "/path/or/url", prompt?: "…" }. Vision failures (missing npx, MCP startup, quota) are surfaced as actionable errors but never abort the prompt; an inline <image_analysis_error> annotation is used so the conversation can continue.

Running

Standalone (stdio)

export Z_AI_API_KEY=your_key_here
node dist/index.js

The agent speaks the ACP newline-delimited JSON protocol over stdin/stdout. You can connect any ACP-compatible client to it.

As a global CLI

npm install -g .
export Z_AI_API_KEY=your_key_here
glm-acp-agent

Development mode (watch)

export Z_AI_API_KEY=your_key_here
npm run dev        # tsc --watch

Connecting to an ACP Client

Zed (recommended for local testing)

Zed is currently the most polished editor for trying out ACP agents locally — it spawns the agent process over stdio and surfaces it in the agent panel. This is the fastest way to iterate on glm-acp-agent before publishing it to the ACP registry or to npm.

1. Prerequisites

A recent build of Zed that supports the agent_servers setting
Node.js 20 or later on your PATH (node --version)
A Z.AI API key — create one at https://z.ai/manage-apikey/apikey-list

2. Build the agent

git clone https://github.com/stefandevo/glm-acp-agent.git
cd glm-acp-agent
npm install
npm run build

Take note of the absolute path to the freshly built entry point — Zed needs it (no ~, no $HOME shortcuts):

echo "$(pwd)/dist/index.js"

3. Wire it into Zed

Open (or create) ~/.config/zed/settings.json and add an agent_servers entry. Pick one of the two API-key strategies below.

Option A — inline env block (simplest):

{
  "agent_servers": {
    "glm": {
      "command": "node",
      "args": ["/absolute/path/to/glm-acp-agent/dist/index.js"],
      "env": { "Z_AI_API_KEY": "sk-…" }
    }
  }
}

Option B — credentials file (no key in your editor settings):

Run the interactive setup once. From the project directory:

node dist/index.js --setup

…or, if you npm install -g .'d the package:

glm-acp-agent --setup

The key is written to ~/.config/glm-acp-agent/credentials.json with 0600 permissions. Then drop the env block from the Zed entry — the agent will read the file on launch:

{
  "agent_servers": {
    "glm": {
      "command": "node",
      "args": ["/absolute/path/to/glm-acp-agent/dist/index.js"]
    }
  }
}

If Z_AI_API_KEY is set in the environment and a credentials file exists, the environment variable wins.

4. Verify it works

Save settings.json. Zed reloads settings automatically.
Open the agent panel (use the command palette: agent panel: toggle focus).
In the agent picker, select glm — Zed labels external agents by their agent_servers key.
Start a new thread and send a small prompt that exercises a tool, e.g. Read package.json and tell me the project name.
You should see streaming text, a read_file tool call awaiting permission, and (with a thinking-capable model like glm-5.1) reasoning surfaced as a separate thought block.

5. Iterating on the agent

After editing the source, rebuild:

npm run build

Zed spawns a fresh agent process per thread, so the easiest way to pick up changes is to start a new thread with the glm agent. If you see stale behavior, fully quit and reopen Zed — that guarantees no in-flight process is reused.

For a tighter inner loop, run npm run dev in a terminal so dist/ rebuilds on every save; you only need to start a new Zed thread to test the latest code.

6. Troubleshooting

The "glm" agent doesn't appear in the picker. — settings.json likely has a JSON parse error, or your Zed build is older than agent_servers support. Open the Zed log via the command palette (zed: open log) and look for settings errors.
Error: Cannot find module '/.../dist/index.js' — you skipped npm run build, or the path in args is wrong. It must be absolute and point at a file that exists.
No API key found. — neither Z_AI_API_KEY nor ~/.config/glm-acp-agent/credentials.json is set. Use Option A or Option B in step 3.
HTTP 401: Invalid API key — your key is wrong, expired, or for the wrong region. Rotate it on https://z.ai/manage-apikey/apikey-list.
client does not advertise the … capability — Zed didn't expose that capability to the agent (e.g. terminal for run_command/list_files). Ask the model to use a different tool, or upgrade Zed.

Neovim / VS Code / JetBrains / any ACP client

Any client that supports configuring an ACP agent via a command + args invocation works the same way: point it at node /absolute/path/to/glm-acp-agent/dist/index.js and supply Z_AI_API_KEY in the environment.

Authentication

The agent advertises two authentication methods at initialize time:

An agent-default method — the agent will read the API key itself, either from the Z_AI_API_KEY environment variable or from the credentials file written by glm-acp-agent --setup.
An env_var method (experimental SDK extension) describing the Z_AI_API_KEY variable so capable clients can prompt the user and inject it.

ACP clients that support the auth-methods proposal will use whichever method they recognise; clients that don't handle auth methods should set Z_AI_API_KEY themselves before launching the agent (or run glm-acp-agent --setup once and let the agent read it from disk).

Project Structure

src/
├── index.ts                  # Entry point – starts stdio connection or --setup flow
├── setup.ts                  # Interactive credential setup (`--setup`)
├── llm/
│   ├── glm-client.ts         # OpenAI-compatible client for Z.AI / Zhipu AI
│   └── credentials.ts        # API-key resolution (env var > credentials.json)
├── protocol/
│   ├── connection.ts         # Sets up the ACP stdio connection
│   ├── agent.ts              # GlmAcpAgent – ACP protocol implementation
│   └── session-store.ts      # On-disk persistence for load/fork/resume
├── tools/
│   ├── definitions.ts        # Tool JSON schemas (function-calling format)
│   └── executor.ts           # ToolExecutor – dispatches tool calls
└── tests/
    ├── agent.test.ts         # Protocol-level tests for GlmAcpAgent
    ├── credentials.test.ts   # Credential resolution and --setup persistence
    ├── executor.test.ts      # Tests for ToolExecutor
    ├── glm-client.test.ts    # Tests for streaming / tool-call assembly
    └── integration.test.ts   # End-to-end tests over the real ACP ndjson transport

Building & Testing

npm run build   # one-shot TypeScript compilation → dist/
npm run dev     # watch mode
npm test        # build + run unit tests with the node:test runner

The test suite covers:

ACP protocol-version negotiation, capability advertising, and auth method shape
Session lifecycle (new / list / close, filter by cwd)
Prompt loop streaming, tool-call assembly, max-turn cap, cancellation, stop-reason mapping (stop → end_turn, length → max_tokens, content_filter → refusal, tool_calls exhausted → max_turn_requests)
Content-block conversion (text, resource_link, embedded resource)
Token usage reporting on the PromptResponse
Tool call lifecycle (pending → in_progress → completed / failed)
Capability gating (tools refuse cleanly when the client did not advertise the required capability)
Permission flows for write_file and run_command (allow / reject / cancel)
Shell-quoted argument handling for list_files and run_command
GLM streaming: text deltas, reasoning_content deltas, multi-chunk tool-call assembly, and trailing usage
Image preprocessing through a mocked Vision MCP client and graceful degradation on Vision MCP failures

Troubleshooting

No API key found. — either set Z_AI_API_KEY in the environment, or run node dist/index.js --setup (or glm-acp-agent --setup if installed globally) once to store the key on disk.
HTTP 401: Invalid API key — your key is wrong or expired; rotate it on https://z.ai/manage-apikey/apikey-list.
The agent says "client does not advertise the … capability". — your ACP client doesn't expose that capability (e.g. terminal). Ask the model to use a different tool, or upgrade the client.
Tools never get to run. — make sure the client is sending the clientCapabilities field in initialize; the agent uses it to decide which tools to expose to the model.

License

Apache 2.0 – see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
.github/workflows		.github/workflows
registry		registry
src		src
.gitignore		.gitignore
README.md		README.md
RELEASING.md		RELEASING.md
icon.svg		icon.svg
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

glm-acp-agent

Coding Plan Only

Features

Architecture

Available Tools

Prerequisites

Installation

Configuration

One-time setup

Supported models

Vision MCP

Running

Standalone (stdio)

As a global CLI

Development mode (watch)

Connecting to an ACP Client

Zed (recommended for local testing)

1. Prerequisites

2. Build the agent

3. Wire it into Zed

4. Verify it works

5. Iterating on the agent

6. Troubleshooting

Neovim / VS Code / JetBrains / any ACP client

Authentication

Project Structure

Building & Testing

Troubleshooting

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages