Core Concepts
A short tour of the Polygent vocabulary. Each concept links to its full guide.
Workspace
A workspace binds Polygent to a Git repository. It is the unit of multi-tenant isolation: users, sessions, tickets, bots, environment variables, hooks, tasks, and templates all live inside a workspace.
- Configurable Git URL, default branch, PAT, and ticket source (
None/GitHub/TFS) - Per-workspace system prompts for Chat, Develop, Merge Conflicts, and Insights
- Workspace users with admin auto-access; non-admins must be assigned explicitly
- Workspace tasks — named scripts (Bash, PowerShell, etc.) reusable from sessions and hooks
→ See Workspaces guide
Session
A session is one AI run, isolated in its own Git worktree.
| Mode | Worktree | Use case |
|---|---|---|
| Chat | Persistent | Ongoing conversation, repo Q&A |
| Develop | Ephemeral | Task-focused work that closes when done |
| Bot | Persistent | Bot-driven conversation |
Sessions support Manual or Auto development modes, per-session toggles (Code Architecture, UX Enhancement, Edge Cases, Code Review, Verification, Update Tests, Update Docs), the Monaco editor, file @ mentions, slash commands, and a built-in Git panel.
→ See Sessions guide
Ticket
A ticket is a unit of trackable work that flows through a pipeline of stages: Pending → Queued → Implementation → Developer Approval → QA Approval → Pull Request → Completed (and may end in Failed, Canceled, or Merge Conflicts). Tickets can be created manually, generated from a Plan, generated from an Insight, or synced from GitHub Issues / Azure DevOps Work Items.
- Lifecycle modes: QA First (default) or Merge First
- Approval flow: developer approval, QA approval (with rejection feedback and attachments), or skip-to-merge
- Iteration tracking: rework grouped by QA rejection rounds
- Queue: tickets start automatically as host capacity frees up, with high-priority tickets picked up first
→ See Tickets guide and Ticket Sync guide
Workflow
A workflow is a reusable multi-step procedure. Steps can be: Message, Clear Context, Asset, Complete Session, Generate Instruction File, Send System Message, or Ralph Loop.
- Auto-advance at the workflow or step level
- Auto-Implementation flag for fire-and-forget runs (no required init params)
→ See Workflows guide
Plan
A plan is a 6-step AI-guided spec wizard: Configuration → Understanding → Clarifications → Recommendations → Specifications → Review. The output is a structured plan.md document that can be exported or converted directly into a ticket.
- Auto-answer modes: MVP, Balanced, Features-Rich, Custom
- Question throttling that scales down as the spec grows
- Worktree isolation per plan, with concurrency lock
→ See AI Planner guide
Ralph Loop
Iterative refinement: re-run the same prompt across context resets until the agent signals completion, the max iterations are reached, or no Git changes occur. Available as a session-level run or as a workflow step. Useful for "loop until tests pass" and "loop until spec is complete" patterns.
→ See Ralph Loop in the Sessions guide
Bot
A bot is a long-lived AI assistant with a fixed system prompt, scoped to a workspace or shared globally. Bots back Chat-mode sessions for fast Q&A, triage, or guided support, with optional public shared URLs.
→ See Bots guide
Round Table
A round table runs a multi-persona AI deliberation across a topic. Pick personas (Moderator, Devil's Advocate, Senior Developer, QA Lead, Product Owner, Designer, or custom workspace personas), send a message, and Polygent runs sequential per-persona replies plus an orchestrator cross-exchange loop. Supports voting, running summaries, and exporting to TXT/Markdown.
→ See Round Table guide
Automation
Automations are scheduled or triggered runs of inline prompts or workflows.
| Type | Trigger |
|---|---|
| One-Time | Specific date/time (with a short grace for past times) |
| Recurring | 5-field cron expression with IANA timezone |
| Loop | Re-execute after the previous session completes |
| Manual | Run-now button only |
| HTTP Trigger | An external webhook URL with a secret token |
Auto-disable kicks in after 3 consecutive failures. The automation's creator receives an inbox notification linking to the executions view so the failure can be investigated.
→ See Automations guide
Insight
An insight is a piece of learning auto-extracted from a completed Develop session — categorized as Documentation, Skill, Process Improvement, Performance, User Experience, Nice to Have, or Other. Dismiss them, turn them into tickets, or use them to feed your docs/skills/commands back into the team's tooling.
→ See Insights guide
Hook
Session hooks run user-defined tasks at lifecycle events: session creation, session start, agent turn complete, session done, and session canceled. Hooks can reference workspace tasks or use inline scripts, with retries, timeouts, branch filters, and an automatic circuit breaker on repeated failures.
→ See Session Hooks in the Sessions guide
Memory
A memory store is a per-workspace named bucket of string items that agents can read and write at runtime via built-in MCP tools. Memory persists across sessions — useful for capturing project conventions, recurring decisions, and team knowledge that should follow every agent run.
→ See Memory guide
IDE Integration
Open any session in your local IDE with a one-liner script (Bash or PowerShell). Push uncommitted changes back to the server with a second script, or pull from your local Git remote into the session worktree. Download tokens expire after 5 minutes and are single-use.
→ See IDE Integration in the Sessions guide
Deployment Agent
A separate worker service deployed on customer machines that registers with the API, sends periodic heartbeats, and runs slots — long-lived deployments with startup/shutdown commands. Use slots to deploy a session (or batch-deploy multiple ticket branches merged into one slot) for QA, demos, or staging.
→ See Deployment Agent guide
Worktree
Every session, plan, and round table runs against an isolated Git worktree on the server's storage path. Worktrees are created on demand and cleaned up when sessions end (Develop) or when explicitly disposed (Chat).
Permissions
Role-based access control with a permission matrix. Admins bypass all checks; the first user to sign in is auto-promoted to Admin. Permissions cover sessions, workspaces, tickets, bots, planner, automations, memory, round tables, statistics, and more.
→ See Permissions guide
Real-Time Updates
All UI updates are delivered over a persistent WebSocket connection — workspace-scoped, with auto-reconnect and live session-presence tracking. No manual refresh is needed.
MCP Server
Polygent exposes a built-in MCP endpoint that lets any compatible agent search tickets, fetch ticket details, and fetch session details — all without additional setup. Compatible with Polygent Code, Claude Code, Gemini CLI, OpenCode, Kilo CLI, Codex, and Qwen Code. Admins can also register their own external MCP servers so every agent run reaches custom tools.
→ See MCP Server guide
Merge Conflicts
A guided workflow for resolving conflicts between two branches. Initiate from branch names, a GitHub PR URL, or an Azure DevOps PR URL. Polygent attempts an AI-assisted resolution in the background (up to 30 minutes) and falls back to a three-pane diff editor (source / destination / merged) for manual fixes. Clean merges auto-commit and push; only one active merge per workspace.
→ See Merge Conflicts guide
External Integrations
| Integration | Capabilities |
|---|---|
| GitHub | OAuth login, issue sync, issue creation, PR creation and live status tracking |
| Azure DevOps / TFS | Work item sync (Bugs), area-path/tag filters, status mapping, PR/MR tracking |
| Git operations | Clone, fetch, push, pull, worktree isolation, credential handling |
GitHub uses workspace-level PATs. Azure DevOps supports per-user PATs (encrypted, max 500 chars) managed under your Profile.
Statistics
A platform-wide analytics dashboard with summary cards plus dedicated views for sessions, tickets, bots, workflows, queues, insights, costs/tokens, user activity, session performance, and hook tasks. Filter by workspace and date range (Last 7/30/90 Days, This Month, Custom). Results are cached server-side for 30 seconds.
→ See Statistics guide
AI Cost Budget
Spend caps at three independent tiers — global (all workspaces), per-workspace, and per-task — measured in real time against per-message cost. Warnings fire at a configurable threshold (default 80%); blocking tiers cancel the offending session when the limit is hit. Per-task budgets are always enforced.
→ See AI Cost Budgets guide
My Work & Notifications
My Work is the unified sidebar surface that merges your active sessions, draft plans, active round tables, and notifications into one live list, with a full history at /my-work. The inbox delivers targeted alerts — failed hooks, pending approvals, budget warnings — only to the people responsible, with optional browser push.
→ See Notifications & My Work guide
User Authentication
OAuth2 sign-in via Google, Microsoft, or any OpenID Connect-compatible identity provider. Polygent issues short-lived access tokens (15 minutes) backed by 7-day rotating refresh tokens stored in secure, HttpOnly cookies. Auth state syncs automatically across browser tabs, and seamless SSO is supported.