A peer orchestrator that puts Claude, Codex, Copilot, and any Claude-compatible API (GLM, Ollama, etc.) in the same terminal. You talk, they listen. They talk to each other. Nobody is the boss except you.

No MCP. No master/servant. No window juggling. Just peers at a terminal table.

What's new in v0.12.0

• Agent sidebar with live activity accordion. Per-agent status, current tool/file, scrollable activity log. Toggle with Ctrl+B. Auto-hides on narrow terminals.
• Animated splash screen when the terminal is idle. Octopus mascot rendered in block characters.
• Rich activity details in sidebar and status bar. See exactly what each agent is doing: Read: src/index.ts, Bash: npm test, Search: handleSubmit.
• Cancel panel (Esc when agents are active). Multi-select which agents to kill, the rest keep working.
• CWD bar at the bottom of the terminal showing your current working directory.

Why llm-party?

| | Traditional multi-agent | llm-party | | ---------------------- | ------------------------------ | -------------------------------------- | | Architecture | MCP (master controls servants) | Peer orchestration (you control all) | | Integration | CLI wrapping, output scraping | Direct SDK adapters | | Sessions | Fresh each time | Persistent per provider, resumable | | Context | Agents are siloed | Every agent sees the full conversation | | Concurrency | Sequential or blocked | Non-blocking per-agent queues | | API tokens | Separate keys per tool | Uses your existing CLI auth |

Getting started

Prerequisites

Bun runtime is required. At least one AI CLI must be installed and authenticated:

bun --version            # Bun runtime
claude --version         # Claude Code CLI
codex --version          # OpenAI Codex CLI
copilot --version        # GitHub Copilot CLI

If a CLI doesn't work on its own, it won't work inside llm-party.

Install

bun add -g llm-party-cli

First run

llm-party

On first run, llm-party automatically creates ~/.llm-party/ with a default config and global memory structure. Your system username is detected automatically. No setup commands needed.

Add more agents

Edit ~/.llm-party/config.json:

{
  "agents": [
    {
      "name": "Claude",
      "tag": "claude",
      "provider": "claude",
      "model": "opus"
    },
    {
      "name": "Codex",
      "tag": "codex",
      "provider": "codex",
      "model": "gpt-5.2"
    },
    {
      "name": "Copilot",
      "tag": "copilot",
      "provider": "copilot",
      "model": "gpt-4.1"
    }
  ]
}

That's it. No paths, no prompts, no usernames to configure. Just name, tag, provider, model.

Talk to your agents

@claude explain this error          # talk to one agent
@claude @codex review this          # talk to multiple
@all what does everyone think?      # broadcast to all agents
@everyone same as @all              # alias

Note: Once you tag an agent, all follow-up messages without a tag go to that same agent. Use @all or @everyone to broadcast again.

Agent-to-agent handoff

Agents can pass the conversation to each other by ending their response with @next:<tag>. The orchestrator picks it up and dispatches automatically. Max 15 hops per cycle to prevent loops.

Non-blocking queue

You can type while agents are working. Each agent has its own queue. If an agent is busy when a new message arrives, the message is queued and processed when the agent finishes. No blocking, no waiting for slow agents to finish before fast ones can respond.

WARNING: FULL AUTONOMY.

All agents run with full permissions. They can read, write, edit files and execute shell commands with zero approval gates. There is no confirmation step before any action. Run in a disposable environment. You are responsible for any changes, data loss, costs, or side effects. Do not run against production systems.

Important notes

Uses your existing CLIs. llm-party uses official SDKs that delegate to each provider's CLI binary. If claude, codex, or copilot commands work on your machine, llm-party works. Authentication is handled entirely by the provider's own tools.

Run in isolation. Always run llm-party inside a disposable environment: a Docker container, a VM, or at minimum a throwaway git branch. Agents have full filesystem and shell access with zero approval gates.

Full permissions. All agents can read, write, edit files and execute shell commands. There is no confirmation step before any action. You are responsible for any changes, data loss, costs, or side effects.

How we use the SDKs

llm-party uses official, publicly available SDKs and CLIs published by each provider. Nothing is reverse-engineered, patched, or bypassed.

| Provider | Official SDK | Published by | | -------- | ----------------------------------------------------------------------------------------------- | ------------ | | Claude | @anthropic-ai/claude-agent-sdk | Anthropic | | Codex | @openai/codex-sdk | OpenAI | | Copilot | @github/copilot-sdk | GitHub |

Custom providers (GLM, Ollama, etc.) route through a native CLI's SDK with environment overrides. No additional SDKs are required.

All authentication flows through the provider's own CLI. llm-party does not implement its own auth flow, store credentials, or intercept authentication traffic.

Supported providers

Native providers (detected automatically)

| Provider | SDK | Session | Prompt Support | | ----------------- | ---------------------------------- | -------------------------------------- | -------------------------------------------------- | | Claude | @anthropic-ai/claude-agent-sdk | Persistent via session ID resume | Full control | | Codex | @openai/codex-sdk | Persistent thread with run() turns | Via developer_instructions (limitations below) | | Copilot | @github/copilot-sdk | Persistent via session ID resume | Full control |

Custom providers (config-driven)

Any AI that exposes a Claude-compatible API can be added as a custom provider. Custom providers route through a native CLI (currently Claude) with environment overrides.

| Provider | API | Notes | | ----------------- | ---------------------------------- | -------------------------------------------------- | | GLM | Zhipu AI (api.z.ai) | Full Claude SDK compatibility via proxy | | Ollama | Local (localhost:11434) | Any model Ollama supports | | Any | Any Claude-compatible endpoint | Just set AUTH_URL and AUTH_TOKEN |

How it works

llm-party uses SDK adapters directly. Each agent gets a persistent session with its provider. Full tool access. Real conversation threading. The orchestrator owns routing, agents are peers.

Terminal (you)
    |
    v
Orchestrator
    |
    +-- Agent Queue Manager (per-agent queues, non-blocking dispatch)
    |
    +-- Agent Registry
    |     +-- Claude  -> ClaudeAdapter  (SDK session, resume by ID)
    |     +-- Codex   -> CodexAdapter   (SDK thread, resumeThread by ID)
    |     +-- Copilot -> CopilotAdapter (SDK session, resumeSession by ID)
    |     +-- Custom  -> CustomAdapter  (routes through native CLI + env override)
    |
    +-- Conversation Log (ordered, all messages, agent-prefixed)
    |
    +-- Transcript Writer (JSONL, append-only, per session)
    |
    +-- Session Manifest (per-agent cursors + SDK session IDs, for resume)

Each agent has its own processing queue. When you send a message, idle agents start immediately while busy agents queue it. You can keep typing while agents work. Each agent receives only unseen messages since its last turn, so no duplicate processing on resume or during concurrent dispatch.

~/.llm-party/config.json is your global config. Every agent receives a base system prompt automatically. The prompts field in config adds extra prompt files on top of it.

Provider details

Claude

| | | | ------- | ----------------------------------------------------------------------------------------------- | | SDK | @anthropic-ai/claude-agent-sdk | | Session | Persistent via resume: sessionId. First call creates a session, subsequent calls resume it. | | Prompt | Passed directly to the SDK. Full control over personality, behavior, and workflow rules. | | Tools | Read, Write, Edit, Bash, Glob, Grep |

Codex

| | | | ------- | ---------------------------------------------------------------------------------------------------------------- | | SDK | @openai/codex-sdk | | Session | Persistent thread. startThread() creates it, resumeThread() restores it. thread.run() adds turns. | | Prompt | Injected via developer_instructions config key. Appended alongside Codex's built-in 13k token system prompt. | | Tools | exec_command, apply_patch, file operations |

Known limitation: Codex's built-in system prompt cannot be overridden. Your instructions are appended alongside it. Action instructions (naming, formatting, workflow rules) work. Personality overrides do not.

Copilot

| | | | ------- | ----------------------------------------------------------- | | SDK | @github/copilot-sdk | | Session | Persistent via createSession() with session ID. Resumable via resumeSession(). | | Prompt | Set as systemMessage on session creation. Full control. | | Tools | Copilot built-in toolset |

Custom (GLM, Ollama, etc.)

| | | | ------- | -------------------------------------------------------------------------------- | | SDK | Uses the native CLI's SDK (currently Claude's @anthropic-ai/claude-agent-sdk) | | Session | Same as the underlying CLI | | Prompt | Same as the underlying CLI. Full control. | | Tools | Same as the underlying CLI |

Custom providers route API calls through a native CLI by overriding AUTH_URL and AUTH_TOKEN in the agent's env block. The cli field selects which native CLI to use (defaults to claude).

Config reference

Config file: ~/.llm-party/config.json (created automatically on first run).

Override with LLM_PARTY_CONFIG env var to point to a different file.

Top-level fields

| Field | Required | Default | Description | | --------------- | -------- | -------------------------- | ---------------------------------------------------------------------------- | | humanName | No | Your system username | Display name in the terminal prompt and passed to agents | | humanTag | No | derived from humanName | Tag for human handoff detection (@next:you) | | maxAutoHops | No | 15 | Max agent-to-agent handoffs per cycle. 0 = unlimited | | timeout | No | 600 | Default timeout in seconds for all agents | | agents | Yes | | Array of agent definitions |

Agent fields

| Field | Required | Default | Description | | ------------------ | -------- | ------------------------ | --------------------------------------------------------------------------------------------------- | | name | Yes | | Display name shown in responses as [AGENT NAME]. Must be unique. | | tag | Yes | | Routing tag for @tag targeting. Letters, numbers, hyphens, underscores only. No spaces. | | provider | Yes | | SDK adapter: claude, codex, copilot, or custom | | cli | No | "claude" | For custom providers: which native CLI to route through | | active | No | true | Set to false to disable an agent without removing its config | | model | Yes | | Model ID passed to the provider. Examples:opus, sonnet, gpt-5.2, gpt-4.1, glm-5 | | prompts | No | none | Array of extra prompt file paths, concatenated after base.md. Relative to project root | | executablePath | No | PATH lookup | Path to the CLI binary. Supports ~/. Only needed if the CLI is not in your PATH | | env | No | inherits process.env | Environment variable overrides for this agent | | timeout | No | top-level value | Per-agent timeout override in seconds | | preloadSkills | No | none | Array of skill names to load at boot. Skills are discovered from ~/.llm-party/skills/, .llm-party/skills/, .claude/skills/, .agents/skills/ |

Prompts

Every agent receives a base system prompt automatically. To add extra instructions per agent, use the prompts field:

{
  "name": "Reviewer",
  "tag": "reviewer",
  "provider": "claude",
  "model": "opus",
  "prompts": ["./prompts/code-review.md"]
}

Template variables available in prompt files:

| Variable | Description | | --------------------------- | ----------------------------- | | {{agentName}} | This agent's display name | | {{agentTag}} | This agent's routing tag | | {{humanName}} | Your display name | | {{humanTag}} | Your routing tag | | {{agentCount}} | Total number of active agents | | {{allAgentNames}} | All agent names | | {{allAgentTags}} | All agent tags as @tag | | {{otherAgentList}} | Other agents with their tags | | {{validHandoffTargets}} | Valid @next:tag targets | | {{preloadedSkills}} | Skills assigned to this agent via preloadSkills |

Custom provider setup

Custom providers use AUTH_URL and AUTH_TOKEN in the env block. The adapter maps these to the correct environment variables for the underlying CLI.

GLM (Zhipu AI):

{
  "name": "GLM",
  "provider": "custom",
  "cli": "claude",
  "model": "glm-5",
  "env": {
    "AUTH_URL": "https://api.z.ai/api/anthropic",
    "AUTH_TOKEN": "your-glm-api-key"
  }
}

Ollama (local):

{
  "name": "Ollama",
  "provider": "custom",
  "cli": "claude",
  "model": "llama3",
  "env": {
    "AUTH_URL": "http://localhost:11434/v1",
    "AUTH_TOKEN": "ollama"
  }
}

Any endpoint that speaks the Anthropic API protocol works. Set AUTH_URL to the base URL and AUTH_TOKEN to the API key.

Skills

Skills are folders containing a SKILL.md file with specialized instructions for specific workflows. Agents discover skills from these locations (in order):

1. ~/.llm-party/skills/ (global, shared across all projects)
2. .llm-party/skills/ (project-local)
3. .claude/skills/ (if present)
4. .agents/skills/ (if present)

Assign skills to agents with preloadSkills in config:

{
  "name": "Reviewer",
  "provider": "claude",
  "model": "opus",
  "preloadSkills": ["aala-review"]
}

At boot, the orchestrator verifies each skill exists and reports status per agent. Skills assigned to an agent are also shown in the team directory visible to all peers.

Mind-map

Shared memory between all agents, stored as Obsidian-compatible notes in ~/.llm-party/network/mind-map/. Each entry is a .md file with frontmatter and [[wikilinks]] connecting related findings. INDEX.md is the entry point that agents read on boot.

Agents write to the mind-map as they work: constraints, discoveries, session progress, cross-project breadcrumbs, user preferences. Anything a cold-boot agent would need to know that is not in the code. Open the folder in Obsidian to visualize the knowledge graph.

Session and transcript

Every run generates a unique session ID and appends messages to a JSONL transcript in .llm-party/sessions/ (project-level). The session ID and transcript path are printed at startup.

File changes made by agents are detected via git status after each response. Newly modified files are printed with timestamps.

Resume a session

Pick up where you left off by passing the session ID:

llm-party --resume 20260402-102915-74722-ba956b96

Or use the /resume command as your first input in a fresh session:

/resume 20260402-102915-74722-ba956b96

The session ID is shown at startup (and in /info). Resume loads the full transcript, restores per-agent SDK sessions (Claude session IDs, Codex thread IDs, Copilot session IDs), and tracks which messages each agent has already seen. Agents pick up exactly where they left off with no duplicate processing.

A .manifest.json file alongside each transcript stores the session state: agent cursors, SDK session IDs, sticky targets. This is what makes cross-provider resume possible.

Resume only works before the first message is sent. Once a conversation has started, resuming another session into it is not allowed.

Terminal commands

| Command | What it does | | ---------------- | -------------------------------------------- | | /agents | Open agents panel overlay (Ctrl+P also works) | | /config | Open config wizard | | /info | Commands and keyboard shortcuts panel | | /save <path> | Export conversation as JSON | | /resume <id> | Resume a previous session (first message only) | | /changes | Show git-modified files | | /clear | Clear chat display (Ctrl+L also works) | | /exit | Quit (graceful shutdown, all adapters cleaned up) | | Ctrl+P | Toggle agents panel | | Ctrl+B | Toggle agent sidebar | | Ctrl+L | Clear chat | | Ctrl+C | Copy selection or exit | | Ctrl+A / E | Jump to start / end of input line | | Ctrl+U | Clear entire input line | | Ctrl+W | Delete word backward | | Esc | Open cancel panel (when agents are active) | | Shift+Enter | Insert new line in input | | Up / Down | Input history | | PageUp/Down | Scroll chat |

Development

git clone https://github.com/aalasolutions/llm-party.git
cd llm-party
bun install
bun run dev

Build and run:

bun run build
bun start

Override config:

LLM_PARTY_CONFIG=/path/to/config.json bun run dev

Troubleshooting

"No agent matched @tag" Run /agents to see available tags. Tags match against agent tag, name, and provider.

"Unsupported provider" Valid providers: claude, codex, copilot, custom.

"Duplicate agent name" Agent names must be unique (case-insensitive). Rename one of the duplicates in config.

Agent modifies source code unexpectedly Expected with full permissions. Use git to review and revert.

Codex ignores personality instructions Known limitation. Codex's 13k token built-in prompt overrides personality. Functional instructions still work.

"ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite" Your Node.js version is below 22. The Copilot SDK requires Node.js 22+.

Agent response timeout Default is 600 seconds (10 minutes). Adjust with timeout in config (top-level or per-agent).