🎺 Overview

Polyagent is a thin layer over AI coding agent CLIs. It gives Claude Code, Codex, and Gemini 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, and Gemini 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

🧰 Usage

# session send commands
pa session send --message "..." --provider claude --session-name <name>
pa session send --message "..." --provider codex --session-name <name>
pa session send --message "..." --provider gemini --session-name <name>
pa session send --file <path> --provider claude --session-name <name>
pa session send --message "..." --output json
pa session send --message "..." --output stream-json

# active commands
pa active
pa active --json

# session commands
pa session create --provider claude --session-name <name>
pa session attach --session-name <name>
pa session attach --session-id <session-id>
pa session attach --session-path <session-path>
pa session list
pa session list --active
pa session show --session-id <session-id>
pa session fork --session-id <session-id> --name <name>
pa session fork --session-name <name> --name <new-name>
pa session remove <name>

# completion commands
pa completion bash
pa completion fish
pa completion zsh

# other commands
pa doctor

| 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' });
const sessions = listSessions({ namedOnly: true });
const forked = forkSession({ sessionName: 'review', name: 'review-fork' });

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