Bilg for VS Code

Bilg is a shared context layer for teams that build with AI agents: documents, epics and decisions in one place, readable and writable by both people and their agents.

This extension brings that context into VS Code — the project your workspace belongs to, its epics and tasks, the decisions behind them, and the open questions nobody has answered yet.

You need a Bilg account. Sign up for free at app.bilgai.com. Without an account the extension has nothing to connect to.

What you get

Your project, in the sidebar. Bind a workspace folder to a Bilg project once, and its epics, tasks, decisions, open questions and documents show up in the activity bar. Every record carries its stable key (BLG-E15, BLG-T42), the same key your agent and your teammates use.

Board. Click Board at the top of the sidebar to open the project board in an editor tab, move work across stages, and drill into an epic without leaving the editor. Each epic's detail view includes an activity timeline, so you can see who changed what and when. While the board is on screen it picks up changes from your teammates and agents on its own, every 30 seconds and whenever you come back to it. Projects that opt into the optional Acceptance stage show it here too, matching the web board — the Build column for "ready" reads "Ready for deployment". An epic whose tasks are all done stays in In Progress until you move it on, and its card says what it is waiting on: "All done · ready to move", or how many open questions are left and who they are addressed to. Tick Waiting on me in the board toolbar to see only the epics with an open question for you. Once an epic is marked deployed it's locked: editing stays with a new epic, though closing a leftover open task or resolving an open question is still allowed.

Tasks you can actually work. Six statuses — open, in progress, in review, blocked, done, cancelled — plus type, priority, labels and a blocked reason, all editable straight from a task's buffer. Cycle a task's status, assign it to a teammate, and leave comments — all from the tree or the command palette.

Comments and questions, on epics too. Leave a comment on an epic, not just a task, and turn any epic or task comment into an open question with one click. Ask a question to a specific teammate — they get notified, and the epic detail view shows who asked, who it's addressed to, and who resolved it and when. An epic's Discussion tab lines up its comments and its questions' open/resolve events in one timeline.

Files, next to the work. Attach any file to a comment — a zip, a screenshot, a log — or add it straight to an epic, a task or an open question from its Files section. Each Files list shows everything attached to that item, including what came in with a comment, and who added it. Files open or download in your browser, and your teammates get them from the same place. The size limit per file follows the project owner's plan.

Pull requests and commits linked to a task, when the project has GitHub connected.

Surfaces. A read-only Surfaces tab lists the project's apps and services (web, mobile, backend...) with their git repository and folder; edit them in the web app.

Surface scope. Add "surface": "Mobile" to .bilg/bilg.config.json (the Bind Workspace command offers the project's surfaces) and the sidebar and board show only that surface's epics and tasks, plus project-wide ones. Use Toggle Surface Scope in the sidebar title to see the whole project and back. Cards and rows carry surface chips (a task shows the surfaces it inherits from its epic), and a task's buffer has a surfaces: line to link it to specific surfaces (empty = inherit from the epic). If the named surface doesn't exist in the project, the whole project is shown and you get a one-time warning. The CLAUDE.md hint also tells your agent to pass that surface to list_epics and list_tasks.

Task board. A drag-and-drop board across your tasks' statuses, grouped by epic or assignee when you want that view, right next to the epic board. Filter by epic, assignee, priority, type, label or a blocked-only toggle, with a live count of what's active; lanes with no card in progress start collapsed and remember how you left them.

Search and ask. Semantic search across your Markdown, PDF and DOCX documents. "Find related documents" pulls up what's relevant to the file you're looking at.

Handoffs. Addressed markdown deliveries between teammates and their agents, with a context link, replies and a resolve state. Unread handoffs show up as a badge on the Bilg view. You can edit a handoff you sent until the recipient has seen it; after that, add a correction and the recipient is notified.

Notifications. Assignments, handoffs, questions asked to you, comments, epic status changes and project invites, with an unread badge in the status bar. Things that need you also pop up as a VS Code notification (turn off with bilg.notifications.showPopups).

Project agent rules. See the markdown policy blocks your project loads into every agent's context, so you know what your agent has been told.

Send feedback to the Bilg team from the command palette.

Setup

Install the extension.
Run Bilg: Set up Bilg from the command palette (⇧⌘P / Ctrl+Shift+P).
Enter your Bilg URL (https://app.bilgai.com unless you self-host) and an API key — create one under Settings → API keys in the Bilg web app. Keys start with blg_.
Run Bilg: Bind Workspace to Project to connect the folder you're in to a Bilg project.

Your API key is stored in VS Code's secret storage, not in settings or in your repo.

Commands

Command	What it does
`Bilg: Set up Bilg`	Connect to a Bilg instance with an API key
`Bilg: Bind Workspace to Project`	Link the current folder to a project
`Bilg: Search Knowledge Base`	Semantic search across your documents
`Bilg: Ask`	Ask a question and get the matching sources
`Bilg: Find Related Documents`	Documents relevant to the active file
`Bilg: Open Board` / `Open Tasks`	Project board and task list
`Bilg: Add Task` / `Add Decision` / `Add Question` / `Add Document`	Create records
`Bilg: Assign Task` / `Add Comment` / `Cycle Task Status`	Move work forward
`Bilg: Handoffs`	Read and resolve handoffs addressed to you
`Bilg: Show Notifications`	Unread notifications
`Bilg: Project Agent Rules`	The rules your project gives every agent
`Bilg: Send Feedback`	Report a bug or send an idea to the Bilg team
`Bilg: Show Connection Status`	Which instance and identity you're connected as

Agents can do this too

The same project is available to any MCP client — Claude Code, Claude Desktop, Cursor. The extension and your agent read and write the same records over the same API, so a decision your agent logs in the terminal is the decision you see in the sidebar.

Connecting an agent takes one config entry, or one prompt you paste into the agent and let it do the setup: app.bilgai.com/docs/connect.

Some things stay human-only by design: only a person signed in on the web can mark an epic deployed or delete records permanently. Agents get a 403 and an explanation.

Requirements

VS Code 1.95 or newer
A Bilg account and an API key

Installing outside VS Code

Cursor, Windsurf, VSCodium and other VS Code forks install extensions from Open VSX, where this extension is published under the same bilg.bilg-vscode id.

Support

Bugs and feature requests: github.com/volkansuner/bilg-feedback. Everything else: app.bilgai.com.