Terse Planner

Nightly prerelease. This build is a release candidate for testing, not an official stable release.

Terse Planner is a VS Code extension that turns a short request into a validated implementation plan, keeps every effective route revision-bound and approval-gated, and executes dependency-ready tasks through explicit provider/model routes. Four distinct route roles — planning, Safety & Plan Review, commit-message generation, and execution — can independently use OpenAI Codex, Anthropic Claude, OpenRouter, or a compatible abliteration.ai model.

Getting started

When a workspace has no saved Plans or Execute sessions, the Plan view opens a guided welcome derived from the workspace's current readiness. It leads through the essentials in order: open a local folder, connect a provider, choose a Planning Default, and choose an Execution Default. Provider repair links directly to Settings → Global → Connections; route setup links to Settings → Workspace → Default routes. If readiness later regresses, a non-blocking repair banner keeps saved work visible while identifying the next connection-aware fixes.

After setup, choose the workflow that fits the work:

• Plan: create a plan, review its dependency board, approve the exact revision, then execute it with a separate Git commit for each successful task.
• Execute: work through repository-wide conversational turns without automatic Git commits.

Plan, review, and execute

Run Terse: New Plan in a trusted file workspace and enter a request. The planning route runs read-only and returns a dependency-ordered plan. Review it on the hybrid Kanban/dependency board, approve that exact revision, then execute dependency-ready tasks concurrently up to the configurable terse.executionConcurrency bound. Material task, scope, or route edits create a new revision and clear the approval, so the plan that runs is always the plan that was approved. For quick work that does not need planning, Execute is a persistent conversational agent session over the repository rather than a synthetic one-task plan.

The board opens in the sidebar and, with Terse: Open Plan Board in Editor, as an editor tab that stays in sync with it. Cards are keyboard-navigable with arrow keys, and every finished task lists its changed files with +N/−M chips and a Review all changes multi-file diff. The status bar carries a Terse: Quick Actions menu that reports what Terse is doing and opens the things you reach for; every command is documented in docs/commands.md.

The complete workflow — clarification rounds, salvaged drafts, Execute session binding and recovery, multiple plans, and scope-lock serialization — is documented in docs/plan-and-execute.md. The saved plan's command center, board, and progressive rendering bounds are documented in docs/presentation.md. Plan maturity review has exactly two modes, Manual and Autopilot, documented together with the permanently enforced revision approval gate in docs/tool-review.md.

Each successfully completed task is committed as an isolated Git transaction that reports a validated short hash, an explicit no-change state, or a failure that distinguishes whether a commit exists. Commit-message generation is a separate read-only feature that never commits. Both are documented in docs/git-integration.md.

Provider routes and settings

Use Terse: Sign In to a Provider to connect Codex through a ChatGPT subscription or an OpenAI API key, Claude through Claude.ai OAuth2 or an Anthropic Console key, OpenRouter, or abliteration.ai. Credentials are stored only in VS Code SecretStorage. Each of the four route roles binds an exact provider/model pair onto the plan revision it runs under, and the settings UI offers only the models the signed-in connection reports as compatible with that phase. The sign-in methods, compatibility rules, and permission and failure behavior are documented in docs/provider-routes.md; every contributed setting and its value sources are documented in docs/settings.md. The deterministic benchmark-informed per-task routing behind terse.taskOrchestration is documented in docs/orchestration.md.

Tool-call sandbox and review

Execution combines deterministic containment with a two-stage review. Operating-system write confinement is selected by functional probe from a pluggable backend registry — bubblewrap on Linux and Seatbelt on macOS — while the trusted execution adapter physically resolves paths and rejects workspace escape before review. Windows is unconfined by default; its unverified AppContainer backend is available only through the experimental TERSE_SANDBOX_WINDOWS=appcontainer opt-in. Shell commands do not claim an enumerated write set; the kernel boundary is what restricts writes to the enforced roots.

When host facts require judgment, a bounded gatherer may inspect the workspace with only read, glob, and grep and emits a sanitized brief. A separate tool-free, single-completion judge receives that brief, the approved intent, and deterministic evidence and returns the structured action-impact analysis. For the built-in descriptor-bound one-file write and edit tools, the host can supply that deterministic brief directly; the judge still runs. In Manual mode, uncleared requests reach a concise decision card with blocking concerns and key evidence visible and full detail in disclosures. In Autopilot, the same continuation gate is applied directly and every other outcome is rejected without a person prompt. Proven workspace escapes and malformed or stale live authorization remain non-overridable hard stops. The full policy is documented in docs/tool-review.md.

Provider-exposed activity, native search, and public web access

Plan and Execute share a bounded, redacted, paginated provider-exposed activity timeline, a secured web_fetch tool for public HTTP(S) retrieval with fixed SSRF-protected limits, and fail-closed provider-native web search where the route supports it. The native abliteration.ai adapter currently reports provider-native search as unsupported. All fetched pages, search results, and citations are untrusted data, never instructions. The complete trust and custody model is documented in docs/security-model.md.

Clipboard and attachment custody

Attachments are inert extension-owned bytes. Clipboard access happens only on an explicit paste, intake is bounded by per-item size, total bytes, and count with no type allowlist, actual bytes — never names or declared types — decide what reaches the model, and owned copies live under extension-managed global storage, never the repository. The complete custody model is documented in docs/security-model.md.

Documentation

The deep reference material lives under docs/:

• docs/commands.md — every contributed command, the keybindings, the status-bar quick-actions menu, and the plan board's editor tab.
• docs/plan-and-execute.md — the complete Plan and Execute workflow, multiple plans, and parallel execution.
• docs/presentation.md — the plan command center, board and Flow views, and progressive rendering at scale.
• docs/planning-hierarchy.md — the epic, milestone, subtask, and checklist contract and its validated limits.
• docs/tool-review.md — Manual and Autopilot review, operating-system containment, and the mode-independent continuation gate.
• docs/security-model.md — provider-exposed activity, public web access, credential custody, attachment custody, and refusal rollback.
• docs/provider-routes.md — supported sign-in methods, phase and model compatibility, and provider permissions and failures.
• docs/settings.md — every contributed setting, value sources, and transactional saves.
• docs/orchestration.md — the deterministic per-task routing policy, multiple accounts per platform, the refusal-only abliteration.ai transition, and durable planning drafts.
• docs/git-integration.md — per-task Git commits and commit-message generation.
• docs/state-and-recovery.md — where plans and Execute sessions are stored and what migration may reconstruct.
• docs/validation.md — the review-gated declared validation contract and its task evidence.
• docs/providers.md — the platform architecture and the contributor contract every provider plugin implements.
• docs/architecture-budgets.md — bundle layers and the module-size budgets the test suite enforces.
• docs/review-reliability.md — the root cause and checkpointed-handoff design for bounded Plan and tool review.
• docs/benchmark-snapshot.md — the offline maintainer workflow for refreshing the bundled benchmark snapshot.
• docs/smoke-checklist.md and docs/release-smoke-checklist.md — the manual installed-VSIX gates.
• docs/release-process.md — Forgejo validation and the nightly prerelease path.

Requirements

• The extension manifest requires VS Code ^1.96.0; the extension-host bundle targets ES2022. It names one Bun runtime API — Bun.spawn, in the Git command runner — behind a typeof Bun !== "undefined" guard that is false in every VS Code extension host, so the Node path is the one that runs there. Nothing in the bundle requires Bun to be installed.
• Bun 1.3.10 is the pinned CI and release-qualification toolchain.
• Credentials for the explicitly selected provider are required for live provider operations: Codex ChatGPT/OpenAI API access, a Claude.ai subscription or Anthropic Console API key, an OpenRouter API key, or an abliteration.ai API key.

Provider access uses direct API clients on the shared in-extension runtime.

One universal VSIX supports every VS Code platform and CPU architecture. It contains the extension and webview code, not provider CLIs or native provider runtimes. Install the same artifact locally or on a Remote SSH, WSL, or development-container extension host. “Universal” describes the packaged JavaScript artifact; automated behavioral qualification currently runs in a Linux container. macOS Seatbelt and Windows host behavior therefore still require the installed-VSIX checklist on those platforms before a stable release can claim them as qualified.

Install a published nightly

Published candidates appear on the Forgejo Releases page. Download the matching .vsix and .vsix.sha256 files, verify them in the same directory, then use the block for your shell. The checksum tool varies by host; all three blocks verify and install the same universal VSIX.

GNU/Linux:

VERSION=0.2.0-nightly.N # Replace with the version shown on the release.
sha256sum -c "terse-planner-$VERSION.vsix.sha256"
code --install-extension "terse-planner-$VERSION.vsix" --force

macOS:

VERSION=0.2.0-nightly.N # Replace with the version shown on the release.
shasum -a 256 -c "terse-planner-$VERSION.vsix.sha256"
code --install-extension "terse-planner-$VERSION.vsix" --force

PowerShell:

$Version = "0.2.0-nightly.N" # Replace with the version shown on the release.
$Vsix = "terse-planner-$Version.vsix"
$Expected = ((Get-Content "$Vsix.sha256" -Raw) -split '\s+')[0].ToLowerInvariant()
$Actual = (Get-FileHash -Path $Vsix -Algorithm SHA256).Hash.ToLowerInvariant()
if ($Actual -ne $Expected) { throw "SHA-256 mismatch for $Vsix" }
code --install-extension $Vsix --force

For Remote SSH, WSL, or a development container, use Extensions: Install from VSIX... in the connected window so VS Code installs it on that extension host, then reload the window. scripts/install-nightly.sh is intentionally a GNU/Linux-only Remote-SSH maintainer workflow that requires Bash and GNU userland; this maintainer-host restriction does not change universal VSIX support. It builds and installs a new local candidate rather than downloading the latest published release. Before running it, install the pinned tree with Bun 1.3.10 using exactly bun install --frozen-lockfile. The script fails before server discovery when that tree is absent or incomplete, holds a checkout-local lock through installed-version readback, and rejects a concurrent attempt before either one changes release metadata or shared build outputs.

Development

bun install --frozen-lockfile
bun run validate:all

The enforced conventions, the composite validation scripts, packaging, and the developer workflow are documented in CONTRIBUTING.md.

Disposable-profile smoke checklist

The manual installed-VSIX gate — disposable local and remote profiles, live provider sign-in, mixed-route planning and execution, tool review, restart recovery, accessibility, and credential-storage inspection — is documented in docs/smoke-checklist.md. The automated suites do not replace it.

Nightly release status

Forgejo validation, the nightly prerelease path, and the manual stable-release gates are documented in docs/release-process.md. Neither nightly nor stable tag pushes publish anything. Forgejo publication requires a manual workflow dispatch from indev for an existing tag; stable publication additionally requires the documented exact acknowledgements. Marketplace and Open VSX publication remain manual and out of band. CHANGELOG.md records candidate changes and qualification notes.