AgentProc

English

中文

English

中文

Appearance

AgentProcConnect any Agent CLI to any messaging platform

A minimal process-based protocol. No HTTP, no sockets — just stdin and stdout.

Quick Start
Read the Spec
🚀

5-minute setup

🤖

Works with the CLIs you already use

🔌

Any messaging platform

📜

Open spec, zero lock-in

Get started in 5 minutes ​

① Install the CLI ​

bash
npm install -g agentproc
bash
pipx install agentproc
bash
pip install agentproc

macOS users: pip/pipx not found?

Homebrew's Python ships without pip exposed. Either run python3 -m ensurepip && python3 -m pip install --user pipx, or just use the npm tab above — Node is required for the agentproc CLI anyway (it ships from the npm package).

Verify it works:

bash
agentproc --version
# agentproc 0.14.0 (protocol 0.4)

② Browse the hub ​

bash
agentproc hub list
#   claude-code   official    Connect the claude CLI (Anthropic) as an AgentProc agent
#   codex         official    Connect the codex CLI (OpenAI) as an AgentProc agent
#   gemini-cli    official    Connect the gemini CLI (Google) as an AgentProc agent
#   cursor        official    Connect the Cursor Agent CLI as an AgentProc agent
#   codebuddy     official    Connect the codebuddy CLI (Tencent) as an AgentProc agent
#   grok-build    community   Connect the grok CLI (xAI Grok Build) as an AgentProc agent
#   qwen-code     community   Connect the qwen CLI (Alibaba) as an AgentProc agent
#   kimi-code     community   Connect the kimi CLI (Moonshot AI) as an AgentProc agent
#   deepseek      community   Connect the deepseek TUI as an AgentProc agent
#   aider         community   Connect the aider CLI as an AgentProc agent
#   opencode      community   Connect the opencode CLI as an AgentProc agent
#   agy           community   Connect the agy CLI as an AgentProc agent
#   pi            community   Connect the pi CLI (earendil-works) as an AgentProc agent
#   recursive     community   Connect the recursive CLI (self-improving Rust agent) as an AgentProc agent
#   echo-agent    official    Minimal hello-world agent

The Profile Hub is a curated set of drop-in profiles for popular AI CLIs. No clone, no copy, no YAML editing — the CLI fetches them from GitHub on first use and caches them at ~/.agentproc/cache/hub/<name>/ (24h TTL).

Hit a GitHub rate limit?

Anonymous fetches are capped at ~60/hour. Raise it to 5,000/hour with a token:

bash
export GITHUB_TOKEN=$(gh auth token)   # or any personal access token

If you'd rather skip the network entirely, run against a local checkout: agentproc --profile ./hub/<name>/profile.yaml --prompt "hi".

③ Run it in one line ​

Start with the smoke test (no API key needed):

bash
agentproc hub run echo-agent -p "hello"
# → You said: hello

Then go real. With claude-code, you get streaming output and multi-turn session continuity:

bash
cd ~/projects/my-app          # the agent runs against whatever dir you're in
agentproc hub run claude-code \
  -p "what is this codebase?" \
  --env ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"

No need to edit any profile YAML

agentproc hub run automatically uses your current directory as the agent's cwd, and locates the bundled bridge script via a placeholder. Just cd into the project you want the agent to work on, and run.

You'll see NDJSON events stream on stderr in real time, and the final reply on stdout:

{"type":"partial","text":"This codebase is...","session_id":"13c2f6ec-1f97-42c4-be9e-9475129e243c"}
{"type":"result","text":"","session_id":"13c2f6ec-1f97-42c4-be9e-9475129e243c"}
agentproc:session:13c2f6ec-1f97-42c4-be9e-9475129e243c

Capture that session id and continue the conversation:

bash
agentproc hub run claude-code \
  -p "tell me about the auth module" \
  --env ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  --session 13c2f6ec-1f97-42c4-be9e-9475129e243c

Short replies may not show {"type":"partial"}

Some agents emit the whole reply in one shot when the answer is short — you'll see a single {"type":"result","text":"..."} (with optional session_id), no {"type":"partial"} lines. That's normal; streaming only fragments longer replies.

④ Connect to your messaging platform ​

AgentProc agents don't talk to WeChat or Slack directly — that's the bridge's job. The bridge is a small program that:

  1. Receives a message from the messaging platform (via webhook, polling, etc.)
  2. Spawns your agent and writes a {"type":"turn",...} object to its stdin
  3. Reads NDJSON events from the agent's stdout (per the AgentProc protocol)
  4. Forwards the reply back to the user

Here's a complete working bridge in ~30 lines of Node.js that wires agentproc to anything:

js
// bridge.js — a minimal AgentProc bridge
const { run } = require('agentproc');
const fs = require('fs');

async function handleMessage(message, sessionId) {
  const profile = JSON.parse(fs.readFileSync('./profile.json'));
  const result = await run(profile, {
    message,
    sessionId,
    onPartial: (chunk) => console.log(`[streaming] ${chunk}`),
  });
  console.log(`Reply: ${result.reply}`);
  console.log(`Session: ${result.sessionId}`);  // pass this back next turn
}

// Replace with your platform's SDK:
// yourMessagingPlatform.onMessage(handleMessage);
handleMessage(process.argv[2] || 'hello', '');

Save as bridge.js, point it at a profile, and wire it to your messaging platform's webhook. The runner.js source is the spec in code form — read it as the canonical reference.

Where to go next ​

Released under the MIT License.

Copyright © 2026 jeffkit