IDE Remote Mode

Connect the VS Code extension to your AgentKanban board at https://www.agentkanban.io so your AI coding agent can read and update tasks directly via MCP tools.

Overview

The VS Code extension connects to your AgentKanban board via the External API and MCP, letting you:

Manage tasks on your board from any workspace
Use MCP tools so your AI coding agent can read and update tasks directly
Share boards with your team without syncing task files through Git

The extension works with two AI agents: GitHub Copilot and Claude Code. It captures conversation turns from whichever you use and feeds board context back to it. Install either or both.

The sidebar is the main control surface for remote task selection and conversation capture.

The @kanban chat participant is available for context resume in GitHub Copilot.

Prerequisites

An AgentKanban account at https://www.agentkanban.io with a board
An API key with Edit permission on that board (see API Keys)

Setup

Quick start

Use Agent Kanban: Configure Remote to open the persistent sidebar panel, or run Agent Kanban: Setup Remote Connection if you prefer the step-by-step wizard. The wizard walks through:

Server URL (pre-filled with https://www.agentkanban.io)
API key (create one from Settings > API Keys in the web app)
Board selection
MCP configuration (writes .vscode/mcp.json for Copilot and .mcp.json for Claude Code)

You can also configure the server URL and default board in the Agent Kanban sidebar panel.

Where credentials are stored

Extension API key -- stored in VS Code SecretStorage by the extension (OS keychain-backed). Used for sidebar and External API operations.
Server URL, default board ID, and default task ID -- stored in extension workspace state for the current workspace.
MCP config -- written to .vscode/mcp.json (Copilot) and .mcp.json (Claude Code) when you choose to generate it. Both contain the API key directly in the Authorization header. Add them to .gitignore if you share the workspace via version control.

Settings

Setting	Description
The extension does not rely on persisted VS Code settings for remote connection state. The only runtime override is `AK_SERVER_URL`, which takes precedence over the workspace-stored server URL in development.

MCP configuration

The setup wizard writes MCP configuration so your AI coding agent can call AgentKanban tools directly (e.g. get_task_context, add_comment, list_todos). It writes a file for each supported agent. The two formats differ slightly.

GitHub Copilot reads .vscode/mcp.json (top-level servers key):

{
  "servers": {
    "agent-kanban": {
      "type": "http",
      "url": "https://www.agentkanban.io/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer ak_your_api_key_here"
      }
    }
  }
}

Claude Code reads .mcp.json at the project root (top-level mcpServers key):

{
  "mcpServers": {
    "agent-kanban": {
      "type": "http",
      "url": "https://www.agentkanban.io/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer ak_your_api_key_here"
      }
    }
  }
}

The API key is written directly into each config so MCP authentication works immediately with no additional prompts. The extension writes these files using the same API key you provide during setup.

Important: Because the files contain your API key in plaintext, you may wish to add .vscode/mcp.json and .mcp.json to your .gitignore if you share the workspace via version control.

Select a task

The sidebar panel is the main control surface: it shows connection status, lets you switch boards and tasks, and can regenerate the MCP config file.

Use the sidebar to choose the active board and task. Selecting a task binds turn capture to that board task.

How it works

When you select a remote task in the sidebar:

The extension fetches the task from the server via the External API
AGENTS.md gets a small managed sentinel directing the agent to read .agentkanban/INSTRUCTION.md
.agentkanban/INSTRUCTION.md is written with the active task binding, workflow rules, and MCP usage guidance (this file is gitignored)
The AI agent uses MCP tools (get_task_context, add_comment, list_todos, add_todo, update_todo) to interact with the task

Both Copilot and Claude Code read the same AGENTS.md and INSTRUCTION.md, so task binding is identical for either agent.

The agent writes comments and updates directly to the server -- no local task files are created or modified.

Turn Capture Scope

Conversation turns from the active agent (Copilot or Claude Code) are captured against the currently selected task. If you work with multiple chats concurrently, consider using Git Worktrees to isolate each task in its own workspace.

Live updates (push channel)

When a remote task is selected, the extension opens a lightweight read-only Yjs WebSocket connection to the server and listens for changes to the board you are working on. The push channel is authenticated with your API key using a standard Authorization: Bearer ak_... header on the WebSocket upgrade.

The extension reacts to events for the currently selected remote task only:

Task renamed server-side -- the AGENTS.md sentinel is silently rewritten with the new title so the agent always sees the current name.
Task moved to a lane named "Done" -- a notification informs you the task is done.
Task deleted -- a warning notification is shown and the active selection is cleared.
New comment on the task -- a VS Code notification offers to resume the selected task in your installed agent (Copilot or Claude Code).

If the connection drops it reconnects automatically with exponential backoff (1s, 2s, 5s, 10s, 30s cap). If your API key is revoked server-side the connection is closed with code 4001 and no further reconnects are attempted until you re-run Setup Remote Connection.

The connection restores the latest board state after reconnect, but transient notifications are not replayed. For example, if a comment arrives while the extension is offline, the task state is recovered on the next refresh or sync, but you will not receive the original notification pop-up retroactively.

Conversation capture

When a task is selected in remote mode, the extension automatically captures your AI conversation turns and uploads them to the board. No action is required from you.

How it works

The extension watches for conversation activity from the active AI agent (GitHub Copilot and Claude Code are supported; Codex is planned)
New turns (user messages and assistant responses) are batched and uploaded every 2 seconds
Duplicate turns are automatically detected and ignored
The status bar shows a capture indicator (syncing/buffered/idle)

How each agent is captured differs under the hood. Copilot turns are read from its chat session files; Claude Code turns are read from its session transcript. You do not need to do anything different for either.

What gets captured

User prompts and assistant responses from the AI chat
Tool-use-only turns (an agent message that only ran tools, with no prose) carry no board value, so they are not captured
Each turn includes a timestamp and source identifier for traceability

Viewing captured turns

Captured turns appear in the Turns tab on the task editor page in the web application. They are displayed alongside comments and todos, with visual badges indicating the source (Copilot or Claude).

Resume context

Resuming brings the task's board context (description, comments, and prior captured turns) into a fresh agent session. The sidebar shows a resume button for each installed agent:

Resume in Copilot Extension opens @kanban /resume, which injects the task timeline as an explicitly framed retrieved-context block, kept separate from the current session's live turns.
Resume in Claude Extension opens Claude Code in the sidebar and copies a resume prompt to your clipboard. Paste it and press Enter. Claude then pulls the task context itself via the AgentKanban MCP tools.

The two agents differ because of how each extension accepts context. Copilot exposes a chat participant the extension can drive directly; Claude Code has no API to inject a prompt into its sidebar, so the extension uses the clipboard instead.

Either way, resume includes board comments as well as captured chat turns, so steering you did on the task board is visible in the resumed session.

Debugging capture delay

When AK_DEBUG=1 or AGENT_KANBAN_DEBUG=1 is enabled, the sidebar shows the active capture file plus the extension log folder and primary log file path.

Open File opens the current capture file directly in VS Code (Copilot's chatSessions/<session-id>.jsonl or Claude Code's session transcript, depending on the active agent)
Live Tail opens a read-only live tail view that refreshes as the agent writes to the capture file
Open Log File opens the extension's current rolling log file in VS Code
Reveal Folder opens the extension log folder in your operating system file browser

This helps distinguish delays caused by the agent persisting the finalized response text from delays in parsing or upload.

Offline behaviour

If the server is unreachable, turns are buffered locally (up to 500). The buffer is flushed automatically when connectivity is restored. The status bar shows the number of buffered turns.

Troubleshooting

Symptom	Cause	Fix
"Remote mode is not fully configured"	Missing server URL or API key	Run Setup Remote Connection or check settings
"API key is invalid or expired"	401 from server	Run Setup Remote Connection to update the key
"Permission denied"	API key lacks access to the board	Grant Edit permission to the key for this board
"Could not reach the server"	Network or URL issue	Check the server URL and your network connection
"Rate limited"	Too many requests	Wait a moment and retry

Developer notes

For local development against a dev server, set the AK_SERVER_URL environment variable in your VS Code launch config:

{
  "env": {
    "AK_SERVER_URL": "http://localhost:5173"
  }
}

This overrides the default server URL without changing your VS Code settings. Enable debug logging with AK_DEBUG=1 to see all API/MCP/WebSocket interactions.

FAQ

What happens if the server goes down while I am working?

The extension tolerates temporary server outages gracefully:

MCP tools return clear error messages that the agent can relay to you. Work already in your local editor (code, branches) is unaffected.
Push channel reconnects automatically with exponential backoff once the server is reachable again. The latest state is recovered when the connection resumes, but missed transient notifications are not replayed.
Resume will fail with a network error until the server is back, because it loads task context from the server.

Your local git work is never lost. Once the server recovers, reload the window and resume the task again as needed.

Can the extension be used fully offline?

No. Remote mode requires a live connection to the AgentKanban server for task listing, context loading, and comment/todo writes.

The extension no longer ships a legacy local-file mode. If the server is temporarily unreachable during capture, turns are buffered locally and retried automatically when connectivity returns, but board operations themselves still require the remote service.