Documentation

How Polynomic works

Polynomic is a local-first, keyboard-first task manager for the agentic coding age. You manage Tasks; coding agents do the work behind them. A Task spans your repos, references the exact code it touches, runs an Agent Session to implement itself, and produces a reviewable diff before anything merges. This page explains the model and the loop end to end.

Core concepts

Six terms carry the whole model. Learn these and the rest of the app reads naturally.

Task

The unit of work, and the thing you actually manage. A complete development cycle — capture, plan, start, implement, review, merge — oriented around the work itself, not the agent that does it.

Ledger

A local, append-only SQLite record. Every status change, comment, edit, and code reference is an immutable Event; current state is a projection folded from the Ledger and rebuildable at any time.

Agent Session

How a Task gets worked: a real `claude` process spawned in an embedded terminal, scoped to the Task over a loopback MCP server. The agent is an implementation detail behind the Task.

Workspace

When you Start a Task, Polynomic lays down one git worktree + branch per touched Repo side by side, so an agent gets full cross-repo context in a single isolated place.

Code Reference

A pointer into source at file granularity, entered with @-syntax. References resolve live and are marked stale when their target moves, so a Task always knows the code it concerns.

Review

Every Task produces a reviewable per-repo branch diff. An independent AI Review session reads it and posts comments — it never changes state or merges. You decide what lands.

Getting started

Polynomic is a macOS desktop app. It drives the claude CLI for Agent Sessions, so you'll want it installed and on your PATH — Polynomic detects it on startup and disables Start with a banner if it's missing.

1. 1

   Install Polynomic

   Download the universal .dmg, drag Polynomic into Applications, and open it. See the install page for first-launch notes on unsigned builds.

2. 2

   Create a Project

   A Project points at one or more existing local git repos — Polynomic validates them and detects the default branch, but never clones. Give it a short key like POL; Tasks become POL-1, POL-2, and so on.

3. 3

   Capture Tasks

   Press c to create a Task, or open the command palette with ⌘K. Seed sample data any time with ⌘K → “Seed demo tasks” to explore the views.

4. 4

   Start a Task

   Open a Task and press x to Start it. Polynomic builds a Workspace, spawns an Agent Session, and streams its terminal so you can watch — or console in.

5. 5

   Review and merge

   When the session finishes you get a per-repo branch diff and an AI Review. Request changes, run an AI Fix, or merge — all from the keyboard.

Tasks & states

A Task is an event ledger, not a row you mutate. Every change — status, comments, edits, code refs — is an immutable Event, and the state you see is a projection folded from those events. A Task moves through a small, fixed set of states:

View Tasks as a List or a Board (kanban, drag-to-change-state), and organize them with initiatives, labels, priority, and assignee — all filterable from the sidebar. The signature Code-Tree view rolls up Task counts per file and directory, so you can filter the list by the part of the system the work touches.

Code References

Reference code from a Task with @repo/path syntax — autocompleted over git ls-files. References resolve live and are marked stale when their target moves, so a Task always points at real code. This is what lets the Code-Tree view exist, and what gives an Agent Session the exact files the work concerns.

Today references are file-level; symbol-level granularity and @-mentions in comments are on the roadmap.

Agent Sessions

Starting a Task builds a Workspace — a git worktree and a polynomic/<id>-<slug> branch per touched repo — then spawns a real claude process in an embedded terminal you can watch or type into. Sessions are resumable, and orphans are reconciled when you reopen a project.

The agent talks to Polynomic over a loopback MCP server, scoped to its Task by a token. It can read and update the Task — but it only signals; Polynomic verifies against real commits before transitioning. A hollow “done” with no commits routes to Needs Attention instead of Done. The agent's tool surface:

• get_task
• add_comment
• update_status
• add_code_reference
• report_needs_attention
• create_subtask

Tool permissions

An Agent Session can read, edit, and run commands on your behalf — so anything with side effects asks first. When the agent wants to use a tool that needs your sign-off, the request queues quietly rather than interrupting you. Press a from anywhere to open the Tool Approvals center and decide. The notification center flags any task that's waiting, so nothing blocks silently.

The approval center

The center is a triage surface, not a one-shot popup. A left rail lists every pending request — tool name, the Task it belongs to, and the command, path, or URL at a glance. The right pane shows the full tool input and the working directory it would run in, so you can see exactly what's about to happen before you decide.

npm install

Three decisions

Every request resolves to one of three answers. The whole center is keyboard-driven: j / k move through the queue, then act on the selected request.

• Allow a / ⏎ — Permit this one call. The agent unblocks immediately and keeps working.

• Allow always ⇧A — Permit this call and remember the decision, so matching calls auto-allow for the rest of the session without prompting again. Bash grants are scoped to the program (allowing npm install allows all npm commands), and the file-editing tools share one grant.

• Deny d — Reject the call. The agent gets the refusal and either tries another approach or routes the Task to Needs Attention.

Closing the center with Esc leaves requests queued — it doesn't answer them — so you can come back to them later. Summon it again any time with a, even when nothing is pending; it just shows an all-clear.

What never asks

To keep the center signal-rich, read-only and clearly safe tools skip it entirely: file reads, searches, web search, and a small allow-list of read-only git commands (status, diff, log…) run without a prompt. Anything you've already allow-listed in your Claude settings (~/.claude/settings.json or a repo's .claude/settings.json) is honored too. If you ignore a request long enough, it falls back to the agent's own permission prompt in the embedded terminal — so a request is never lost, just waiting on you.

Tool approvals keep you in the loop, but they're also a leash: every Bash, Edit, and Write blocks until someone clicks. To run agents truly unattended — dozens in parallel, overnight — Polynomic can instead wrap each Agent Session in an OS-enforced sandbox and let it run with --dangerously-skip-permissions. The boundary is drawn by macOS itself, not by a prompt you have to answer.

A Workspace already isolates an agent's files from your real checkout. Native isolation extends that to the whole session — filesystem, network, and child processes — so a misbehaving agent can't read your ~/.ssh, reach arbitrary hosts, or touch anything outside its worktree, even with permissions skipped.

Two runtimes, chosen per Project

Turn it on per Project with a Sandbox toggle (off by default while in beta). Once on, Polynomic picks the isolation runtime based on whether the Project declares an agent image:

Seatbelt sandbox

The default. Wraps the entire claude process — every tool, hook, and MCP server it spawns — in a macOS Seatbelt sandbox via @anthropic-ai/sandbox-runtime. Process-level isolation that runs on any macOS with no extra install, and keeps the agent on your real toolchain and ~/.claude.json.

Apple container

The stronger boundary. Runs the agent inside a lightweight Linux VM per session via Apple's container CLI (Virtualization.framework) — kernel-level isolation. Used when a Project names a Linux agent image. Requires Apple Silicon + macOS 26+; the worktree mounts in and the MCP server is reached over the host gateway.

How the runtime is selected

1. 1

   Sandbox off → no sandbox. The Agent Session runs as today, with Tool Approvals gating every side effect.

2. 2

   Sandbox on + an agent image declared + the container CLI available → Apple container, the VM boundary.

3. 3

   Sandbox on, but no image (or container unavailable) → the Seatbelt sandbox-runtime, the universal path.

4. 4

   Neither runtime available → Polynomic degrades gracefully to an unsandboxed session rather than failing.

What the sandbox allows

For the Seatbelt runtime, Polynomic generates a per-session settings file that allow-lists exactly what the agent needs and denies the rest:

What changes when it's on

• No approval prompts. The OS boundary replaces the dialog. Sandboxed sessions skip the Tool Approvals center entirely and run start-to-finish without a click.

• Lifecycle hooks stay. Only lightweight hooks remain — auto-advance when the agent stops, and plan approval for plan-mode tasks. The broad approve-everything hook is gone.

• Same Task, same Review. Everything downstream is unchanged: the session still lands commits on its branch, Polynomic still verifies real changes, and you still review the diff before it merges.

• Cleaned up on stop. Per-session sandbox artifacts are removed when the session ends. Discovery of npx and container is cached, like claude and gh.

Native isolation is in beta and off by default. The Seatbelt runtime is process-level, not a full VM — for the strongest separation, give a Project a Linux agent image and let it run under Apple container.

Review & merge

Nothing reaches your main branch until you've seen it. Every Task produces a per-repo branch diff with Review Comments you can anchor to a file and line. An independent AI Review — a fresh, headless /review session — reads the diff and posts comments. It never changes state or merges anything.

• Request changes. Send comments back and route the Task to a Changes state.

• AI Fix. Resume the original Agent Session with your comments so it addresses them in place.

• Guarded merge. Fetch → rebase → --no-ff merge, locally. Conflicts route to Needs Attention; on success the worktrees are cleaned up.

Keyboard shortcuts

Polynomic is keyboard-first: capture, start, review, and merge without reaching for the mouse. Press ? in the app for this list any time.

Data & storage

Everything is local. Your tasks, events, and code references live in SQLite — one Ledger database per Project — kept entirely separate from your git repos. No cloud dependency, no API keys, no seat fees. Your source stays in git; your task data stays separate; you own both.

~/.polynomic/
├── registry.db                  global project registry
├── projects/<project-id>/
│   └── polynomic.db              that project's event ledger + projections
└── workspaces/<task-id>/         one git worktree per touched repo

Override the root with POLYNOMIC_DATA_DIR. Projections are pure caches: an append writes the Event and re-folds the projection in one transaction, and the projections can be dropped and rebuilt from the Ledger at any time.

FAQ

Which platforms are supported?

macOS today, as a universal build for Apple Silicon and Intel. Windows and Linux are coming later.

Do I need the claude CLI?

Yes — Agent Sessions spawn the claude process. Polynomic detects it on startup and disables Start with a banner if it can't be found on your PATH.

Does Polynomic clone or push my repos?

No. A Project points at existing local repos, and merges are local git operations. There is no push in the current version.

Can a Task span multiple repos?

Yes. A Project can include several Repos, and a single Task can touch more than one — Polynomic lays a worktree of each side by side in one Workspace.

What happens if an agent claims it's done but didn't commit?

Polynomic verifies against real commits before transitioning. A hollow “done” routes to Needs Attention rather than Done.

How do I approve the commands an agent wants to run?

Press a to open the Tool Approvals center and Allow, Allow always, or Deny each pending request. Read-only tools and anything you've allow-listed in your Claude settings run without asking. See Tool permissions above.

Can agents run unattended without approving every step?

Yes — turn on native isolation per Project (beta). The Agent Session runs inside a macOS sandbox with --dangerously-skip-permissions, so the OS draws the boundary instead of a prompt. See Native isolation above.