{"_id":"@aryanbains/polyagent","_rev":"2-f33956d3b715774b805fbb253c5726bc","name":"@aryanbains/polyagent","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@aryanbains/polyagent","version":"0.1.0","keywords":["agents","ai","ink","llm","multi-agent","orchestration","terminal"],"author":{"name":"Aryan"},"license":"MIT","_id":"@aryanbains/polyagent@0.1.0","maintainers":[{"name":"aryanbains","email":"aryanbains6@gmail.com"}],"bin":{"polyagent":"dist/cli.js"},"dist":{"shasum":"5fb05c1b1b54c45d9d49a4eadbd308c94b083884","tarball":"https://registry.npmjs.org/@aryanbains/polyagent/-/polyagent-0.1.0.tgz","fileCount":6,"integrity":"sha512-gjzZEYW9zgxXN9w/nqz3Mp/HDz5SoeFeLxO3MagiwlcLhlxqcr1VWuaM1HlnsNqvGpRP1UmMcreEO45V0ScdWA==","signatures":[{"sig":"MEQCIBm2SanIzVysiTvTOrsb/K5nRYg4sT1vnm8RHZ049y4pAiAp84clePQVd6lSrpNwNknSfWgV8N62GMf64k5QpSMkaA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":699214},"type":"module","engines":{"node":">=18"},"gitHead":"d521d92d34249ee662ac06d928f2368d008ad161","scripts":{"dev":"tsx src/cli.tsx","test":"vitest run test/config.test.ts test/cli.test.ts test/agents.test.ts test/chat.test.ts test/memory.test.ts test/tools.test.ts test/providers.test.ts test/dashboard.test.tsx test/multi-agent-view.test.tsx test/task-graph.test.tsx test/mouse.test.ts test/approval-queue.test.ts test/session-recorder.test.ts test/phase35.test.ts test/graph.test.ts test/debate.test.ts test/orchestration.test.ts test/react-strategy.test.ts test/prompt-completions.test.ts test/prompt-files.test.ts test/prompt-history.test.ts","build":"tsup","check":"npm run typecheck && npm test && npm run test:e2e","test:e2e":"npm run build && vitest run test/e2e","typecheck":"tsc --noEmit"},"_npmUser":{"name":"aryanbains","email":"aryanbains6@gmail.com"},"_npmVersion":"11.12.1","description":"JavaScript-native multi-agent orchestration CLI for your terminal. Plan, debate, and run a swarm of agents locally.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"ai":"^6.0.199","ink":"^5.1.0","zod":"^4.4.3","diff":"^9.0.0","boxen":"^8.0.1","chalk":"^5.4.1","execa":"^9.6.1","react":"^18.3.1","js-yaml":"^4.2.0","p-queue":"^8.1.1","chromadb":"^3.4.3","commander":"^12.1.0","fast-glob":"^3.3.3","ink-spinner":"^5.0.0","@ai-sdk/groq":"^3.0.39","@tavily/core":"^0.7.5","ink-big-text":"^2.0.0","@ai-sdk/openai":"^3.0.69","ink-text-input":"^6.0.0","ink-select-input":"^6.2.0","@ai-sdk/anthropic":"^3.0.82","@inquirer/prompts":"^8.5.2","@xenova/transformers":"^2.17.2","@ai-sdk/openai-compatible":"^2.0.48"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","tsup":"^8.3.5","vitest":"^2.1.8","typescript":"^5.7.2","@types/node":"^22.10.5","@types/react":"^18.3.18","@types/js-yaml":"^4.0.9","ink-testing-library":"^3.0.0"},"_npmOperationalInternal":{"tmp":"tmp/polyagent_0.1.0_1781530047625_0.7703703134310145","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aryanbains/polyagent","version":"0.1.1","description":"JavaScript-native multi-agent orchestration CLI for your terminal. Plan, debate, and run a swarm of agents locally.","type":"module","bin":{"polyagent":"dist/cli.js"},"engines":{"node":">=18"},"scripts":{"build":"tsup","dev":"tsx src/cli.tsx","test":"vitest run test/config.test.ts test/cli.test.ts test/agents.test.ts test/chat.test.ts test/memory.test.ts test/tools.test.ts test/providers.test.ts test/dashboard.test.tsx test/multi-agent-view.test.tsx test/task-graph.test.tsx test/mouse.test.ts test/approval-queue.test.ts test/session-recorder.test.ts test/phase35.test.ts test/graph.test.ts test/debate.test.ts test/orchestration.test.ts test/react-strategy.test.ts test/prompt-completions.test.ts test/prompt-files.test.ts test/prompt-history.test.ts","test:e2e":"npm run build && vitest run test/e2e","typecheck":"tsc --noEmit","check":"npm run typecheck && npm test && npm run test:e2e"},"repository":{"type":"git","url":"git+https://github.com/aryanbains/polyagent.git"},"homepage":"https://github.com/aryanbains/polyagent#readme","bugs":{"url":"https://github.com/aryanbains/polyagent/issues"},"keywords":["agents","ai","ink","llm","multi-agent","orchestration","terminal"],"author":{"name":"Aryan"},"license":"MIT","dependencies":{"@ai-sdk/anthropic":"^3.0.82","@ai-sdk/groq":"^3.0.39","@ai-sdk/openai":"^3.0.69","@ai-sdk/openai-compatible":"^2.0.48","@inquirer/prompts":"^8.5.2","@tavily/core":"^0.7.5","@xenova/transformers":"^2.17.2","ai":"^6.0.199","boxen":"^8.0.1","chalk":"^5.4.1","chromadb":"^3.4.3","commander":"^12.1.0","diff":"^9.0.0","execa":"^9.6.1","fast-glob":"^3.3.3","ink":"^5.1.0","ink-big-text":"^2.0.0","ink-select-input":"^6.2.0","ink-spinner":"^5.0.0","ink-text-input":"^6.0.0","js-yaml":"^4.2.0","p-queue":"^8.1.1","react":"^18.3.1","zod":"^4.4.3"},"devDependencies":{"@types/js-yaml":"^4.0.9","@types/node":"^22.10.5","@types/react":"^18.3.18","ink-testing-library":"^3.0.0","tsup":"^8.3.5","tsx":"^4.19.2","typescript":"^5.7.2","vitest":"^2.1.8"},"gitHead":"bd46c8615d815f986e76cc66c36f584b15bab712","_id":"@aryanbains/polyagent@0.1.1","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-0y8GWa002PeJCFQQXy68APz6ubwBrv7FoKqLc91Lq70qEzXn1Tzh5YOVmJ6n4/J/+7yjq4Fois0I211B6nTKlw==","shasum":"9d575a1f1b88bb750979f032bb6b81e3e3146481","tarball":"https://registry.npmjs.org/@aryanbains/polyagent/-/polyagent-0.1.1.tgz","fileCount":6,"unpackedSize":700935,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIA87CGwl0DlCzwKdRwAEZSLaWakvTVuMCAv5DklIhteZAiEAozGXTgE897K8and4sMnsxFVHYT9F1dyaqjnuoXAkO7M="}]},"_npmUser":{"name":"aryanbains","email":"aryanbains6@gmail.com"},"directories":{},"maintainers":[{"name":"aryanbains","email":"aryanbains6@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/polyagent_0.1.1_1781532101827_0.4707196127832165"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-15T13:27:27.379Z","modified":"2026-06-15T14:01:42.142Z","0.1.0":"2026-06-15T13:27:27.793Z","0.1.1":"2026-06-15T14:01:42.041Z"},"author":{"name":"Aryan"},"license":"MIT","keywords":["agents","ai","ink","llm","multi-agent","orchestration","terminal"],"description":"JavaScript-native multi-agent orchestration CLI for your terminal. Plan, debate, and run a swarm of agents locally.","maintainers":[{"name":"aryanbains","email":"aryanbains6@gmail.com"}],"readme":"# Polyagent\n\n> JavaScript-native multi-agent orchestration CLI for your terminal.\n> Plan, debate, and run a swarm of agents locally.\n\n[![npm version](https://img.shields.io/npm/v/@aryanbains/polyagent.svg)](https://www.npmjs.com/package/@aryanbains/polyagent)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-blue.svg)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org)\n\nPolyagent is an interactive, terminal-first multi-agent orchestration framework. It brings the multi-agent patterns pioneered in Python frameworks (CrewAI, AutoGen, LangGraph) to the Node.js and TypeScript ecosystem as an installable CLI that feels native to developer terminals.\n\nThe framework is built around a single workflow that no other CLI does in one place:\n\n**Plan** an execution graph from a high-level task.\n**Debate** the plan with a virtual advocate / skeptic / judge panel that proposes modifications.\n**Edit** the plan interactively in the TUI before approving it.\n**Execute** the plan with retries, timeouts, cancellation, and full session recording.\n\n---\n\n## Table of contents\n\n- [Why Polyagent](#why-polyagent)\n- [Install](#install)\n- [Quickstart](#quickstart)\n- [Commands](#commands)\n- [Interactive TUI](#interactive-tui)\n- [Multi-agent orchestration](#multi-agent-orchestration)\n  - [Plans and strategies](#plans-and-strategies)\n  - [Plan debate](#plan-debate)\n  - [Plan graph editor](#plan-graph-editor)\n  - [Execution resilience](#execution-resilience)\n- [Tools](#tools)\n- [LLM providers](#llm-providers)\n- [Memory](#memory)\n- [Configuration](#configuration)\n  - [Environment variables](#environment-variables)\n- [Examples](#examples)\n- [Development](#development)\n- [Project status](#project-status)\n- [License](#license)\n\n---\n\n## Why Polyagent\n\n- **Plan, debate, edit, then execute.** The only CLI where plans are reviewed by an advocate / skeptic / judge panel before any agent runs, and where you can edit the plan graph visually before approving it.\n- **Native TypeScript.** No Python subprocess, no JSON-over-stdio. Everything is real async/await in a single ESM binary.\n- **Real TUI.** Three-pane layout, mouse support, `@`-mention for agents, file path autocomplete, and up/down history recall.\n- **Nine built-in tools.** File I/O, command execution, web search (Tavily + DuckDuckGo), URL fetch, and inter-agent messaging.\n- **Secure by default.** AES-256-GCM encryption for API keys keyed to your machine identity, sandboxed file paths, opt-in tool approvals.\n- **Replayable sessions.** Every multi-agent run is recorded with the full plan, debate transcript, agent messages, and execution events, and can be replayed from the CLI.\n\n---\n\n## Install\n\n```bash\nnpm install -g @aryanbains/polyagent\npolyagent --version\n```\n\nRequires Node.js 18 or newer. Linux, macOS, and Windows are all supported.\n\n---\n\n## Quickstart\n\nRun the onboarding wizard to configure your provider and create a starter `agents.yaml`:\n\n```bash\npolyagent init\n```\n\nThen launch the terminal app:\n\n```bash\npolyagent\n```\n\nType a request at the bottom prompt and press Enter:\n\n```text\n> read package.json and summarize this project\n> list all TypeScript files in src\n> create hello.txt with Hello World\n> create a report at ./reports/summary.md\n```\n\nIn multi-agent mode (`/multi`), the orchestrator first shows you a plan graph you can approve, edit, or reject. Plans can also be debated by a virtual advocate / skeptic / judge panel that proposes modifications before execution.\n\n---\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `polyagent` | Launch the interactive TUI dashboard. |\n| `polyagent init` | Onboarding wizard (provider, API key, memory backend). |\n| `polyagent init --yes ...` | Scripted init for CI and demos. |\n| `polyagent status` | Print current local configuration summary. |\n| `polyagent validate` | Validate `agents.yaml`, `agents.yml`, or `agents.json`. |\n| `polyagent chat <agent>` | Chat with a single agent (script-friendly). |\n| `polyagent run \"<task>\"` | Run a single-agent task. |\n| `polyagent run --multi \"<task>\"` | Plan, debate, and run a multi-agent task. |\n| `polyagent replay <session-id>` | Replay a recorded session. |\n| `polyagent memory` | Show memory backend and embedding count. |\n| `polyagent memory --clear` | Clear all agent memory. |\n| `polyagent --version` | Print installed version. |\n\n---\n\n## Interactive TUI\n\nThe dashboard has three panes:\n\n- **Agents** (left) — click to select, click `[+] New agent` to create one. Status icons show `*` succeeded, `!` failed, `x` cancelled, or a spinner while running.\n- **Conversation** (middle) — streaming agent output, tool activity that collapses into a `Steps taken (N)` summary, and a color-coded transcript (user, assistant, tool, debate, system, error, preview).\n- **Inspector** (right) — project path, selected agent, runtime state, and memory panel.\n\n### Slash actions\n\nPress `/` to open the searchable actions menu. The list filters as you type, so `/set` finds Settings, `/agent` finds the agent builder, and `/multi` switches to multi-agent mode.\n\n| Action | What it does |\n|---|---|\n| `/multi` | Switch to multi-agent mode. |\n| `/single` | Switch to single-agent mode. |\n| `/create` | Open the in-terminal agent builder. |\n| `/settings` | Change run mode, approvals, planner, and web search. |\n| `/memory` | Toggle the memory panel. |\n| `/validate` | Reload and validate `agents.yaml` without leaving the app. |\n| `/clear` | Clear the conversation. |\n| `/cancel` | Stop the active run. |\n| `/help` | Show keyboard controls. |\n| `/exit` | Quit. |\n\n### Keyboard and mouse\n\n- Mouse wheel over the conversation panel scrolls the transcript.\n- Click an agent to select it.\n- Click `[+] New agent` to open the builder.\n- `Up` / `Down` on an empty prompt switches the selected agent.\n- `Up` / `Down` with text in the prompt recalls history.\n- `Tab` accepts the top completion (`@`-mention or `./` file path).\n- `PageUp` / `PageDown` scrolls the transcript.\n- `Esc` closes popups or cancels a running task.\n- `Ctrl+C` cancels a running task, then exits when idle.\n\n---\n\n## Multi-agent orchestration\n\n### Plans and strategies\n\nTop-level `orchestrator` config in `agents.yaml`:\n\n```yaml\norchestrator:\n  strategy: plan_and_execute   # plan_and_execute | sequential | dynamic | react\n  max_parallel_agents: 3\n  max_iterations: 10\n```\n\n| Strategy | Behaviour |\n|---|---|\n| `plan_and_execute` | Creates research, analysis, and synthesis steps, then schedules dependency-ready work in parallel. |\n| `sequential` | Forces a strict dependency chain. |\n| `dynamic` | Asks the LLM planner to return a task-specific JSON plan, validates it, and falls back to the static plan if malformed. |\n| `react` | Single primary agent runs a Reason + Act loop using its tools and the `message_agent` tool to consult specialists. Best for open-ended tasks. |\n\n### Plan debate\n\nWhen the plan has more than one step, Polyagent spins up a virtual advocate / skeptic / judge panel that reviews the plan and proposes modifications before any agent runs:\n\n- **Advocate** defends the plan.\n- **Skeptic** finds dangerous gaps, wrong agent assignments, or underspecified prompts.\n- **Judge** reads the transcript and returns a JSON verdict: `approved: boolean`, `summary: string`, and a list of `modifications`.\n\nModification types the judge can emit:\n\n- `modify_prompt` — strengthen a step's prompt.\n- `reassign_agent` — change which agent owns a step.\n- `flag_risk` — prefix the prompt with `[HIGH RISK]`.\n- `add_step` — insert a new step.\n\nIf the debate fails (network error, malformed JSON), Polyagent falls back to the original plan and continues. The full debate transcript is saved with the session and visible during replay.\n\n### Plan graph editor\n\nBefore execution, the TUI shows a wave-grouped plan graph with these controls:\n\n- `y` — approve the plan.\n- `e` — enter edit mode. Change prompt, swap agent, edit dependencies, add or delete steps, navigate with arrow keys.\n- `n` — request a replan. The planner re-runs with your feedback as additional context.\n\nEdits win over debate modifications: if you edit a step's prompt after a debate, your edit is what gets executed.\n\n### Execution resilience\n\n- **Step retries** with fallback agent reassignment. Default: 1 retry, configurable via `POLYAGENT_AGENT_STEP_RETRIES`.\n- **Step timeouts** with abort signal. Default: 180 seconds, configurable via `POLYAGENT_AGENT_STEP_TIMEOUT_MS`.\n- **Cancellation** — `Esc` or `Ctrl+C` aborts mid-step. The runner records a `cancelled` status without crashing the session.\n- **Approval queue** — multiple tool approvals are serialised so a fast agent does not overwhelm the user with prompts.\n- **Session recording** — every run saves the plan, debate outcome, messages, execution events, step records, artifacts, and stats to `.polyagent/sessions/`. API keys and oversized blobs are redacted on disk.\n\n---\n\n## Tools\n\nAgents can call the tools listed in their `tools` array. Built-in tools:\n\n| Tool | Description |\n|---|---|\n| `read_file(path)` | Read a file with line numbers and binary detection. |\n| `write_file(path, content)` | Write a file (with diff preview and approval). |\n| `append_to_file(path, content)` | Append to a file (with diff preview and approval). |\n| `list_directory(path, recursive?)` | List files in a directory. |\n| `search_files(pattern, directory?)` | Glob-search files in the workspace. |\n| `execute_command(command, working_dir?, timeout_ms?)` | Run a shell command. Default timeout 10 seconds, approval required. |\n| `web_search(query, max_results?)` | Tavily (with `TAVILY_API_KEY`) or DuckDuckGo fallback. |\n| `fetch_url(url)` | HTTP fetch with HTML stripping and timeout. |\n| `message_agent(to, message, expect_response?)` | Send a message to another agent mid-run. |\n\nFile and command tools are workspace-scoped. `write_file`, `append_to_file`, and `execute_command` show a preview and require confirmation unless you pass `--yes`, change Approvals in `/settings`, or set `POLYAGENT_TOOL_APPROVAL=allow`.\n\n---\n\n## LLM providers\n\nPolyagent uses the Vercel AI SDK. Five providers are supported out of the box:\n\n| Provider | Adapter | Default model |\n|---|---|---|\n| OpenAI | `@ai-sdk/openai` | `gpt-4o-mini` |\n| Anthropic | `@ai-sdk/anthropic` | `claude-3-5-haiku-latest` |\n| Groq | `@ai-sdk/groq` | `llama-3.1-8b-instant` |\n| OpenRouter | `@ai-sdk/openai-compatible` | `deepseek/deepseek-v4-pro` |\n| Ollama | `@ai-sdk/openai-compatible` | `llama3.1` |\n\nFor OpenRouter, choose `openrouter` during onboarding and use any OpenRouter model ID in `agents.yaml`:\n\n```yaml\nagents:\n  - name: researcher\n    model: deepseek/deepseek-v4-pro\n    tools: [read_file, web_search, fetch_url]\n```\n\n---\n\n## Memory\n\nThree memory backends:\n\n- `chroma` — uses a local ChromaDB server at `localhost:8000`.\n- `skip` — disables memory (default for scripted init and demos).\n- `pinecone` — reserved for a future cloud adapter.\n\nFor local development without ChromaDB, use the embedded driver:\n\n```bash\nPOLYAGENT_MEMORY_DRIVER=local polyagent chat researcher --message \"Remember Vitest\"\n```\n\nEmbeddings are produced by `@xenova/transformers` (`Xenova/all-MiniLM-L6-v2`) by default, with a deterministic 64-dim hash embedder for fast offline tests:\n\n```bash\nPOLYAGENT_EMBEDDINGS=hash POLYAGENT_MEMORY_DRIVER=local polyagent memory\n```\n\nTo clear memory:\n\n```bash\npolyagent memory --clear\npolyagent memory --agent researcher --clear\n```\n\n---\n\n## Configuration\n\nMachine-level configuration is encrypted with AES-256-GCM (keyed to your machine identity) and stored at `~/.polyagent/config.json` by default. Override the location for tests or isolated runs:\n\n```bash\nPOLYAGENT_HOME=.tmp/polyagent-home polyagent status\n```\n\nPowerShell:\n\n```powershell\n$env:POLYAGENT_HOME = \"$PWD\\.tmp\\polyagent-home\"\npolyagent status\n```\n\n### Environment variables\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `POLYAGENT_HOME` | `~/.polyagent` | Config directory override. |\n| `POLYAGENT_MEMORY_DRIVER` | _(unset)_ | `local` to use the in-repo JSON driver. |\n| `POLYAGENT_EMBEDDINGS` | _(unset)_ | `hash` for offline deterministic embeddings. |\n| `POLYAGENT_TOOL_APPROVAL` | `prompt` | `allow` to skip destructive-tool confirmations. |\n| `POLYAGENT_WEB_SEARCH_PROVIDER` | `auto` | `auto`, `tavily`, or `duckduckgo`. |\n| `POLYAGENT_WEB_TIMEOUT_MS` | `15000` | HTTP timeout for `fetch_url` and web search. |\n| `POLYAGENT_AGENT_STEP_TIMEOUT_MS` | `180000` | Per-step wall clock (max 600000). |\n| `POLYAGENT_AGENT_STEP_RETRIES` | `1` | Retries before reassigning to a fallback agent. |\n| `POLYAGENT_MOCK_LLM_RESPONSE` | _(unset)_ | Force a single-line LLM response (tests). |\n| `POLYAGENT_MOCK_WEB_SEARCH` | _(unset)_ | Force a single-line web search response (tests). |\n| `OLLAMA_BASE_URL` | `http://localhost:11434/v1` | Ollama endpoint. |\n| `TAVILY_API_KEY` | _(unset)_ | Enables Tavily web search. |\n| `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | OpenRouter endpoint. |\n| `OPENROUTER_HTTP_REFERER` | `https://polyagent.dev` | OpenRouter referer header. |\n| `OPENROUTER_APP_NAME` | `Polyagent` | OpenRouter app title. |\n\n---\n\n## Examples\n\nThe `examples/` directory contains three ready-to-run setups:\n\n- `examples/research-team/` — three-agent team (researcher, analyst, writer) using the `dynamic` planner.\n- `examples/code-review-team/` — coder, reviewer, and tester pipeline with the `plan_and_execute` strategy and debate enabled.\n- `examples/single-agent/` — minimal `react` strategy with one helper agent.\n\n```bash\ncd examples/research-team\npolyagent init --yes --project-name Research --working-directory . --provider openai --api-key $OPENAI_API_KEY --memory skip\npolyagent run --multi --yes \"Research the top 5 JavaScript testing frameworks in 2026 and write a markdown report at ./reports/testing-frameworks.md\"\n```\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/aryanbains/polyagent.git\ncd polyagent\nnpm install\nnpm run check\n```\n\n`npm run check` is the main verification command. It runs TypeScript typechecking, the full unit test suite (Vitest), the e2e test suite, and the production build.\n\n---\n\n## Project status\n\nPolyagent `0.1.0` is the first public release. It includes the terminal app, agent definitions, model-provider wiring, memory, file, web, and shell tools, dependency-aware multi-agent orchestration, graph approval and editing, agent-to-agent messages, cancellation, plan debate, session recording, replay, and sensitive-data redaction.\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full release notes.\n\n---\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","readmeFilename":"README.md","homepage":"https://github.com/aryanbains/polyagent#readme","repository":{"type":"git","url":"git+https://github.com/aryanbains/polyagent.git"},"bugs":{"url":"https://github.com/aryanbains/polyagent/issues"}}