Sessions

A session is one AI run, isolated in its own Git worktree. Sessions are the heart of Polygent — every developer task, ticket implementation, bot conversation, and workflow execution happens inside a session.

Session modes

Mode	Worktree	Use case
Chat	Persistent	Ongoing conversation, repo Q&A, no expectation of Done
Develop	Ephemeral	Task-focused work that closes when done — implementations, bug fixes
Bot	Persistent	Bot-driven conversation, scoped to a workspace bot

Lifecycle

Status	Meaning
Waiting	Idle — waiting for user input
In Progress	Agent is actively working
Done	Completed successfully
Canceled	Aborted by user

The session also supports Reset Context (clear the agent's conversation history without ending the session) and Server Restart Recovery (in-flight sessions resume on server boot).

Creating a session

1. Click New Session from the sidebar or workspace view
2. Choose:
   • Mode — Chat, Develop, or Bot
   • Provider — Polygent Code, Claude Code, Gemini CLI, OpenCode, Kilo CLI, Codex, Qwen Code
   • Model — provider-specific
   • Branch — base branch for the worktree
3. Enter a prompt or initial message
4. Optionally attach files or configure session toggles
5. Start

Pinning your favorite actions

The New popup lets you pin the actions and bots you use most. Hover any card and click the pin badge on its top-right corner to pin it — pinned items jump to a Pinned section at the top of the popup, and also appear as one-click quick-launch buttons in the My Work section of the sidebar so you can start them without opening the popup. Drag pinned items to reorder them in either place; the order is shared. Pins and their order are saved to your account, so they follow you across devices.

Examples

Ship a small feature start-to-finish Start a Develop session on a new branch, in Manual mode for the first message so you can sanity-check the agent's plan, then switch to Auto to let it finish. Watch the inline tool display for each edit, review the diff in the Git tab, commit, and push — all without leaving the browser.

Ask questions about the codebase Open a Chat session (persistent worktree) and ask "where do we validate uploaded files?" Use @ to mention a file for precision. The agent reads and searches the repo and answers — no changes are made, and the conversation stays around for follow-ups.

Loop until the tests pass On a Develop session, run a Ralph Loop with the prompt "fix the failing tests" and Stop on EXIT_SIGNAL enabled. Each iteration starts from a clean context; the loop stops automatically once tests pass, the agent signals done, or no further changes are made.

Drop into your local IDE for tricky debugging Use Open in IDE to pull the session's worktree onto your laptop, debug in your editor, commit and push, then Pull from Remote to bring your commits back into the session — the agent continues from your changes.

Guard quality automatically Enable the Code Review and Verification toggles when starting the session. After the agent finishes, Polygent runs an automated review for bugs/security and a completeness check against the task — findings appear in the sidebar without you asking.

Wire build/test into every run Configure session hooks: install dependencies on init, run the test suite when the agent finishes, and lint before the session is marked Done. The agent never has to be told — the scripts run on the right lifecycle events every time.

Development modes

Mode	Behavior
Manual	You approve each agent step — full control
Auto	Agent runs autonomously until done

Switch modes mid-session if you want to pause or release control.

Session mode toggles

Per-session toggles tell the agent which behaviors to apply:

• Code Architecture — apply architectural review patterns
• UX Enhancement — apply UX guidelines
• Edge Cases — explicitly enumerate edge cases
• Code Review — run automated code review (see Code Review)
• Verification — run task-completion verification (see Verification)
• Update Tests — author/update tests as part of the change
• Update Docs — author/update docs as part of the change

These toggles flow into the agent's system prompt so the same session prompt produces different rigor levels.

Messages

The conversation surface inside a session:

• Send Message — type and send
• Edit Message — edit your own messages (re-runs from that point)
• Delete Message — remove your message
• Cancel Working Message — stop the agent mid-response
• Attachments — files, images, PDFs sent with messages
• Message Actions Metadata — interactive actions like Create Ticket, Ask Question, Create Plan
• File Mention Autocomplete — type @ to mention a file with precision
• Follow-up Message Queue — messages sent while the agent is busy auto-deliver on idle
• Model Steering — nudge the agent with a real-time guidance hint while it's still working, without waiting for it to finish (Polygent Code)

Message types

Type	Source
System	Polygent or hooks
User	You
Agent	The AI
Tool	Tool use (file edits, bash commands)
Hook Failure	A hook task failed
Thinking	Agent's internal reasoning
Summary	Auto-generated digest

Message status

Pending, Working, Done, Failed, Canceled. Token and cost usage is audited per message.

Message actions

Polygent recognizes special action blocks the agent emits in chat:

• create-ticket — inline ticket creation or link to existing ticket
• ask-question — predefined options with an "other" text field
• create-plan — launch a plan with auto-filled description

These render as interactive UI inside the message, not just text.

Slash commands and skills

Type / in the message box to open an autocomplete picker for commands and skills defined for the active agent. Results are cached for fast lookups.

File operations

Each session has a built-in file workspace:

• File Tree Browser
• Monaco Editor — full browser-based editor
• Create File / Create Folder
• Rename / Delete
• Content Search — search file content across the worktree
• Recent Files — your 15 most recently opened files

Git operations

The session sidebar exposes Git directly:

Operation	Modes
Status	Full (with remote tracking) or quick
Stage	File / multiple / all
Unstage	File / multiple / all
Discard	File / multiple / all
Commit	Custom message
Push	To origin
Pull Remote	Fetch + ff-merge
Pull Specific Branch	Pull from a non-tracking branch
Merge to Starter Branch	Merge the worktree branch back to the workspace's starter branch
Pull from Starter Branch	Update the worktree with starter changes

Tool display

When the agent uses tools, Polygent renders them inline:

• Read — click to open the file
• Write — click to open the file
• Edit — click to open a diff view
• Before/After Diff Panels for any file change
• Bash — status indicators (running, success, fail)
• Task Agent Hierarchy — nested spawned agents shown as a tree

Sidebar tabs

Tab	Purpose
Session Info	Metadata and config
Files	File tree and editor
Search	Content search
Git	Git operations
Tasks	Workspace task runner
Hook Logs	Hook execution history (see Session Hooks)
Context	Token usage, file changes tracking, context reset
Session Insights	Auto-extracted insights for this session (see Insights guide)
Code Review	Review history (see Code Review)
Verification	Verification history (see Verification)

Session presence

While viewing a session, the session shows who is currently watching live. Presence updates automatically as users open and close the session.

Context tracking

• Token Usage Display — running cost
• Context-Window Indicator — on Develop sessions, a compact bar in the Session info panel (below the Ticket row, above More details) shows how full the model's context window is (used / limit tokens and a percentage), updating live as the agent works. It turns amber past 80% and red once the window is full
• File Changes Tracking — what's modified
• Context Reset — wipe agent history without ending the session

Keyboard shortcuts

Shortcut	Action
Ctrl+P	Quick Open file
Ctrl+Shift+F	Content search
Ctrl+Shift+X	Open Context tab
@	File mention
/	Slash commands picker

Bulk actions

From the sessions list:

• Bulk Hide — hide many sessions from the sidebar
• Bulk Cancel — cancel many at once
• Bulk Complete — mark many Done

Ticket progress bar

Sessions tied to tickets show a progress bar based on completed versus total workflow steps, with interpolated progress between ticket and workflow stages.

Session pinning

Pin sessions to keep them at the top of your sidebar. Pin state is per-user with optimistic UI updates.

Workflow execution

When a workflow is running inside a session:

• Start Workflow with parameters
• Manual / Auto Advance between steps
• Cancel Active Workflow
• Toggle Auto-Advance mid-run

Task execution

Run workspace tasks directly from a session:

• Start Task / Stop Task
• Task Output Streaming — live output
• Task Status — Pending / Running / Completed / Failed / Canceled

Deploy to slot

From any Develop session, Deploy to Slot pushes the session's branch onto a deployment agent slot. See the Deployment Agent guide.

Total cost display

The session header shows aggregate USD cost across every message and tool call — handy for spotting expensive sessions.

Filtering the sessions list

Filter the sidebar / sessions list by:

• Status — Active, Completed
• Mode — Chat, Develop, Bot
• Workspace
• User
• Bot
• Search by name

Ralph Loop

Ralph Loop is iterative refinement on a single session: re-run the same prompt across context resets until the agent succeeds, fails, or stops on its own. It's the right tool for "loop until tests pass", "loop until the spec is complete", or "keep refining this answer".

How it works

1. Send the loop prompt to the session
2. The agent works one iteration with a fresh context (no history beyond the prompt itself, when context reset is enabled)
3. The agent is made aware of which iteration it's on
4. After the iteration finishes, the loop continues or stops based on your configured stop conditions
5. Between iterations, the session context is reset so each iteration starts clean — unless Reset context on new iteration is disabled, in which case the agent keeps the full conversation history

The first iteration runs in a fresh session — no reset needed.

Configuration

Setting	Description
Prompt	The task to repeat (max 10,000 chars)
Max Iterations	Hard cap, 1–1000
Model Override	Optional alternative model for loop iterations
Stop on EXIT_SIGNAL	Stop early when the agent emits EXIT_SIGNAL: true (recommended)
Reset context on new iteration	When enabled (default), clears conversation history each iteration; when disabled, history is kept

Stop conditions

The loop ends when any of these occur:

• Max Iterations reached
• User Stop — clicking Stop deletes the loop row and ends immediately
• Agent emits EXIT_SIGNAL: true — when the toggle is enabled, this is how the agent says "done"
• No Git changes after first iteration — prevents pointless looping when the agent has converged
• Session terminal — Done or Canceled

Per-iteration UI

While the loop runs, the session shows an iteration badge so you can see which round is active. Live updates arrive automatically — no manual refresh needed.

Workflow integration

Ralph Loop is also available as a Ralph Loop workflow step. Use it inside a multi-step procedure when one stage needs iterative refinement, e.g.:

1. Generate a failing test → Message step
2. Implement until tests pass → Ralph Loop step
3. Verify → Message step

Concurrency

A per-session lock ensures only one Ralph Loop runs per session at a time. Attempts to start a second loop on the same session return an error.

Sidebar panel

Sessions with an active or completed loop show a Ralph Loop panel with:

• Current iteration / max
• Last iteration outcome
• Stop reason once finished
• Cancel button while running

When to use it

• The agent's first attempt is rarely perfect (e.g., flaky tests, partial fixes)
• You have a hard success signal — tests passing, lint clean, output matching a schema
• The task converges with each iteration rather than diverging

When to avoid it

• The task is open-ended without a clear stop signal — pick a workflow with explicit gates instead
• You need different prompts per iteration — that's a workflow, not a loop

IDE Integration

Open any session in your local IDE with a one-liner script, push uncommitted changes back to the server, or pull from your local Git remote into the session worktree. IDE integration is the bridge between Polygent's web interface and your everyday editing tools.

Three operations

Operation	Direction	Use it when
Open in IDE	Server → Local	You want to edit the session's worktree on your laptop
Pull from IDE via Remote	Local → Server (Git)	You committed and pushed locally; pull those commits into the session
Upload Uncommitted from IDE	Local → Server (zip)	You have uncommitted changes locally and want to ship them up

Where to find it

IDE bridge actions live in the Session sidebar tab, inside the Actions section, as a dedicated sub-block titled "Continue this session in your local IDE". The block contains three labeled buttons: Open in IDE, Upload from IDE, and Pull from IDE (Remote).

The block is hidden in Chat mode (no worktree to bridge) and in read-only sessions. The Git sidebar's pull dropdown only exposes the two true pull operations (Pull from Remote, Pull from Starter Branch); IDE-specific actions are no longer buried behind icons in the git toolbar.

Open in IDE

From the Session sidebar's Actions section, click Open in IDE. Polygent shows a modal with two scripts:

• Bash one-liner (macOS/Linux/WSL/Git Bash)
• PowerShell one-liner (Windows)

Run the one-liner in your local terminal. It:

1. Mints a 5-minute single-use Open Token
2. Downloads a zip of the session worktree
3. Extracts it locally
4. Opens the directory in your IDE

You now have the session's code on disk for inspection or editing.

Pull from IDE via Remote

If you've committed your local edits and pushed to your Git remote, the server can pull them straight into the worktree:

1. Locally: git push to your remote (the worktree's tracking branch)
2. In Polygent: click Pull from IDE (Remote) in the Session sidebar's Actions section
3. The server runs git fetch and git merge --ff-only

This is the cleanest path — works with any IDE, any commit history, no zip transfer.

Upload Uncommitted from IDE

When you don't want to commit yet but still need the changes on the server, use the upload flow:

1. Click Upload from IDE in the Session sidebar's Actions section to open the modal with a Bash or PowerShell one-liner
2. Run the one-liner locally
3. The script collects uncommitted changes and uploads them as a zip
4. Polygent confirms before applying — the worktree must be dirty (you'll see a confirmation prompt)
5. Changes are applied to the session worktree

This uses a separate 5-minute single-use Upload Token to authenticate the upload.

Session feedback

On a successful download or upload, Polygent posts a system message to the session chat summarizing the operation (for example: IDE: downloaded session changes (3 files, 1 deletion).). This gives everyone watching the session a clear audit trail of when the worktree was bridged to or from a local IDE.

Messaging failures are swallowed silently — an outage in chat will never break the IDE bridge operation itself. No system message is posted when the operation fails or is canceled.

Token security

Each operation uses a short-lived, single-use token (5-minute TTL) bound to the specific session and operation type. Open tokens cannot be used to upload, and vice versa. Tokens are generated from your authenticated browser session, so the one-liner script works without your login cookie.

Session Git lock

All mutating operations (apply uploaded changes, pull from remote) acquire the session Git lock to prevent races with the agent. If the session is mid-mutation, the operation queues until the lock is free.

Chat mode rejection

IDE integration is intended for Develop sessions — Chat sessions reject these operations. Chat sessions are conversational, with no expectation of being a working tree you'd open elsewhere.

When to use which path

• Read-only inspection → Open in IDE (download)
• Quick experimental edits → Open in IDE → Upload Uncommitted
• Commits with proper history → Open in IDE → commit locally → push → Pull from Remote
• Adding tests / debugging → Pull from Remote (after committing locally)

Session Hooks

Session hooks run user-defined tasks at specific lifecycle events of a session — install dependencies on init, run tests when the agent finishes, push artifacts on done. Hooks are how you wire build/test/lint scripts into every session without telling the agent to do it.

Hook events

Event	Fires when
On Init	The session is created and the worktree is being prepared
On Start	The session transitions to In Progress
On Agent Finish	The agent finishes a turn (In Progress → Waiting)
On Done	The session reaches Done
On Cancel	The session is canceled

Each event can be enabled/disabled independently per workspace.

Task configuration

For each event, configure the tasks to run:

Setting	Description
Reference Workspace Tasks	Use named tasks defined at the workspace level
Inline Scripts	Provide a script directly on the hook
Custom Name	Display name for the hook
Agent Provider	Which provider runs the hook task
Stop on Failure	Halt the chain if this task fails
Max Retries	0–10 retries before reporting failure
Timeout	1–3600 seconds
Send Failed Output as Message	None, Truncated, Full, or Command Only — what to inject into the chat on failure
File Changed Filter	Gitignore-style glob; the hook only runs if matching files changed

Conditional execution

Restrict when a hook fires:

• Branch Filter — glob patterns matched against the starter branch (e.g., main, release/*)
• Disable for Tickets — skip the hook when the session was started by a ticket
• Disable for Automations — skip the hook when the session was started by an automation

Use these to keep CI-like hooks from running on every chat session.

Execution status

Each hook task progresses through:

Status	Meaning
Pending	Queued
Running	Executing
Completed	Finished without error
Failed	Threw an error or exceeded timeout

The Hook Logs sidebar tab shows the live status, command output, exit code, and duration for every hook execution.

Circuit breaker

If a hook fails repeatedly across sessions, Polygent temporarily disables it for that workspace. This prevents one broken hook from blocking the whole team. The circuit auto-resets after a short cool-off period or when the hook config changes.

onDone agent-assisted retry

When an On Done hook fails, Polygent can re-engage the agent: the failure output is sent as a message back into the session, the session re-opens (In Progress), and the agent gets a chance to fix the failure (e.g., a failing test) before re-running the hook. Only one such retry runs at a time per session.

Hook cancellation

You can cancel a running hook from the UI. The cancellation flows through to the task process and marks the hook as failed with a canceled reason.

Chat mode exclusion

Hooks do not run for Chat-mode sessions by default. Chat sessions are interactive Q&A — running build/test scripts on every message would be noise. Develop sessions, ticket sessions, and automations all run hooks normally.

Common patterns

Install dependencies on init

• Event: On Init
• Task: install your project's dependencies (whatever your repo uses, e.g., npm ci, pip install -r requirements.txt)

Run tests when agent finishes

• Event: On Agent Finish
• Task: run test suite
• Send Failed Output: Truncated
• Stop on Failure: yes

Lint and type-check before done

• Event: On Done
• Tasks: run linter, run type checker
• Send Failed Output: Full
• Enables the On Done agent-assisted retry to let the agent fix issues

Cleanup on cancel

• Event: On Cancel
• Task: kill running dev servers, drop temp files

Configuration location

Configure hooks under Workspace Settings → Session Hooks. The configuration is per-workspace, but individual hooks can be globally disabled via the per-event toggle.

Code Review

Polygent runs an AI-powered code review automatically when a session agent finishes work. The review analyzes the session's Git diff for bugs, performance issues, security vulnerabilities, and code-quality problems, then surfaces the findings inline in the session sidebar.

How it works

1. The agent finishes a Develop session (In Progress → Waiting transition)
2. Polygent collects the full diff of the session worktree, including untracked files
3. The diff is sent to the configured review provider/model
4. Issues are returned with category and severity, capped at 20 per review
5. Results are saved as history — re-runs after QA rejection produce a new review without overwriting the previous one
6. The sidebar updates live — no refresh needed

A system message is posted to the session chat summarizing the result (e.g., "Code review passed", "Code review found 3 issues", "Code review failed").

Issue categories and severity

Each issue carries:

• Category — Bug, Performance, Security, Code Quality, etc.
• Severity — Critical, High, Medium, Low. Issues are ordered critical-first.

Configuration

Global settings

In Settings → Code Review:

Setting	Description
Enabled	Global on/off toggle
Provider	AI provider used for review (e.g., Claude Code)
Model	Specific model the provider should use

Per-workspace prompt

Open a workspace, go to the Prompts tab, and set a Code Review System Prompt (max 10,000 chars). It is appended to the base extraction prompt for that workspace's reviews — useful for project-specific conventions or files to ignore.

Per-session skip

Toggle Skip Code Review on a session if you want to bypass the review for one specific run (e.g., docs-only changes). The flag is preserved on the session record.

Session Mode Toggle

Code Review is one of the Session Mode Toggles available on every session and ticket — alongside Code Architecture, UX Enhancement, Edge Cases, Verification, Update Tests, and Update Docs. Disabling the Code Review toggle on a session/ticket has the same effect as Skip Code Review for that run. The toggle is also available on Start Ticket Templates and Automations.

Sidebar tab

The Code Review tab in the session sidebar shows the review history:

• Newest review first, all prior reviews retained
• Status badges: Pending, Running, Completed, Failed, Canceled
• Issues are lazy-loaded when you expand a review
• A Cancel button is available while a review is Pending or Running

The tab is visible for Develop sessions in Waiting, In Progress, or Done status.

When reviews fire and when they skip

A review is triggered only when all of these are true:

• Code review is enabled in global settings
• The session is a Develop session (Chat sessions are excluded)
• Skip Code Review is not set on the session
• No review is currently Pending or Running for this session
• The session worktree has actual file changes vs. HEAD

Reviews wait for any in-flight Verification to finish before starting.

Limits and timeouts

• Concurrency: one review per session at a time
• Timeout: up to 30 minutes total per review
• Max issues: 20 per review

If extraction fails, the review is marked Failed with a generic message; raw exception details are logged server-side only.

Verification

Verification is post-agent task-completion checking. After a Develop session's agent finishes, an AI verifier analyzes the Git diff against the original task description and reports anything missing — incomplete features, missing tests, missing error handling, incorrect behavior. It runs as a non-blocking background process and preserves full audit history per session.

Verification is a sibling to Code Review. Code review focuses on quality of the changes; verification focuses on completeness vs. the task.

How it works

1. The agent finishes a Develop session (In Progress → Waiting)
2. Polygent collects the session's task description and Git diff
3. The diff and task are sent to the verification AI provider/model
4. The AI returns categorized issues — what's missing or incorrect vs. the task
5. Issues are saved as history; re-runs after rework produce a new verification record

A status badge appears inline in the session chat plus a dedicated Verification sidebar tab.

Issue categories

Category	Meaning
Missing Feature	Required behavior was not implemented
Incomplete Implementation	Partial implementation, gaps in logic
Incorrect Behavior	Implementation does not match the task
Missing Edge Case	An edge case identified by the verifier is unhandled
Missing Test	Tests for the change were not added
Missing Error Handling	Error paths were left unhandled
Other	Anything else

Verification status

Status	Meaning
Pending	Queued
Running	Verifier is executing
Completed	Done — issues (if any) are listed
Failed	Extraction error
Skipped	Skipped by config or per-session toggle
Canceled	User canceled the run

Configuration

Global settings

In Settings → Verification:

• Enabled — toggle the feature globally
• Provider — AI provider used for verification
• Model — specific model

Per-workspace prompt

Each workspace can define a Verification System Prompt (under workspace Prompts tab) appended to the base verification prompt — useful for project-specific requirements.

Per-session skip

Toggle Skip Verification on a session to bypass verification for that one run.

Session Mode Toggle

Verification is one of the Session Mode Toggles on sessions and tickets — alongside Code Architecture, UX Enhancement, Edge Cases, Code Review, Update Tests, and Update Docs. Turning the Verification toggle off on a session/ticket has the same effect as Skip Verification for that run. The toggle is also exposed on Start Ticket Templates and Automations.

Live updates are pushed automatically so the sidebar tab and inline status reflect run progress without a refresh.

Sidebar tab

The Verification sidebar tab shows the run history:

• Newest verification first, prior runs preserved
• Status badges and per-issue category
• Cost and duration per run
• Cancel button while Pending/Running
• Issues are lazy-loaded on expand

Inline status

A compact status indicator appears in the session chat so you can see verification progress without opening the sidebar.

When verification fires

A run is triggered when:

• Verification is enabled in settings
• The session is a Develop session
• Skip Verification is not set on the session
• The session worktree has actual file changes

If both Code Review and Verification are enabled, verification runs first; code review waits for verification to finish before starting.

Limits

• One verification per session at a time
• Up to 30 minutes per run
• Max 20 issues per run
• A failed extraction posts a generic error message; raw exception details are logged server-side only

Why have both verification and code review?

Code review and verification answer different questions:

Question	Tool
"Is this code well-written?"	Code Review
"Did this code do what was asked?"	Verification

Together they catch both quality issues (security, perf, bugs) and completeness issues (missed features, missing tests). Either can be disabled independently if you don't need both.