Forq VSCode Extension

Forq turns VSCode into a control panel for building software with an AI coding agent, driven by an issue board. Move an issue to todo and Forq automatically spawns an agent session for it in an isolated git worktree — when the agent finishes, it moves the issue to in review for you to approve. It works fully offline by default, and can optionally sync the board with Linear.

The coding agent is Anthropic's Claude Code CLI. Forq launches the claude binary you install and sign in to separately, running under your own Anthropic account. Forq does not bundle, modify, proxy, or resell Claude, and it does nothing to circumvent Claude Code's usage limits or terms — your use of the agent remains governed by Anthropic's own Usage Policy and Consumer/Commercial Terms. You can point Forq at a different agent CLI with forq.agentCommand.

Requirements

• Claude Code CLI — Forq launches the claude binary; install it and sign in to your Anthropic account before using Forq. If claude isn't on your PATH, set its location with the forq.agentCommand setting. (To drive a different coding-agent CLI instead, point forq.agentCommand at that binary.)
• Git — agent sessions run in isolated git worktrees, so the workspace must be a git repository.
• A Forq license key — see Licensing below.

The issue board

The issue board lives in the sidebar and is the heart of Forq: it turns a list of work into running agents. It works in one of two modes, chosen per-workspace:

• Local (default, offline): issues live in a plain JSON file in the workspace, .forq/issues.json. No account, no network. The agent reads and writes this same file directly (the generated CLAUDE.md documents the format), so the board, you, and the agent all share one source of truth.
• Linear (optional): issues live in Linear, in a Team/Project you pick. The board mirrors Linear, and agents manage issues through Linear's own MCP server. Linear is authoritative; the local file becomes a read-only cache.

When Start Polling is on, any issue assigned to agent that enters the todo state launches an agent session in an isolated worktree. The agent works the issue end to end; when it's done it moves the issue to in review for a human to mark done (which closes the session). Because each issue runs in its own worktree, several agents can work in parallel without stepping on each other.

Getting started (offline)

1. Open a project folder in VSCode.
2. Initialize → the extension sets up a local .forq/ folder (an empty issues file plus a small meta file) and opens the agent, which first asks you about your idea, then scaffolds the project (framework, CLAUDE.md, README, and the initial issues).
3. Start Polling → issues moved to todo spin up agent sessions automatically.

Each workspace is one project — there is no cross-project list. A workspace counts as initialized once its issues file (.forq/issues.json) exists; the project's own description lives in its tracked README.md. The .forq/ folder holds local-only board state and is gitignored.

Licensing

Forq is a paid extension. On a fresh install it is locked — the sidebar shows an Enter License Key button and a $(lock) Activate Forq item in the status bar. Paste the license key from your Dodo Payments purchase email (Command Palette → Forq: Enter License Key, or click the status-bar item) to unlock it.

• Activation is a one-time online step that binds the key to this machine. After that the result is cached locally and trusted offline — Forq does not re-validate or phone home again, so you can work fully offline.
• Manage or move a license with Forq: Manage License (replace the key, or remove it from this machine to free an activation for another device).

Syncing with Linear

1. Connect Linear → a browser tab opens for OAuth consent (Authorization Code + PKCE). Approve, and the browser hands you back to VS Code via a vscode:// redirect — no local server is started. Then pick a Team and a Project.
2. The board now reflects that Linear project. Create/move issues here or in Linear's own app — Linear wins on conflict.
3. Add Linear MCP → registers Linear's MCP server with the agent CLI so agents manage issues directly in Linear. Run /mcp in an agent session the first time to authorize it.

Switch back anytime with Use Local; disconnect entirely with Disconnect Linear.

How issues map to Linear (labels)

An issue's status maps to a Linear workflow state (backlog / unstarted / started / "In Review" / completed / canceled). Its type, mode, and assigned_to fields are stored as labels — but only the non-default value of each field carries a label. The default value carries no label, which keeps a typical feature / agent issue label-free.

Using the labels correctly:

• Set a field from Linear's app by adding or removing the matching label. Add Bug to make an issue a bug; remove it to make it a feature. Add Human to take an issue off the agents; remove it to hand it back. Add mode:plan (or mode:auto) to override the run mode.
• The extension creates the labels it needs. Human and mode:* are created on first use; Bug is Linear's built-in label. You don't have to pre-create any of them.
• mode: labels are relative to your default. Because the unlabeled mode is forq.defaultMode, changing that setting flips which issues need a mode: label. If you want every issue's mode to be explicit in Linear, that's expected — the extension writes a mode: label only when it has to.
• Don't hand-edit a mode: label to a value other than auto or plan — an unrecognized mode: label is ignored and the issue falls back to your default.
• Legacy labels still work. Older paired labels (type:bug, type:feature, assignee:agent, assignee:human) are still read correctly and are cleaned up automatically the next time you edit the issue from the extension.
• Other labels are left alone. Any labels you add for your own organization are preserved on every edit; the extension only manages the ones above.

One-click sessions

Alongside the board, Forq gives you launcher buttons that drive the agent CLI directly — no terminal commands to memorize. They live in the Forq view in the activity bar, with a terminal toggle pinned to the status bar:

Because every session opens as an editor tab, you can run several agents side by side — one per worktree — and arrange them like panes.

Settings

Mode and the Linear Team/Project mapping are stored per-workspace and set via the Connect Linear / Use Local commands, not settings.

Commands

Caveats

• The OAuth callback returns through VS Code's URI handler (vscode://barakolsheviz.agent-forq/auth/callback) — no local server or ports. The Linear OAuth app must register that redirect URI (and the matching vscode-insiders://… if you run Insiders, or your fork's scheme).
• In Linear mode, a team needs the usual workflow states (backlog / unstarted / started / completed / canceled); an "In Review" state is used when present, otherwise the started state is reused.

Privacy & data

Forq is offline-first. The local board never leaves your machine — issues live in a plain file in your workspace (.forq/issues.json). Forq only contacts the network for the specific, opt-in features below, and it does not collect analytics or send telemetry of any kind.

Secrets (your license key, Gemini API key, and Linear token) are stored in the editor's encrypted SecretStorage, never in plaintext settings. The Gemini and Linear features are entirely optional; with neither configured, Forq talks to the network only for the one-time license activation.

For full details, see the privacy policy: https://forq.ink/privacy.

Disclaimer

Forq is an independent, third-party tool. It drives a separately-installed coding-agent CLI on your machine — by default Anthropic's Claude Code (claude). Forq is not affiliated with, endorsed by, or sponsored by Anthropic; "Claude" and "Claude Code" are trademarks of Anthropic. Forq does not bundle or redistribute Claude and does not bypass its usage limits or terms — you supply and sign in to the CLI yourself, and your use of it is governed by Anthropic's own terms. "Linear" is a trademark of Linear Orbit, Inc.