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 sidebar is the main control surface for remote task selection and conversation capture.

The @kanban participant is available for context resume operations.

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)

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 when you choose to generate it. Contains the API key directly in the Authorization header. Add this file 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 an MCP configuration to .vscode/mcp.json so your AI coding agent can call AgentKanban tools directly (e.g. get_task_context, add_comment, list_todos).

The generated config looks like:

{
  "servers": {
    "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 the config so MCP authentication works immediately with no additional prompts. The extension writes this file using the same API key you provide during setup.

Important: Because the file contains your API key in plaintext, you may wish to add .vscode/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 is updated with a remote task sentinel that includes the task ID and MCP tool references
Any legacy .agentkanban/INSTRUCTION.md file is removed if it still exists from an older extension version
The AI agent uses MCP tools (get_task_context, add_comment, list_todos, add_todo, update_todo) to interact with the task

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

Turn Capture Scope

Copilot chat turns 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 Resume In Chat, which opens @kanban /resume for the selected task.

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 harness (currently GitHub Copilot; Claude Code and Codex support 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)

What gets captured

User prompts and assistant responses from the AI chat
Tool-use-only turns are flagged but still stored
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, Claude, Codex).

Resume context

Use Resume In Chat in the Remote sidebar to open @kanban /resume for the selected task.

The resume flow:

loads prior captured board turns for the selected task
injects them as an explicitly framed retrieved-context block in chat
keeps them separate from the current session's live turns

Important limitation:

the sidebar does not silently mutate an already-running Copilot chat session
instead it launches the supported @kanban /resume command because VS Code does not expose a stable API for hidden sidebar-to-chat transcript injection

The underlying extension code now uses a unified task timeline abstraction, and /resume includes board comments as well as captured chat turns so user steering on the task board is visible in resumed chat context.

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 chatSessions/<session-id>.jsonl file directly in VS Code
Live Tail opens a read-only live tail view that refreshes as VS Code 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 Copilot/VS Code 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 commands (/resume, /resume delta) will fail with a network error until the server is back.

Your local git work is never lost. Once the server recovers, reload the window or rerun @kanban /resume 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.