Core Concepts
This glossary defines the user-visible objects that Supporters encounter when configuring and troubleshooting Polygent. Each concept links to its operating guide.
Workspace
A workspace binds Polygent to one or more Git repositories and is the unit of access isolation: members, sessions, tickets, environment variables, hooks, tasks, and templates all belong to a workspace.
- Repositories with Git URL, default branch, access token, and folder name
- Ticket source: None, GitHub, or Azure DevOps / TFS
- Guidelines — workspace instructions for Chat, Development, Plan, Merge Conflicts, Insights, Code Review, and Verification
- Members — administrators have access to every workspace; other users must be added
- Tasks — named scripts (Bash, PowerShell, Cmd, Node.js, Python) reused by hooks
→ See Workspaces guide
Session
A session is an agent conversation running in its own Git working copy, so concurrent sessions never share a working directory; actual concurrency depends on host limits and compute.
| Mode | Working copy | Use case |
|---|---|---|
| Chat | Persistent, shared by Chat sessions with the same branch selection | Questions and ongoing conversation |
| Develop | Isolated per session, released when it completes | Changes to review, commit, push, or merge |
Bot conversations use the bot's configured mode (Chat or Develop). Develop sessions support Auto Code Review and Auto Verification, a file editor, @ file mentions, / slash commands, and a Git panel.
→ See Sessions guide
Ticket
A ticket is a unit of tracked work that moves through Pending → Queued → (Plan) → Implementation → Developer Approval → QA Approval → Pull Request → Completed, and can end in Failed, Canceled, or Merge Conflicts. Tickets are created manually, from a Plan, from an Insight, by an automation, or by sync from GitHub Issues or Azure DevOps work items.
- Lifecycle: QA First (default) or Merge First, per workspace
- Approvals: developer and QA approval with feedback and attachments, or privileged Skip to Merge
- Iterations: rework grouped by QA rejection rounds
- Queue: tickets start as host capacity frees up; High priority first, Low only during the configured hour
→ See Tickets guide and Ticket Sync guide
Workflow
A workflow is a reusable multi-step procedure that runs in a session. Steps are Message, Task, Clear Context, Complete Session, Generate Instruction File, Send System Message, and Ralph Loop.
- Workflow- and step-level auto-advance
- Initial, step, and automatic parameters (
$ticket-description,$session-url,$env:NAME, and more) - Auto-Implementation workflows run unattended for tickets
→ See Workflows guide
Plan
A plan is a Planner specification built through a six-step guided flow: Configuration → Understanding → Clarifications → Recommendations → Specifications → Review. The result can be exported or turned into a ticket. Tickets can also run a Plan stage that produces an implementation plan for approval before coding starts.
- Auto Answer modes: Disabled, MVP, Balanced, Features Rich, Custom
- Isolated working copy for repository-aware planning
→ See Planner guide
Ralph Loop
A Ralph Loop repeats the same prompt with a fresh context each iteration until the agent signals completion, the maximum iterations is reached, or an iteration makes no Git changes. It runs in a session, as a workflow step, or from a Develop automation.
→ See Ralph Loop in the Sessions guide
Bot
A bot is a reusable assistant configuration — instructions, mode (Chat or Develop), model, capability limits, and access rules — scoped globally or to selected workspaces. Polygent ships built-in bots (for example Request, Debugger, Help With Polygent) that administrators can customize or reset.
→ See Bots guide
Round Table
A round table is a private discussion in which selected AI personas examine a topic against a workspace's repositories. It supports votes, summaries, export to Markdown or text, and ticket or plan drafts. Built-in personas must be enabled per workspace before use.
→ See Round Table guide
Automation
Automations start sessions — or create tickets — without someone opening them by hand.
| Type | Trigger |
|---|---|
| One-time | A specific date and time |
| Recurring | Cron expression, macro, or interval in a selected timezone |
| Loop | Starts again after the previous session finishes |
| Manual | Run Now only |
| HTTP Trigger | A webhook call authenticated with a secret token |
Three consecutive failed sessions disable any type except Manual, and the creator is notified.
→ See Automations guide
Insight
An insight is a finding extracted from a completed Develop session, categorized as Documentation, Skill, Process Improvement, Performance, User Experience, Nice To Have, Tests, or Other. Dismiss insights or turn them into tickets.
→ See Insights guide
Hook
Session hooks run workspace tasks or scripts at lifecycle events — session created, first message, agent finished, session done, and session canceled — with retries, timeouts, branch and changed-file filters, and a temporary automatic disable after repeated failures.
→ See Session Hooks in the Sessions guide
Memory
A memory store is a per-workspace, named collection of text items that agents read and write through built-in tools, so conventions and decisions persist across sessions.
→ See Memory guide
IDE Integration
IDE integration moves Develop-session work between the server and a developer's local clone: Open in IDE, Upload from IDE, and Pull from IDE (Remote), using single-use tokens that expire after 5 minutes.
→ See IDE Integration in the Sessions guide
Session host and Session Worker
A session host is a machine that runs agent sessions: the server itself (enabled by default) and any number of Session Workers. Each host has its own concurrency limits, optional workspace allowlist, and approval state on the Hosts page.
→ See Installation → Add a Session Worker
Deployment Worker
A Deployment Worker runs slots: long-lived preview deployments of a session branch or a group of ticket branches, controlled by a workspace deploy template. Every slot requires a connected worker.
→ See Deployment Worker guide
Working copy (worktree)
Every session, plan, round table, and merge request works in an isolated Git working copy under the host's storage path. Develop copies are released when the session completes (or preserved for a limited time when they hold unpushed work); Chat copies persist and are shared by Chat sessions with the same branch selection.
→ See Storage → Cleanup
Permissions
Role-based permissions decide what a user can do and workspace membership decides where. Administrators bypass permission checks, and the first user to sign in becomes an administrator.
→ See Permissions guide
Real-time updates
Session, ticket, and workspace changes appear automatically for connected users over a persistent connection. If updates stop or lag, verify that the reverse proxy passes WebSocket upgrades and does not time out idle connections.
→ See Installation → Reverse proxy notes
MCP Server
The built-in MCP endpoint gives agents approved Polygent tools such as ticket search, memory, and user questions. Each agent run gets a temporary credential bound to its identity, session, workspace, and granted tools. Administrators can also register external MCP servers.
→ See MCP Server guide
Merge Conflicts
When delivering a ticket or session hits conflicts, Polygent opens a merge request for that repository, tries an AI resolution (up to 30 minutes per attempt by default), and has a person review the result in a diff editor before pushing. Clean merges are committed and pushed automatically.
→ See Merge Conflicts guide
External integrations
| Integration | Capabilities |
|---|---|
| GitHub | Issue sync and creation, pull-request creation and status tracking |
| Azure DevOps / TFS | Work-item sync (all types), Bug creation, area-path and tag filters, stage-to-state sync, pull requests |
| Git | Clone, fetch, push, and pull over HTTPS with per-repository tokens |
Azure DevOps also supports personal tokens per user and workspace, managed under Profile → TFS Tokens.
Statistics
The Statistics dashboard reports sessions, tickets (throughput, cycle time, QA rejection rate), bots, workflows, insights, cost and tokens, user activity, session performance, guard events, and hook tasks, filtered by workspace and date range.
→ See Statistics guide
AI cost budget
Budgets cap recorded model spend in USD at three independent scopes: global monthly, per-workspace monthly, and per ticket. A warning is sent at a configurable threshold (80% by default), and a run that reaches a configured limit is stopped.
→ See AI Cost Budgets guide
My Work and notifications
My Work is the sidebar list of your active sessions, plans, round tables, tickets awaiting your action, and notifications, with full history on the My Work page. Notifications go only to the people responsible for an event, with optional browser notifications.
→ See Notifications & My Work guide
User authentication
Users sign in through Google, Microsoft, or any OpenID Connect provider. Polygent then issues short-lived access tokens (15 minutes) and rotating 7-day refresh tokens in secure, HttpOnly cookies.
→ See Authentication