Documentation

Getting Started

What is PolyphonyAI?

PolyphonyAI is a native desktop application for multi-agent AI collaboration, coming soon. Instead of chatting with a single AI, you deploy multiple agents from different providers, Claude, GPT, Gemini, Ollama, into a shared conversation. Each agent responds independently, and you control exactly what each agent can see through selective visibility rules.

The core idea: information flow control. You decide which agents see which messages, whose identity is hidden, and which conversations branch off in isolation. This turns basic AI chat into a structured collaboration environment where agents can review, critique, and build on each other's work, or operate in isolation when that produces better results.

System Requirements

• macOS 14 (Sonoma) or later: Apple Silicon (M1/M2/M3/M4)
• Windows 10 or 11
• Linux: major distributions (Ubuntu, Fedora, and similar)
• At least one API key from a supported provider (Anthropic, OpenAI, Google) or a local Ollama installation

Installation

PolyphonyAI is launching soon, join the waitlist on the home page to be notified. Once it's available, installation on macOS takes seconds:

1. Download the .dmg file from the PolyphonyAI website
2. Open the .dmg and drag PolyphonyAI into your Applications folder
3. Launch PolyphonyAI from Applications or Spotlight
4. On first launch, macOS may ask you to confirm opening the app. Click Open in the security dialog

First Launch

When you open PolyphonyAI for the first time, a 5-step welcome modal walks you through the basics: creating a project, deploying agents, sending messages, and using visibility controls. You can dismiss it at any time and check "Don't show again" to skip it in the future.

After the welcome modal, you land on the Command Center: the dashboard where you manage projects, deploy agents, and monitor your fleet.

Setting Up API Keys

PolyphonyAI uses a Bring Your Own Key (BYOK) model. Your API keys are stored in your operating system’s keychain and used only to authenticate requests to the provider you're calling.

1. Open Settings (gear icon in the bottom of the activity bar)
2. Under the API Keys section, you will see fields for each provider:
   • Anthropic: for Claude models
   • OpenAI: for GPT and o-series models
   • Google: for Gemini models
   • Tavily: for web search functionality
   • GitHub: for pull request integration
3. Paste your key and click Save. The key is immediately stored in your operating system’s keychain
4. Click Test to verify the key works. The test button auto-saves before testing, so you do not need to save separately first
5. Saved keys show a masked preview (last 4 characters visible)

Choosing a Theme

PolyphonyAI has three visual themes. Switch between them using the theme pill in the activity bar (three icons: moon, sparkle, sun) or via Settings:

• Dark: deep navy background with frosted glass panels and subtle aurora washes
• Vibrant: dark glass panels with white text on a colorful aurora background (brand blues, indigo, teal, violet)
• Light: light glass panels with black text on a vibrant aurora background

Your theme preference is saved locally and persists across sessions.

Creating Your First Project

1. Click the + icon in the workspace header, or press Cmd+N
2. Name your project
3. Optionally set a working directory: a folder on your disk that agents will have access to. You can browse to it with the directory picker or type the path manually
4. After creation, the template picker appears. Choose from 4 built-in templates (Code Review, Research Session, Architecture Design, General) or start with a blank project
5. Templates pre-deploy a set of agents with appropriate roles and models, you can modify them afterward

Local Profiles

Keep separate setups on one machine. A work profile and a personal profile each hold their own projects, agents, and history, and nothing crosses between them.

• Switch anytime. Pick a profile from the profile menu in the top bar. The app reloads into that profile's projects and conversations.
• Just a directory. A profile is its own data directory on disk. There is no account and no sync, so the boundary is physical: separate files, separate SQLite database.
• Optional PIN. Set a local PIN on a profile to keep it private on a shared machine. The PIN gates opening that profile and never leaves the device.

Updates

The app keeps itself current.

• Update checks. The app checks for new releases and applies them in place, so you stay current without hunting for a download.
• Silent or prompted. Updates install in the background, or ask first, depending on your preference. Either way the running version stays whole until the new one is verified.
• In place. There is no separate installer to download and no reinstall. The next launch runs the new version.

Bring Your History

Start with what you already have. Import your conversations from a Claude.ai export and bring your Claude Code history across, so a new project starts with your existing context instead of a blank slate.

The Command Center

Overview

The Command Center is your dashboard for managing the entire agent fleet across all projects. It gives you a birds-eye view of every agent, their status, model, role, and visibility configuration, all in one place.

Agent Fleet View

Agents are grouped by project. Each project header shows the agent count and branch count (e.g. "2 agents · 3 branches"). Within each group, agent cards display:

• Agent name and role (Architect, Builder, etc.)
• Provider logo: Claude asterisk, OpenAI knot, Gemini star, or Ollama llama
• Model name: the specific model this agent uses (click to change inline)
• Live status: Idle, Thinking (gold pulse), or Streaming (blue pulse)
• Chat / Code badge: whether the agent is a conversational or code-execution agent
• Context bar: shows token usage as a progress bar with the model's context limit. Color-coded: green under 50%, gold 50-80%, red above 80%
• Per-branch token breakdown: when an agent has been active in multiple branches, a breakdown appears below the context bar showing token usage per branch (e.g. "main: 80K, feature-auth: 12K")
• Visibility pills: colored pills showing what each agent can see from other agents (green=visible, red=excluded, amber=blind)
• Spent: accumulated API cost for this agent
• Memory: observation and reflection count for this agent

Stats Bar

At the top of the Command Center, the stats bar gives you a quick summary:

• Total agents deployed across all projects
• Active projects count
• Branches: total conversation branches across all projects
• Visibility rules in effect
• Token usage: estimated context tokens consumed
• Total cost accumulated across all agents

Deploying Agents

Click the robot+ icon next to the /AGENTS header, or press Cmd+D. This opens the deploy modal, which walks you through a three-step flow:

1. Pick a role: choose from 6 built-in roles (Architect, Builder, Researcher, Writer, General, Transcriber)
2. Pick a model: models are grouped by provider (Anthropic, OpenAI, Google, Local). Models recommended for the selected role are marked with a RECOMMENDED tag. Code-capable models show a green CODE badge
3. Name the agent: give it a display name (or accept the default)

Each step has a Back button so you can change your mind. The role selection determines the agent's system prompt and CLAUDE.md template.

Managing Agents Inline

Right from the Command Center agent cards, you can:

• Change model: click the model name to swap models inline
• Remove agent: click the × button on the card
• Clear memory: click the brain icon on agents with active memory
• Save as template: click the floppy icon to save the agent config as a reusable template
• Deploy to other projects: click the copy icon to clone the agent into other projects
• Click card: opens the full agent detail modal (Overview, CLAUDE.md, Context, Tools, Memory tabs)

Context / Token Usage

Each agent card shows a context usage indicator. When an agent's context approaches the model's token limit, the bar fills up. Messages are automatically truncated from the oldest first when the limit is approached, and a warning appears in the output panel at 80% capacity.

Visibility Controls

Each agent card has visibility pills that show the agent's current visibility state relative to other agents in the project. The three states are:

• Full (green): the agent can see messages from the target agent with full attribution
• Excluded (red): the agent cannot see any messages from the target agent. Those messages are completely filtered out of context
• Blind (amber): the agent can see the target agent's messages, but the author is masked as ANONYMOUS. The agent does not know who wrote the content

Blind Review Toggle

For quick setup of anonymous review workflows, you can enable blind review mode which automatically masks agent identities when sharing content. This is useful for getting unbiased feedback on proposals, code, or writing.

Save as Template

Once you have a project configured with the right agents and settings, you can save the configuration as a custom template for future reuse. Click Save as Template from the project options. The template stores the agent lineup, roles, models, and visibility configuration.

Per-Agent Usage

Each agent shows its own token count and running cost right on its card in the conversation. You read it at a glance, without opening the Command Center.

• On the card. Tokens and cost update live as the agent works, next to where it speaks.
• Aggregated in the Command Center. The same numbers roll up across every agent and project in one place.
• Filterable. Sort and filter by project, provider, cost, and tokens to find where spend is going.

Activity Log

Every tool an agent runs is recorded: the command, the target it acted on, the result, and a timestamp for each. Open an agent's Activity tab to review exactly what it did.

• Full trace. Each entry pairs the action with its outcome, so a failed call reads as clearly as a successful one.
• Export. Save the log as JSON or CSV for review outside the app.
• 30-day window. Entries are kept for 30 days, then rolled off.
• Behind the gate. This is the record behind the approval gate, so you can always answer what an agent actually did, not just what it was allowed to do.

Agent Attribution

See which agent produced which change, message, and memory. In a room full of agents, you always know who did what.

• Tagged at the source. Every message and every memory write carries the agent that produced it, enforced by per-agent scoping in the database, not a label the model fills in.
• An action ledger. Each file an agent edits, each command it runs, and each commit it makes is recorded against the agent, so a change traces back to the one responsible.
• One provenance. This is the code-side view of the same provenance that memory tracks, so attribution reads the same whether you are looking at a file or a memory.

Branches in the Fleet View

The Command Center shows forked branches, not just the main thread, and which agents are active in each. Token usage is tracked per branch, so you can see an agent spending heavily on one branch and lightly on another.

The Conversation Interface

Layout

The conversation interface is composed of six main panels, laid out in a VS Code-inspired arrangement:

• Activity bar (far left), vertical icon strip with Command Center (grid), Chat (toggle sidebar), Theme pill (dark/vibrant/light), and Settings (gear)
• Sidebar (left panel), a unified project tree showing all your projects as collapsible nodes. Each project contains Threads, Explorer, and Source Control sections. Multiple projects can be expanded simultaneously. Right-click a project for options including Pin to top and Delete. Toggle the sidebar with Cmd+B or Cmd+1
• Conversation (center), the main chat area where messages appear as card-based bubbles. User messages are right-aligned; agent messages are left-aligned with colored left borders matching the agent's color
• Inspector (right panel), shows deployed agents, their status, and detailed configuration. Click any agent card to open the full detail modal. Toggle with Cmd+3
• Output panel (bottom), displays tool execution output, git results, web search results, context budget warnings, and Claude Code agent tool events. Toggle with Cmd+2
• Composer (bottom of conversation), where you type messages, select recipients, and attach files

All panel dividers are draggable. Drag to resize, or double-click a splitter to collapse that panel. Panel sizes persist across sessions on your machine.

Sending Messages

Type in the composer and press Enter to send. Press Shift+Enter for a new line without sending.

By default, your message goes to all active agents in the project. Passive Transcriber agents aren't shown as recipients, but still receive every message automatically. The send button disables during processing and re-enables when all agents have finished responding.

@Mention Routing

Type @ in the composer to open an autocomplete dropdown showing all agents in the project, each in their assigned color. Use arrow keys and Tab/Enter to select. When you @mention one or more agents, your message is routed only to those agents, overriding the TO chip selection.

@mentions are highlighted in the agent's color both in the composer and in rendered messages.

TO Chips

Above the composer input, you will see TO chips, small pill-shaped badges showing which agents will receive your message. By default, all non-passive agents are included. Click the x on a chip to exclude an agent from receiving this message. Click + to add agents back. Passive agents (Transcriber) are excluded from TO chips but still receive all messages automatically.

How Agents Respond

When you send a message, each targeted agent processes it independently and streams back a response in real time. While an agent is processing:

• A thinking indicator with a pulsing dot appears in the conversation
• The response streams in with live markdown rendering, headers, syntax-highlighted code blocks with copy buttons, lists, links, and more
• The agent card in the inspector shows a THINKING status
• The send button turns into a red stop button: click it or press Escape to cancel all pending agents. Partially streamed responses are preserved with a "[stopped]" marker
• If an error occurs, the status resets to ACTIVE and an error message appears in the conversation

Message Actions

Each message in the conversation has action buttons that appear on hover:

• Pin: pins the message so it appears in a dedicated pinned section at the top of the conversation. Pinned messages are injected into the context of every agent cleared to see them, as [PINNED CONTEXT]
• Fork: creates a new conversation branch starting from this message
• Share dropdown: click the share icon to see a dropdown of agents. Choose to share normally (the agent sees the message with attribution) or blind share (content shared but author masked as ANONYMOUS)

Voice Dictation

Click the microphone in the composer to dictate a message instead of typing. Transcription runs entirely on your machine: a local speech-to-text model turns your voice into text as you speak, and the audio never leaves your device. Your words stream into the message box live; press the mic again (or Enter) to finish, or the trash icon (or Escape) to cancel. Edit the transcribed text like any other message before sending.

Tiling

Keep several conversations open at once. Drag a project from the sidebar into the workspace to open it as a tile, then split, resize, and arrange tiles so related threads sit side by side.

• Whole conversations, tiled. Each tile is a full, visibility-controlled conversation, not a fragment.
• Focus follows you. The sidebar and shared panels track the tile you are working in.
• State persists. Your layout is saved per project and restored when you return.

Move and Copy Between Projects

A conversation that outgrows its project, or research that belongs somewhere else, does not have to be retyped. Copy a thread or a branch into another project and its content comes with it as context.

Agents & Roles

The 6 Built-In Roles

Each role comes with a tailored system prompt and a CLAUDE.md template that shapes the agent's behavior, focus area, and communication style.

Deploying an Agent

The deployment flow is: Role → Model → Name.

1. Click the deploy icon (robot+) next to the /AGENTS header, or press Cmd+D
2. Select a role. Each role shows a brief description of its purpose
3. Select a model. Models are grouped by provider (Anthropic, OpenAI, Google, Local). Models recommended for the selected role are tagged with a RECOMMENDED label. Code-capable models show a green CODE badge
4. Name the agent and confirm

You can go back at each step. Clicking a role immediately moves to the model picker.

Agent Configuration

Click any agent card in the inspector to open the Agent Detail Modal. The Overview tab lets you configure:

• Model: swap to a different model from the same or different provider. Opens the model library filtered by the agent's backend
• Budget limit: maximum dollar amount this agent can spend (defaults to $2.00). Applies to Claude Code agents
• Max turns: maximum number of tool-use turns per response (defaults to 25). Applies to Claude Code agents
• Temperature: displays the agent's temperature setting (read-only in the UI)
• System prompt: editable text area with the agent's system prompt, pre-filled from the role template

Agent Memory

Each agent builds persistent memory across conversations through three pillars: Retention (automatic event logging and reflections), Divergence (visibility rules shape what each agent remembers), and Transfer (share insights across projects). At query time, the most relevant reflections are retrieved via semantic search and injected into context automatically.

For the full guide on how memory works and how to use it, see the dedicated Agent Memory page.

Agent Detail Modal Tabs

The full detail modal has five tabs:

• Overview: editable name, model picker, system prompt, configuration fields (budget, max turns, temperature, thinking, effort), and per-agent cost stats
• CLAUDE.md: the agent's working document. Editable, with a reset-to-default button that restores the role template. This is the equivalent of a CLAUDE.md file, project-specific instructions for the agent
• Context: shows the exact assembled context the agent sees, with a live token count. Includes a full context editor where you can strike through text to temporarily exclude it from context (subtraction-only editing)
• Tools: per-agent toggle switches for web_search, git_context, and file_context. Controls which integrations inject data into this agent's context
• Memory: observation and reflection timeline, transfer controls, and the Cross-Project Transfer toggle. See the Memory page for full details

Consensus and Voting

When several agents answer the same question, have them converge instead of leaving you to reconcile. Agents can vote or synthesize a shared answer, so a room of models produces one considered result.

Agent Chains

Pass one agent's output to the next in a defined sequence. A researcher's findings flow to a writer, whose draft flows to a reviewer, each step handing off automatically.

Conflict Detection

When two agents disagree, the disagreement is surfaced rather than buried. You see where they diverge and why, so a genuine difference of view becomes a decision you make, not a contradiction you miss.

For how these modes work and why they rest on genuine independence, see the dedicated Orchestration page.

Selective Visibility

Why It Matters

When every agent sees everything, agents tend to anchor to each other. The second agent reads the first agent's answer and anchors to it. Visibility control lets you create independent perspectives, adversarial review, blind evaluation, and staged information handoffs, patterns that produce better results than a single shared context ever could.

Per-Message Sharing

Every message has Share and Blind Share buttons. These let you selectively make a message visible to an agent that did not originally receive it:

• Share: the agent sees the full message with the original author's name
• Blind Share: the agent sees the message content, but the author is masked as ANONYMOUS

Once you click either button on a message for a specific agent, both buttons disable for that agent-message pair, you cannot share and blind-share the same message to the same agent.

Per-Message Exclusions

You can exclude specific messages from an agent's context. This is different from visibility rules (which operate at the agent level), exclusions let you surgically remove individual messages from what an agent sees. Excluded messages are filtered out of the agent's context before assembly.

Manage exclusions from the agent's Context tab in the detail modal, or via the message action buttons.

Visibility Rules

Visibility rules operate at the agent level: they define persistent relationships between agents that apply to all messages:

• Excluded: Agent A cannot see any messages from Agent B. Agent B's messages are completely removed from Agent A's context. Use this when you want agents to work in isolation from each other
• Blind: Agent A sees Agent B's contribution but not the author's name. The name is withheld and the content is shown, so work is weighed on its merits, not by who produced it.
• Isolated: Agent A can only see user messages and its own responses, with every other agent excluded. Use this for fully independent work

The Visibility Map

The inspector panel includes a visibility map, a node diagram that visualizes the information flow between agents. Each agent is a node, and the connections between them show the visibility relationship:

• Solid line: full visibility. The source agent's messages are visible to the target with full attribution
• Dashed line: blind visibility. Messages are visible but the author is masked as ANONYMOUS
• Faded/absent line: excluded. No messages flow between these agents in this direction

The map is interactive: click a relationship to change it directly on the map, and it updates in real time, giving you an immediate visual of the information topology.

Practical Workflows

Adversarial Code Review

Deploy a Builder agent to write code and a Researcher agent to review it. Set the Builder to Excluded for the Researcher, so the Researcher only sees the final code, not the design rationale behind it. This forces the Researcher to evaluate the code on its own merits, catching issues that might be rationalized away if the reasoning were visible.

Blind Design Critique

An Architect proposes a system design. A Writer evaluates the proposal with the Architect set to Blind, so the Writer sees the proposal content but not that it came from the Architect. This prevents authority bias: the Writer evaluates the idea, not the reputation of the person who suggested it.

Staged Handoff

The Architect designs in isolation (excluded from every other agent), seeing only the user's requirements and its own responses. Once the design is approved, you pin the final design spec. The Builder, who has been excluded from the design conversation, now sees the pinned spec as [PINNED CONTEXT] and implements from a clean starting point, no design-phase noise in its context.

Silent Observer

Deploy a Transcriber with the passive flag. The Transcriber automatically receives all messages from all agents but never appears in TO chips and never interrupts the conversation. At any point, you can ask the Transcriber to summarize the discussion, document decisions, or flag inconsistencies. Its output goes to the output panel, keeping the main conversation clean.

Agent Lens, See the Conversation as an Agent Sees It

Visibility rules decide what each agent can see. Agent Lens lets you verify it, and act on it. Type @@ and pick an agent (or toggle the lens on its inspector card) to re-render the shared conversation exactly as that agent sees it: blind messages show their author as ANONYMOUS, excluded messages disappear entirely, and only what that agent is cleared to see remains.

While a lens is active, the composer becomes a private channel to that one agent. Anything you send is a 1:1 aside: its visibility is scoped to just you and the lensed agent, so no other agent receives it unless you later Share it. A banner reminds you: "Talking to [Agent], you see the conversation as they do." Exit the lens to return to the full shared view; the lens also clears automatically when you switch projects.

Use it to sanity-check a visibility setup before a long run, to brief one agent privately without cluttering the shared thread, or to debug why an agent answered the way it did, by seeing the exact context it was working from.

The Visibility Matrix

See who sees what as a grid. Alongside the radial map, a matrix view lays every agent against every message source, so you can read and edit visibility rules row by row when a room gets large.

Staged Context Reveal

Reveal context to an agent in stages rather than all at once. Hold back later material until an agent has worked with what it has, so its reasoning is not anchored by information it should not have yet.

Memory & Identity

Agents remember what they learn, so you stop re-teaching them every session. Memory stands on three pillars: what each agent retains, how those memories diverge by visibility, and how insight transfers between projects.

Retention

Each agent accretes its own memory on an append-only event log. Nothing is edited or deleted: the database refuses any attempt to change a recorded memory, so history cannot be quietly rewritten.

• Four kinds of event. Observations (a distilled record of what the agent learned), reflections (a periodic synthesis of recent events), corrections (which supersede an old memory without erasing it), and seeds (context you add directly, plus a role baseline).
• Focused recall. An agent searches its reflections by meaning, re-ranks the strongest matches, and pulls in only the few that bear on the topic.
• Self-healing index. The search index is a derived, rebuildable view of the log, so the append-only record it rebuilds from stays intact.

Divergence

Not every agent sees the same messages, so their memories diverge, and each brings genuinely different context to a problem. A visibility gate checks every memory before it is stored: kept, dropped, or stored with the author anonymized. An agent's memory only ever holds what it was cleared to see.

Transfer

Knowledge built in one project does not have to stay locked there. You mark a reflection as transferable, and a transfer-enabled agent in another project can search that distilled insight by meaning. It arrives as a read-only reference, never copied into the receiving agent's own memory, so it can inform without being edited, deleted, or built on.

Provenance

You can see why an agent knows something. Every memory, reflection, and transferred insight traces back to its source: which message, which agent, which project, or which retrieved document it came from.

The full mechanics, with the scroll-through walkthrough, live on the Memory page.

Conversation Branching

What Branches Are

A branch is a fork of the conversation at a specific message. From that point forward, the branch has its own independent message history. Think of it like git branches for conversations, you can explore an alternative approach without disrupting the main thread.

Every project starts with a main branch. You can create as many branches as you need, and branches can be nested (branch from a branch).

Forking at Any Message

Every message in the conversation has a Fork button. Clicking it creates a new branch that starts from that message. The new branch inherits all messages up to and including the fork point, then diverges. New messages in the branch do not appear in the parent branch, and vice versa.

The fork always creates a child of the current branch, not the main branch. This means you can create deeply nested branch trees.

Branch Tree View

Click View tree in the sidebar to see the full topology of your branches. The tree view shows:

• The main branch at the root
• All child branches with their names
• Merge status, which branches have been merged back
• Merge buttons for unmerged branches

Click any branch in the tree to switch to it.

Branch Isolation

Branches provide full context isolation. When an agent processes a message in a branch, the context builder only includes messages from the branch's lineage, that is, messages from the current branch and its ancestors up to the fork point. Messages from sibling branches or other unrelated branches are not included.

This isolation is critical for exploring alternatives. You can have an agent design two competing approaches in separate branches, each with its own clean context.

Merging

To merge a branch back into its parent:

1. Open the branch tree view
2. Click the Merge button on the branch you want to merge
3. Write a summary of what was decided or accomplished in the branch
4. The summary is posted as a message in the parent branch
5. The branch is marked as merged

Merging does not copy all messages from the branch into the parent. Instead, it posts a summary message that captures the outcome. This keeps the parent branch clean while preserving the decision.

Deleting Branches

You can delete any branch except the main branch. When you delete a branch that has child branches, those children are reparented to the deleted branch's parent, they are not lost. Only the deleted branch's messages are removed.

Multi-Provider Models

Supported Providers

PolyphonyAI supports Anthropic, OpenAI, Google, and local Ollama models, across chat and Claude Code backends:

Anthropic (Claude)

Claude models for chat, reasoning, and writing.

Anthropic (Claude Code backend)

The same Claude models, run as code agents with filesystem and shell access, a separate backend, not extra models.

OpenAI (GPT / o-series)

GPT and o-series models.

Google (Gemini)

Gemini models, including very large context windows.

Local (Ollama)

Local models via Ollama. No API key, and nothing leaves your machine.

Chat vs Code Agents

There are two types of agents, distinguished by their backend:

• Chat agents (claude, chatgpt, gemini, ollama backends), conversational agents that respond with text. They have no filesystem access and cannot execute commands
• Code agents: agents with real filesystem and shell access, run through Claude Code. They can read and edit files, run shell commands, and create code, with Bash, Read, Edit, and Write available by default. They ask before they act, and you approve an action once, for the session, or as a standing rule for that tool. Plan mode lets you approve the whole approach up front.

BYOK, Bring Your Own Keys

All API keys are stored securely in your operating system’s keychain. Keys never leave your machine, they are sent directly from the app to the provider's API endpoint. No keys are stored in the database, in configuration files, or in environment variables at runtime.

Each provider has its own key slot in Settings. You can save, test, and delete keys independently. The masked preview shows the last 4 characters so you can verify which key is stored.

Cost Tracking

Every agent response is logged with input tokens, output tokens, and a cost estimate based on the model's pricing. You can view per-agent cost in the Overview tab of the agent detail modal, or view project-level cost summaries.

Model pricing is maintained per model, with input and output token costs.

Recommended Models Per Role

Each role suggests the kind of model that fits its purpose, and the app tags recommended models in the picker during deployment so you can make an informed choice:

• Architect: a strong reasoning model, for planning and system design
• Builder: a Code agent with filesystem and shell access, for writing and running code
• Researcher: a high-context model, for working across large amounts of material
• Writer: a capable general model, for polished prose
• Transcriber: a lightweight, low-cost model, for passive observation

Model line-ups change often, so pick from each provider's current models: Anthropic, OpenAI, Google, and Ollama.

Workspace & Developer

Claude Code Agents

Claude Code agents run with real filesystem and shell access. They can:

• Read, write, and edit files in the project's working directory
• Execute shell commands via Bash
• Operate in plan mode: where the agent proposes a plan before execution
• Use MCP servers configured for the project

Tool execution events stream in real time to the output panel, so you can see exactly what the agent is doing as it works. Budget and max-turn limits prevent runaway execution.

MCP (Model Context Protocol)

PolyphonyAI has built-in MCP support for Claude Code agents. MCP servers extend agent capabilities with additional tools:

• Filesystem: extended file operations beyond basic read/write
• Git: direct git operations as agent tools
• Fetch: HTTP requests from within the agent
• Memory: long-term memory storage via MCP
• Brave Search: web search from within the agent

The Discover feature suggests well-known MCP servers. You can add custom MCP servers via the MCP settings, specifying the command, arguments, and environment variables. MCP configuration is generated as a temporary JSON file and passed to Claude Code via the --mcp-config flag.

You assign specific tools to each agent, not just to the project, so a given agent gets exactly the tools it should have and nothing more. Every MCP tool call routes through the per-action approval gate, so no external tool runs without your say.

Codebase RAG

PolyphonyAI can automatically index your project's source code using a local embedding model for semantic search. When an agent needs context about the codebase, relevant code snippets are retrieved and injected into the agent's context. This eliminates the need to manually paste files into prompts.

Git Integration

Each project's Source Control section (in the sidebar tree) provides full git operations:

• Read operations: Refresh, Diff, and Log buttons show status, diffs, and commit history inline
• Write operations: Stage & Commit with message input, Push to remote
• Branch switching: dropdown to switch between git branches, plus a button to create new branches
• GitHub PR creation: with a GitHub API key configured, create pull requests directly from PolyphonyAI

All git operations run against the project's working directory. The Source Control section lazy-loads when expanded and is hidden for projects that are not git repositories.

File Explorer & Editor

Each project's Explorer section (in the sidebar tree) shows a tree view of the working directory. Click to expand, it lazy-loads for performance.

• Click a file to open it as a tab in the built-in editor (up to 512KB)
• Multiple tabs: open several files at once, switch between them
• Edit and save: modify file content and save back to disk
• Unsaved indicator: tabs show a dot when the file has been modified
• Per-project state: open tabs are saved and restored per project. Switching projects or going to the Command Center preserves your editor state
• Floating chat: when the editor is open, the conversation collapses into a floating panel in the bottom-right corner so you can keep chatting while editing
• File sizes displayed next to each file
• Drag to attach: drag a file from the explorer to the composer to attach it to your message (50KB cap with warning for larger files)
• Attach button: opens a visual file picker starting from your home directory, showing all files including hidden ones

Inline File Preview

When an agent generates a file, preview it inline in the conversation, expand it, and edit it in place. Open it as a full editor tab when you want more room, the same tab system the Explorer uses.

Web Search

Click the globe button in the composer to perform a web search via the Tavily API. Search results appear in the output panel and are automatically injected into the message context for agents to reference. You need a Tavily API key configured in Settings.

User-initiated searches (clicking the globe button) always pass through to agents regardless of the web_search tool toggle. The toggle only controls automatic or agent-initiated searches.

Project Templates

PolyphonyAI ships with 4 built-in templates:

• Code Review: deploys agents configured for reviewing and discussing code
• Research Session: agents set up for investigation, comparison, and analysis
• Architecture Design: Architect and Builder agents with appropriate models
• General: a minimal starting point with general-purpose agents

You can save any project's configuration as a custom template for reuse. Templates store the agent lineup, roles, models, and settings. Apply a template to a new project immediately after creation.

Specialized templates go further: a code-review agent and a security-review agent arrive with role, model, and visibility already configured, so a focused agent is one click away.

Working Directory

Each project can point at a folder on your disk. This working directory is used for:

• File explorer tree view
• Git operations
• Code agent filesystem access
• Codebase RAG indexing
• Context file paths

Set the working directory during project creation via the directory browser, or use Cmd+O to open a folder and create a project from it (deduplicates if a project for that folder already exists).

WORKSPACE.md

WORKSPACE.md is a project-level rules file that applies to all agents in the project. Think of it as a shared configuration document, coding standards, naming conventions, project-specific instructions that every agent should follow. It is injected into every agent's context alongside their individual role prompts and CLAUDE.md.

Export Thread

Click the export button in the conversation header or press Cmd+E to export the current conversation thread as a markdown file. The exported .md file includes all messages with author attribution, timestamps, and formatting preserved. The file downloads directly to your default downloads folder.

Skills

Skills are reusable instructions you invoke with a slash command. Define a skill once, a name, a description, and the instruction body (with optional argument hints), then type /name in any conversation to inject it as a [SKILL] block into the agents' context. Manage them from the Skills panel: create, edit, and delete your own.

Skills follow Anthropic's Agent-Skills format (a SKILL.md file with YAML front-matter and a Markdown body, the same SKILL.md files Claude Code uses). Import an existing library from a folder or a .zip, and the built-in /help command is always available. Beyond typing /name, an agent applies a relevant skill on its own when the skill's description matches the task, so you do not have to remember to call it.

Skills are scoped the way you need: keep one global across every project, or bind it to a single project. Export any skill to share it or version it alongside your code.

Interactive Terminal

A real shell lives inside PolyphonyAI, scoped to the project's working directory. Open it with Cmd+` and it appears as a panel tab next to your other views. Whatever the project points at is where the terminal starts, so paths, git state, and environment all match what the agents see.

• Yours to drive. Unlike the read-only output panel that streams an agent's tool events, this terminal takes your keystrokes.
• Feed the conversation. Send any output straight into the shared chat so an agent can read the result and act on it.
• Project-scoped. Commands run in the folder the project points at, with no manual cd.

Command Palette

Press Cmd+Shift+P to open a keyboard-first launcher for every action in the app. Start typing and it fuzzy-matches as you go, so dep surfaces "Deploy agent" and vis surfaces your visibility rules.

• Everything in one list. Deploy an agent, switch projects, open a file, toggle a visibility rule, or fork a branch without hunting through menus.
• One index. It draws from the same actions found in the menus and panels, so what you can click you can also type.
• Hands stay on the keyboard. Open, filter, and run an action without reaching for the mouse.

Find in Files

Literal keyword search across every file in the working directory. Reach for it when you know the exact string you want: a function name, a config key, the text of an error message. This is separate from the semantic Codebase RAG.

• Exact text. Matches the characters you type, not the meaning behind them.
• File and line. Each result shows where it lives and jumps you straight there in the built-in editor.
• The right tool for the job. RAG finds code by meaning when you are exploring; Find in Files finds it by exact text when you already know what to look for.

Git Worktrees

Run several code agents in parallel on the same repository without them colliding. Each agent works in its own git worktree, an isolated checkout of a branch, so one agent's edits, installs, and test runs never step on another's. When a branch is ready, merge it back.

• Filesystem isolation. Separate checkouts mean concurrent installs or test runs stay out of each other's way.
• Two kinds of isolation. Worktrees isolate the filesystem; conversation branching isolates context.
• A team on one codebase. Together, the two let a whole set of agents work the same repository at once and reconcile at the end.

Agent Change Review

After a code agent runs, review everything it changed in one place before any of it lands. Accept or reject per file or per hunk, so a good refactor can go in while one questionable edit stays out.

• Sign off after the fact. This is the diff you approve once the work is done, distinct from the approval gate that asks before a tool runs.
• Per file or per hunk. Take the parts you want and leave the rest.
• Attributed. Each change is labeled with the agent that made it, so you always know who wrote what.

Hooks

Run your own script on lifecycle events: when an agent finishes, when a commit lands, or before a tool runs. Hooks are configured per project, so you wire PolyphonyAI into the rest of your workflow.

• Notify. Post to a channel when an agent completes its work.
• Build. Kick off a build the moment a commit lands.
• Log. Write your own record every time a tool runs.

Images & Screenshots

Drop an image into the composer, or attach a screenshot, and ask about it. The image goes to any agent running a vision-capable model.

• Ask in context. Reference a diagram, a UI mockup, or an error screenshot right in the conversation.
• No silent drops. An agent on a model without vision gets a clear note that an image was attached, never a quiet skip.

Also available as a plugin

The same control over what each agent sees also ships as an embeddable plugin, so you can drop it into your own agent stack. You keep your framework, your models, and your infrastructure; the plugin adds the layer that decides what each agent is allowed to see and enforces it on the path, before anything reaches a model or a memory store. It runs entirely in your environment.

The plugin is a separate product with its own pages:

• Plugin overview: what it is and who it is for.
• Integration docs: how to route your calls through the gateways, author clearances, and export decisions to your SIEM.
• Policy sandbox: rehearse any policy change before you make it.

Security & Privacy

Local-first

Your data is stored locally and never sent to us. When you use a cloud model, your prompts go directly to that provider; with a local Ollama model, nothing leaves your machine at all. The app runs against your own storage, not a hosted backend.

• No accounts. There is nothing to sign up for and no identity to manage.
• No sync. Nothing is copied to a server in the background, and there are no hidden servers to reach.

Keys and BYOK

Bring your own API keys. They are stored in the operating system keychain, never on a server, and read only when a request is made. Claude can also run through your own local Claude Code instead of a key.

No telemetry

The app collects nothing about how you use it. There is no usage tracking and no analytics.

Run modes and approval

Code agents do not act on their own. They ask before they act, and you approve once, for the session, or as a standing rule for a given tool. Plan mode lets you approve the whole approach up front. The prompts are fail-closed: no answer denies, so an unanswered prompt never becomes a silent yes.

Keyboard Shortcuts

Troubleshooting

Backend Not Responding

If the app cannot reach its backend, agent responses will fail. PolyphonyAI starts and manages the backend for you automatically. If responses stop working, quit and relaunch the app, which restarts the backend cleanly. If the problem persists, check the output panel for a specific error.

API Key Issues

If agents return authentication errors:

1. Open Settings (gear icon in the activity bar)
2. Verify the correct provider has a key saved (masked preview shows last 4 characters)
3. Click Test: this auto-saves the key before testing, so you do not need to save separately
4. If the test fails, delete the key and re-enter it
5. API keys are stored in your operating system’s keychain. If the keychain is locked or unavailable, keys may not be retrievable

Agent Stuck in "Thinking"

If an agent shows THINKING status indefinitely:

• The error handler automatically resets agents from THINKING to ACTIVE when an error occurs
• On app restart, all agent statuses are reset
• If the issue persists, restart the backend, this clears any stuck subprocess connections
• Check the output panel for error messages that may indicate what went wrong

Context Too Large

When an agent's context approaches the model's token limit:

• A warning appears in the output panel at 80% capacity
• Messages are automatically truncated from the oldest first: the most recent messages are always preserved
• Pinned messages and retrieved reflections are in the highest priority tier and are never truncated
• To reduce context: unpin messages you no longer need, or start a new branch to get a fresh context window

The context builder uses a 4-tier priority system:

1. Tier 1: Role system prompt, retrieved reflections, transferred insights (never truncated)
2. Tier 2: Pinned messages, context files, git context
3. Tier 3: Conversation history (truncated from oldest)
4. Tier 4: Search results, attachments, current message

The app shows stale content after an update

If the app keeps showing old content after an update, fully quit it and reopen. If that does not resolve it, reinstalling the latest version clears any cached content and reloads the app fresh.

Other Common Issues

• File attachments failing: files over 50KB are rejected to prevent context window bloat. The app warns before attaching oversized files
• Git panel not visible: the git panel is automatically hidden for projects whose working directory is not a git repository. Set the working directory to a git-initialized folder
• Web search disabled: the globe button in the composer is disabled if no Tavily API key is configured. Add a Tavily key in Settings
• Agent responses missing markdown: ensure the message content is rendering correctly. All responses support headers, syntax-highlighted code blocks (with copy button), lists, blockquotes, links, bold, italic, and inline code