agent-client-kernel

A Jupyter Kernel for Zed's Agent Client Protocol (ACP) https://agentclientprotocol.com/ .

This kernel allows you to interact with external ACP agents directly from Jupyter notebooks. It acts as an ACP client that connects to coding agents like Codex, providing a seamless notebook interface for AI-powered coding assistance.

Try This Now

This deep link will create a new (free!) GitHub Codespace (it will ask you first) for running the Codex devcontainer:

QR to this GitHub Repo (https://github.com/wiki3-ai/agent-client-kernel)

.

About

This project implements a Jupyter kernel that serves as a client for coding agents via the Agent Client Protocol. The implementation uses MetaKernel as the base class, which provides built-in magics, shell commands, and other useful features.

The kernel spawns and communicates with external ACP agents (such as codex-acp) via stdio, allowing you to interact with AI coding assistants directly from your notebook.

Features

• ACP Client Implementation: Full client-side ACP protocol support
• External Agent Integration: Connects to any ACP-compatible agent
• Multiple Agent Support: Pre-configured devcontainers for Codex, Gemini, Goose, Kimi, and Docker cagent
• Based on MetaKernel: Built-in magics (help, shell, file operations, etc.)
• Configurable: Easily switch between different agents via environment variables
• Compatible with JupyterLab and Jupyter Notebook

Installation

Using Devcontainers

This project provides multiple devcontainer configurations for different ACP agents. Each devcontainer comes with JupyterLab and the agent-client-kernel pre-installed with the respective agent.

Available devcontainers:

• .devcontainer/codex/ - OpenAI Codex with ACP adapter
• .devcontainer/gemini/ - Google Gemini CLI (Apache 2.0)
• .devcontainer/goose/ - Block's Goose agent (Apache 2.0)
• .devcontainer/kimi/ - MoonshotAI's Kimi CLI (Apache 2.0)
• .devcontainer/cagent/ - Docker's cagent (Apache 2.0)

To use a devcontainer:

1. Open the repository in GitHub Codespaces or VS Code with Dev Containers extension
2. When prompted, select the desired devcontainer (e.g., "Codex", "Gemini", etc.)
3. Wait for the container to build and start
4. JupyterLab will be available on port 8888

For Codex: After JupyterLab starts, open a Terminal and run codex. Follow prompts for API key and authorization then /quit.

Manual Installation

Alternatively, install the project from source. We use uv for reproducible installs against uv.lock:

pip install --upgrade uv
git submodule update --init --recursive
uv sync --locked --extra dev      # or: uv pip install -e ".[dev]"
uv run python -m agent_client_kernel install --user

Configuration

The kernel spawns a subprocess to run the agent which needs installation and ACP adapter.

Using Codex (Default)

1. Install the codex and codex-acp binaries.