🎺 Overview

Polyagent is a thin layer over AI coding agent CLIs. It gives Claude Code, Codex, Kimi, and Pi one shared way to create, continue, attach, list, fork, and stream provider sessions without reshaping provider output.

❓ Motivation

I use multiple coding agents and often want one agent to continue a session, inspect sessions in the current repo, or get another agent's second opinion.

Why? Each provider stores and attaches to sessions differently. Polyagent makes that workflow scriptable from one command.

⭐ Features

• One command shape for Claude Code, Codex, Kimi, and Pi sessions.
• Named sessions that continue context across separate CLI calls.
• Project session discovery with active-session filtering.
• Native provider attach by name, session id, or path.
• Session forking for parallel investigations.
• Text, JSON, and provider-native stream-json output.

🚀 Quick Start

1. Install the CLI globally:

   npm install -g polyagent-lvt
   # now you can use "pa" or "polyagent" in your terminal

2. Send a message to a provider in a named session:

   pa session send --message "review this branch" --provider claude --session-name review

3. Continue the same session:

   pa session send --message "what did I ask before?" --session-name review

4. List sessions for the current project:

   pa session list

Package API

Provider sessions accept persistent provider-level instructions and process-local environment metadata separately from user messages:

const session = createSession(ProviderName.Pi);
await session.start({
  cwd: process.cwd(),
  environment: { MY_SESSION_CONTEXT: JSON.stringify({ runId: "run-1" }) },
  instructions: "Review code and report concrete findings.",
});
await session.send("Inspect the authentication changes.");

Check session.capabilities.instructions before relying on native instruction support. Pi, Claude, Codex, and Kimi support it. Callers that resume a session should pass the same start options again because Polyagent does not persist caller metadata.

🧰 Usage

# session commands
pa session attach [--session-name <session-name>] [--session-path <session-path>] [--provider <provider>] [--permission-mode <mode>] [--session-id <session-id>]
pa session create [--session-name <session-name>] [--provider <provider>] [--model <model>] [--permission-mode <mode>] [--message <message>] [--output <mode>]
pa session fork [--name <name>] [--provider <provider>] [--session-id <session-id>] [--session-name <session-name>] [--session-path <session-path>]
pa session list [--active] [-l, --limit <count>] [--message <mode>] [--named] [-o, --output <mode>] [-p, --provider <provider>]
pa session remove <name>
pa session send [--provider <provider>] [--model <model>] [--permission-mode <mode>] [--session-name <session-name>] [--session-id <session-id>] [--session-path <session-path>] [--message <message>] [--file <path>] [--delivery <delivery>] [--output <mode>]
pa session show [--session-name <session-name>] [--session-path <session-path>] [--provider <provider>] [--session-id <session-id>]

# other commands
pa active [--output <mode>] [--json]
pa doctor [--output <mode>] [--json]

| Variable | Default | Description | | ------------------------ | ---------------------------- | ------------------------------------------------ | | POLYAGENT_CONFIG_DIR | OS user config dir | Directory used for Polyagent named-session data | | POLYAGENT_PROG_NAME | polyagent or invoked bin | Displayed program name | | OMNI_TURN_TIMEOUT_MS | 600000 | Provider turn timeout in milliseconds | | POLYAGENT_DEV_BIN_DIR | ~/.local/bin or npm prefix | Directory used by the local development shims |

import { forkSession, listSessions, send } from 'polyagent-lvt';

await send({ provider: 'codex', sessionName: 'review', message: 'Review this branch' });
await send({ sessionName: 'review', message: 'Urgent update', delivery: 'steer' });
const sessions = listSessions({ namedOnly: true });
const forked = forkSession({ sessionName: 'review', name: 'review-fork' });

Delivery notes:

• --delivery steer and --delivery followUp target an active named session started by another Polyagent session send process.
• Pi supports active delivery through RPC steer/follow-up.
• Claude uses realtime stream-json input for best-effort steer and Polyagent queues follow-up.
• Codex uses app-server turn/steer with the active turn id and Polyagent queues follow-up.
• Kimi uses prompt-mode stream-json; active steering is unavailable and Polyagent queues follow-up.

For a better terminal experience, enable shell completion so pa <tab> can show available commands, subcommands, and flags.

Add this to your .zshrc:

eval "$(pa completion zsh)"

For other shells, generate the matching completion script:

pa completion bash
pa completion fish

🛠 Development

Install the local development commands:

pnpm install
pnpm dev:install
pad --help
polyagentd --help

This creates pad and polyagentd, which run the current workspace version without replacing your global pa or polyagent commands.

Add zsh completion for pad:

eval "$(pad completion zsh)"

Remove the local development commands when you are done:

pnpm dev:uninstall

📜 License

MIT