Polymath Zero

Docs

Comment-triggered Work

Type an actionable comment in the Zero editor and Zero surfaces an inline approval offer. Nothing runs until you approve.

How it works

While editing a file in Zero, the editor scans the current line as you type. If the line is a comment in a supported language and the comment text starts with an actionable phrase, an inline tooltip appears:

// fix the auth timeout on refresh
                   ┌──────────────────────────────────────┐
                   │ Hmm.. let me take over..  [Approve] [Decline] │
                   └──────────────────────────────────────┘

If you click Approve, Zero creates a Work item using the comment text as the bounded intent, spawns an agent, and starts a session. If you click Decline or ignore the offer, nothing happens.

Approval-first. No agent starts, no file changes, no Work item is created until you explicitly click Approve. The tooltip is an offer, not a trigger.

Trigger phrases

The comment text (after stripping the comment syntax) must start with one of these phrases to surface an offer:

PhraseExample
fix// fix the auth timeout on refresh
refactor// refactor this to use atomic CAS
improve// improve error messages here
optimize / optimise# optimize this query
investigate// investigate why this races
explain// explain what this loop does
simplify// simplify this branching
add// add retry logic here
make// make this idempotent
find// find where this leaks memory
review// review this section
clean up// clean up this state machine
help me// help me understand this diff
please// please fix the type error below

Comment text must be at least 8 characters (after stripping the prefix).

Ignored patterns

These comment patterns are explicitly excluded and never surface an offer:

  • TODO: — task annotations
  • FIXME: — legacy fixme markers
  • NOTE: — informational notes
  • eslint-disable / eslint-enable — linter directives
  • prettier-ignore — formatter directives
  • Copyright — license headers

Supported languages

LanguageLine commentBlock comment
TypeScript / JavaScript///* … */
Rust///* … */
Python#—
Shell#—
YAML#—
HTML—<!-- … -->
Markdown—<!-- … -->
CSS—/* … */

Approval and Work creation

When you click Approve:

  1. Zero creates a Work item with the comment text as the title and intent.
  2. The active file path, language, line number, and surrounding context (±6 lines) are attached to the Work item.
  3. An agent is spawned via POST /agents with the comment as a prompt override.
  4. A session starts in Plan mode — the agent forms a hypothesis and plan for operator review before any code executes.
The comment becomes bounded Work. The agent runs in Plan mode first — you still review and approve the plan before execution begins.

Dismissed and approved state

Zero tracks which offers you've dismissed or approved using a stable fingerprint (project ID + file path + normalized comment text). Dismissed offers do not reappear for the same comment. Approved offers are also recorded so the same comment does not offer again.

State is stored locally in localStorage under:

  • zero.editor.takeover.dismissed
  • zero.editor.takeover.approved