DoStuff Issue Board

A simple software issue board for VSCode with a built-in MCP server, so coding agents can read tickets and report progress without being able to silently change scope.

Made mostly for solo devs who have trouble keeping track of things they were totally going to fix after the agent broke it.

Keeps an audit log of changes to a ticket — in case you still have the willpower to read something after reviewing the 113-file PR the agent opened.

New in 2.0.0 — Share one ticket board across clones and contributors over plain git (a hidden ref, no server, no worktree noise), or skip the VSCode window entirely with the bundled headless server. Claude Code drives the queue for near-zero context cost via the new agent skill, and parallel agents can finally write without clobbering each other. Full changelog ↓

Install

From the Marketplace — search for "DoStuff" in the VSCode Extensions view and click Install.

From a .vsix — download the latest release, then in VSCode open the Extensions view (Ctrl+Shift+X), click the … menu → Install from VSIX…, and pick the file. Or right-click the .vsix in your file explorer and choose Install Extension VSIX.

Quick start

1. Click the DoStuff icon in the activity bar — the sidebar opens with a sample ticket.
2. Hit Ctrl+Shift+I (or Cmd+Shift+I) to file a new issue. New tickets always land in Thinking.
3. Run DoStuff: Show Board from the command palette (or click the board icon in the sidebar title bar) for the full Kanban view.
4. (Optional) Enable the MCP server — DoStuff: Toggle MCP Server — to let coding agents read your queue and report progress. See Using the MCP server below.

Using the extension

Sidebar

The sidebar lists every issue, newest first. The search box matches title, id, description, and tags; the status chips filter by lane. Complete tickets are hidden by default — toggle "Show completed" to reveal them.

Click any row to expand an inline detail panel for editing title, description, type, priority, status, tags, links, tasks, verify criteria, and attachments. Edits autosave as you type (toggleable in settings).

Board

The board has five lanes:

Thinking drawer  →  Planned  →  Working  →  Verification  →  Complete drawer
   (left)                                                          (right)

Drag a card between lanes to change its status. Each active lane (Planned, Working, Verification) is capped — six tickets by default; configurable via dostuff.activeLaneCap.

You can also start a drag in the sidebar. The board lights each lane and drawer with a "Move to lane" overlay; click any lane to drop, or press Esc to cancel. If the board isn't open, dragging from the sidebar opens it.

Thinking drawer: click a card to view its details. Shift+Click promotes the draft straight to Planned.

Ticket links

Relate tickets to each other from the detail panel's Links field. Pick a relationship — blocks, blocked by, child of, parent of, or relates to — then search the target by #number, DS-id, or a title substring. Forward kinds (blocks / child of / relates to) are stored on the current ticket and shown as chips; inverse kinds (blocked by / parent of) define the relationship from the other ticket's side without leaving the current one, and appear under Linked by. Click any chip to jump to that ticket; remove a Linked by chip to delete the relationship from its source. Links are directional and stored once — deleting the link, or the ticket, cleans up both ends. The new-issue dialog offers the same relationships (forward and inverse); inverse ones are applied to their source tickets right after the new ticket is created.

Graph view

Run DoStuff: Show Graph (command palette or the sidebar toolbar) to see the link network as an interactive node-link diagram — only tickets that participate in at least one link appear. Edges are colored and arrowed by kind, and the legend doubles as a filter: click a relationship type to hide or show its edges (tickets left with no visible link drop out too). Drag a node to rearrange; scroll to zoom; drag the background to pan; click a node (or focus it and press Enter) to open that ticket. Fit to view frames everything currently shown, and Forces opens sliders to tune link distance, repulsion, and node spacing on the fly.

Use the filter box (by #id, title, or tag) to focus on part of the network. Filtering preserves context: a matched ticket keeps its whole connected chain so you never see it stripped of its blockers, children, or related tickets — matches render normally while the surrounding chain dims. The view auto-fits to the matching cluster.

Attachments

Each ticket has an Attachments strip in its detail panel. Drop one or more files onto it, or hit the + to pick via the OS dialog. Image attachments render as thumbnails — click to view full-size (Esc closes). Non-images open in VSCode via the system handler. Cap is 10 MB per file. Binaries live next to the ticket database, so the default .gitignore keeps them out of Git. Deleting a ticket removes its attachments too.

Attachments are exposed to MCP clients through get_ticket's attachments[] field; agents fetch the bytes by reading dostuff://attachments/{ticketId}/{attachmentId}. Export/import JSON includes the metadata but not the bytes — re-upload after an import if you need them.

Tags

Tags are free-form labels (like Jira labels), edited in the detail panel and rendered as colored chips on sidebar rows and board cards. Once a row runs out of space the extras collapse to dots. Chip colors are derived deterministically from the tag name — no per-tag setup. Sidebar search and the board drawer filter both match tag substrings.

Links in ticket text

Description and verify-criteria text is auto-linkified. Bare http(s)://, file:///, mailto:, and workspace-relative ./path/to/file references become clickable. External links open in your browser; file links and relative paths open in VSCode.

Import / export

Run DoStuff: Export Issues (JSON)… or DoStuff: Import Issues (JSON)… from the command palette, or use the cloud icons in the sidebar title bar. The exported JSON contains the ticket data and attachment metadata — attachment bytes are not bundled.

Workflow rules

• New tickets always start in Thinking for human triage.
• Agents may move tickets freely among the non-terminal states — promote out of Thinking, shuffle the active lanes, or demote back to Thinking — and edit the description of any non-terminal ticket.
• Tickets move freely between Planned, Working, and Verification.
• Only humans can set the terminal states, and agents signal them through two distinct flows: request_ticket_complete (from Verification only) says "the work is finished — please accept" and approval moves the ticket to Complete; request_ticket_close says "this is OBE / no longer needed" and approval moves it to Closed. Distinct on purpose — history records whether a ticket was done or dropped.
• Active lanes (Planned, Working, Verification) are each capped — a workflow throttle. Finish or de-scope before starting more work. Or raise dostuff.activeLaneCap; I'm not your supervisor.
• Closed is a "won't do" state. It lives only in the sidebar (no board lane/drawer), is hidden under the All filter, and is reachable via its dedicated filter chip. The sidebar also has an Awaiting decision filter that surfaces tickets with a pending agent close/completion request.

Keyboard shortcuts

Settings reference

Sharing tickets across clones (git sync)

Share your ticket board across clones via git — no server. Tickets sync through a hidden git ref (refs/dostuff/state) that never touches your worktree, branches, or PRs: enable dostuff.sync.enabled (or run DoStuff: Toggle Git Ticket Sync), and everyone pushes/pulls tickets over the remote you already use. Offline-first — local edits always commit to the ref; pushes retry on the next sync. DoStuff: Sync Tickets Now forces a cycle; the $(sync) status-bar item shows state and doubles as the button.

How conflicts resolve: state-level last-writer-wins on a per-ticket updatedAt (with a deterministic tiebreak, so replicas never diverge), per-task/attachment LWW for concurrent delete-vs-edit, and append-only union for history/records. Clock skew between machines biases who wins a concurrent edit but never causes divergence. Deletes propagate via tombstones (kept 90 days).

Two clones that filed tickets independently will collide on DS-NNN numbers: the first sync renumbers deterministically (oldest ticket keeps its number) and both sides toast the rename list. Agent note: after such a merge, a DS-NNN handle an agent memorized mid-session can change — agents recover via list_issues / get_ticket by title. Sync is otherwise invisible to MCP agents; all write boundaries hold unchanged.

Enabling sync also fixes same-machine clobbering: two VSCode windows on one workspace converge within ~15 seconds instead of overwriting each other.

meta.json                        { "formatVersion": 1 }
tickets/<guid>.json              one ticket per blob, keyed by a stable guid
tombstones/<guid>.json           deletion witnesses (which ticket died, when)
attachments/<guid>/<attId>       raw attachment bytes (optional, capped)

Using the MCP server

DoStuff runs an HTTP MCP server on 127.0.0.1:<port>/mcp. Each VSCode window binds its own port and writes a registry entry so agents can discover which port serves which workspace — no port collision with multiple windows open. The server is disabled by default — enable it with DoStuff: Toggle MCP Server or by setting dostuff.mcp.enabled: true.

Every tool response includes a workspace field ({ name, rootPath } or null) so agents can verify they're connected to the intended project.

Pinning the port (recommended)

By default the OS picks an ephemeral port each session, so any mcp.json URL with a hard-coded port breaks at the next restart. To keep the URL stable:

1. Start the MCP server in this workspace (status bar shows $(plug) DoStuff MCP :<port>).
2. Run DoStuff: Pin MCP Port to Workspace from the command palette. DoStuff writes the live port to this workspace's settings as dostuff.mcp.port.
3. From then on the server tries to bind that exact port at every start. If the port is busy (e.g. another DoStuff window pinned it), the server falls back to an ephemeral port and logs a warning to Output → DoStuff MCP.

You can also edit dostuff.mcp.port (window-scoped, 1024–65535) by hand. Set it back to 0 to return to ephemeral.

Looking up the live port

• Status bar: the $(plug) DoStuff MCP :<port> indicator shows the live port.
• Registry file: ~/.config/dostuff/instances.json (Linux/macOS) or %APPDATA%/dostuff/instances.json (Windows) lists every running instance. See Multi-workspace agent discovery below.

Pointing a client at it

Pin the port (above), then drop it into your client config:

VSCode MCP settings (VS Code 1.99+)

"dostuff": {
  "servers": {
    "dostuff-ticket": {
      "url": "http://127.0.0.1:<PORT>/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

Claude Code

Add an entry to your .mcp.json (or run claude mcp add):

{
  "mcpServers": {
    "dostuff": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:<PORT>/mcp"
    }
  }
}

Customize the workflow prompt via the dostuff.mcp.instructions setting or the DoStuff: Edit MCP Workflow Instructions… command. The command pre-fills the editor with the built-in default so you can see it before editing; clearing the field and saving reverts to the default.

The full prompt is served once per connection as the MCP server's initialize instructions (clients like Claude Code inject it into agent context automatically — visible under /mcp), and stays readable at the dostuff://instructions/workflow resource and the workflow MCP prompt. Individual tool responses carry only a one-line pointer instead of repeating the full text, keeping per-call context small.

Claude Code Agent Skill (skip MCP registration)

The repo ships a Claude Code Agent Skill — skills/dostuff-tickets/ — that covers the entire MCP surface without registering the server as an MCP client. The server is stateless loopback HTTP, so the skill's helper script (scripts/dostuff.sh) drives it with bare one-shot curl POSTs: it discovers the right port from the instance registry, validates field length caps locally before sending, wraps the JSON-RPC envelope, and unwraps SSE framing. Full parameter schemas live in a lazy-loaded reference file.

Why bother: a registered MCP server costs every Claude Code session the workflow instructions (~1.5 KB) plus connection metadata, whether or not any ticket work happens. The skill costs only its one-line listing entry at session start; the body loads when ticket work actually comes up, and the schema reference only if the agent needs exact shapes.

Install one of two ways:

• From the extension — run DoStuff: Install Claude Code Agent Skill (command palette). Copies the bundled skill to ~/.claude/skills/dostuff-tickets; new Claude Code sessions pick it up automatically. Stays current on its own: each install records the extension version plus a hash of every file, and on activation a newer extension silently refreshes an unmodified copy. If you've edited the skill locally it is never overwritten — you get a one-time "Replace / Keep mine" prompt instead, and a manual copy without the marker file is never touched at all.
• As a plugin — /plugin marketplace add wcole3/DoStuff, then /plugin install dostuff@dostuff. Versioned with the repo; updates arrive through Claude Code's plugin update flow (the plugin version is pinned to the extension version by a CI test, so every release is pickable).

Keep registering the MCP server instead when you want typed tool schemas with client-side validation, concurrent dispatch of read-only tools (readOnlyHint), per-tool permission gating, or a non-Claude-Code client. The two paths coexist: the skill detects registered mcp__dostuff__* tools and defers to them, so installing both is safe.

Headless server (no VSCode required)

The extension bundles a standalone ticket server — dist/server.cjs in the extension install — that serves the same loopback MCP HTTP API against the same <workspace>/.vscode/dostuff/dostuff.db and registers in the same instance registry. The agent skill (and any other MCP client) finds it exactly like a running extension, so ticket work no longer requires an open VSCode window — and future IDE integrations get a process to talk to instead of a codebase to port.

node ~/.vscode/extensions/<publisher>.dostuff-*/dist/server.cjs serve --workspace /path/to/repo

• serve [--workspace PATH] [--port N] [--storage-dir PATH] [--takeover] [--no-sync] [--print-config] — serve one workspace (default: cwd). Prints {"port": N, ...} on stdout when ready; logs to stderr; Ctrl-C unregisters and exits cleanly.
• status — list registered instances (workspace, port, pid, liveness).
• Config parity: the server resolves flags > DOSTUFF_* env vars (DOSTUFF_MCP_PORT, DOSTUFF_STORAGE_DIR, DOSTUFF_ACTIVE_LANE_CAP, DOSTUFF_MCP_RECORD_LIMIT, DOSTUFF_MCP_INSTRUCTIONS) > the workspace's .vscode/settings.json dostuff.* keys > defaults — so one workspace behaves identically under both hosts (same lane cap, record window, custom instructions; comments and trailing commas in settings.json are fine). --print-config shows every resolved value and where it came from.
• Same rules: agent write boundaries, lane caps, field caps, and human-only Complete/Closed are enforced in the shared core — there is no privileged headless path.
• Single-writer gate: serve refuses a workspace that a live process (VSCode window or another headless server) already serves — exit 3, naming the pid/port — because the DB is wholesale-rewrite and two writers clobber each other. --takeover overrides for zombie entries. The inverse (opening VSCode while a headless server runs) is the same two-window clobber class as before: enable git ticket sync and the two reconcile through the ref automatically (the headless server runs the same sync controller, honoring dostuff.sync.* from settings.json; --no-sync opts out).
• Close-request approvals remain human actions in the VSCode UI — a headless-filed request_ticket_close/request_ticket_complete parks in pendingClose until a human opens the board, same as an unattended window.

Default workflow prompt

This is intentionally terse.

DoStuff is this workspace's engineering ticket queue. Use these tools to find,
start, update, and file work.

You may NOT change a ticket's title, priority, type, or verify criteria over
MCP, and only a human can set Complete or Closed. Wrong? Say so, or file a new
ticket.

Write terse — every byte is re-read on each later ticket read. Fragments fine,
grammar not important. Record notes: one line, ~15 words, facts and outcomes.
No narration, no restating the ticket, no summarizing what you read or plan.
Descriptions: 1-2 sentences of what + why, detail below; boards show only that
opening.

Find work: `list_issues` or `dostuff://tickets`, then `get_ticket` by number
("42"), id ("DS-042"), or title substring. Read description + verify criteria
first.

`update_ticket_status` moves among Thinking, Planned, Working, Verification
(active lanes cap 6 each; Thinking uncapped). Working when you start. As you
go, `update_ticket_progress` ticks tasks, appends one note, records each commit
sha. Done → Verification, then `request_ticket_complete`. Verify fails → back
to Working.

OBE — superseded or won't be done → `request_ticket_close` instead. Both
requests need human approval, neither changes status: poll `get_ticket` with
`view: "status"`. Close = dropped work, complete = finished work.

Follow-ups → `create_ticket` (lands in Thinking). Reshape a draft's tags,
links, tasks with `update_ticket_draft` — Thinking only. Reads return newest
record entries only — `recordLimit: 0` for full history.

(The lane-cap number tracks your dostuff.activeLaneCap setting.) Override the text per-user via DoStuff: Edit MCP Workflow Instructions… or dostuff.mcp.instructions in Settings. Leave the setting blank to use the built-in text above.

Keep a custom prompt under 2KB. Claude Code truncates MCP server instructions at 2KB and drops the remainder with no error — a prompt that overruns loses its tail, which is where rules usually put the things you least want dropped. The built-in text is ~1.5KB for this reason, and a test enforces the budget. Detail that doesn't fit belongs in a tool's own description, which gets its own 2KB.

The prompt also bounds what agents write. Ticket prose is replayed on every later read of that ticket, by every agent, so the built-in text caps record notes at one ~15-word line and descriptions at a 1-2 sentence lead. The schema backs it up: recordEntry / note are capped at 500 chars and description at 10,000 (an over-long value is rejected, not truncated). These caps apply only to agent writes over MCP — the UI is uncapped, and tickets already on disk with longer prose load and are served unchanged. A custom prompt that drops the write-terse rule gives that back.

Tools

Resources

• dostuff://tickets — summary index of Thinking + active-lane tickets (Complete and Closed hidden). One compact row per ticket — id, number, title, type, priority, status, tags, a done/total task count, and a short excerpt of the description's opening paragraph — plus count and a single detailUriTemplate. Full bodies are deliberately not served here: fetch one from dostuff://tickets/{id}.
• dostuff://tickets/{id} — one Thinking or active-lane ticket, full body (record windowed as in get_ticket).
• dostuff://attachments/{ticketId}/{attachmentId} — raw attachment bytes (base64).
• dostuff://instructions/workflow — the workflow prompt.

Resources are URI templates with nowhere to put arguments, so they always serve the default shape. An agent that needs a demoted section calls get_ticket with include.

Why the reads are lean

Everything an MCP tool returns lands in the agent's context window and is paid for on every call, so DoStuff's reads are shaped to be small by default and complete on request:

• The record log is windowed to its newest few entries (dostuff.mcp.recordLimit, default 3). It is append-only and git sync only ever unions it, so on a long-lived ticket it grows without bound and would otherwise dominate every read of that ticket. recordLimit: 0 returns all of it.
• Commit shas collapse to a commitCount. They're shas the agent itself reported, and git holds them authoritatively. include: ["commits"] brings the list back.
• verifyCriteria is truncated past 2,000 characters — insurance against one verbose ticket taxing every read of it, not something you'll normally hit.
• The board listing serves summary rows, not full ticket bodies. Fetching 25 full tickets to decide which one to work on costs roughly 20× what the index does.
• Anything withheld is named in omitted, spelled exactly as include expects — so the escape hatch is visible at the moment an agent wants it, rather than only in the tool docs.

If your agents routinely need deeper history, raise dostuff.mcp.recordLimit; that is the one knob most worth tuning. src/measure.bench.test.ts prints the byte cost of each of these on every bun test run if you want to see the tradeoff on your own tickets.

Two Claude Code behaviors also shape this (docs): it truncates MCP server instructions at 2KB silently, and it defers tool schemas by default (tool search), so the workflow prompt — not the tool list — is what costs context each session. Both are why the built-in prompt is terse and leads with what the server is for.

Multi-workspace agent discovery

TL;DR: just pin the port.

Each VSCode window with DoStuff enabled binds its MCP server to a localhost port and registers itself in a user-global file so external agents can find the right endpoint per workspace.

• Registry file: ~/.config/dostuff/instances.json on Linux/macOS, %APPDATA%/dostuff/instances.json on Windows.
• Entry shape: { "workspacePath": string, "port": number, "pid": number, "name": string, "startedAt": ISO8601 }. Paths are resolved absolute and lowercased on Windows.
• Stale entries are pruned automatically on activation (via process.kill(pid, 0)) and removed on extension deactivation.

Recommended agent discovery algorithm:

1. Read the registry file. Treat ENOENT and corrupt JSON as an empty list.
2. Normalize process.cwd() the same way (resolve absolute; lowercase on Windows).
3. Filter entries whose workspacePath is a path-prefix of the normalized cwd; pick the longest match.
4. On a tie, prefer the most recent startedAt. If no entry is a prefix and the list has a single entry, fall back to it.
5. Optionally verify with process.kill(pid, 0) before connecting. The MCP endpoint is http://127.0.0.1:<port>/mcp.

If the auto-pick is wrong (e.g. an agent runs from a deeply nested cwd that doesn't share a prefix with the workspace root), set dostuff.mcp.workspaceOverride on that window to the path you want advertised.

Storage

Tickets are stored in a single SQLite database — dostuff.db — under <workspace>/.vscode/dostuff/ (or in VSCode globalState if no workspace is open). The folder is configurable via dostuff.storagePath. Attachment binaries live alongside the DB at <storagePath>/attachments/<issueId>/.

Legacy <id>.json ticket files from earlier versions are migrated into the DB on first launch and moved to a legacy-json-backup/ folder next to the DB — your tickets carry over automatically.

On first use, DoStuff writes a nested .gitignore inside the storage folder so the DB and attachments are excluded from Git even when .vscode/ is tracked. The gitignore itself is kept trackable (via !.gitignore) so teammates can see why their tickets aren't there. Disable via dostuff.writeStorageGitignore: false.

With sync off (the default), the ticket DB is single-writer. Each clone keeps its own local board, and opening the same workspace in two VSCode windows at once can silently overwrite edits (last save wins). Turning on git sync fixes both: clones converge through a hidden git ref, and two windows on one workspace reconcile within ~15 seconds.

Roadmap

Nothing committed yet — git sync was the headline item and has shipped. Design docs for it live in docs/plans/ticket-sync/; they're a historical record of how it was built, not a description of current behavior.

Ideas under consideration, none promised:

• Sync status per ticket — surfacing which tickets are ahead of the remote, rather than only a global status-bar state.
• Richer agent read shaping — the include mechanism currently covers commits and verify criteria; attachments and status history are the obvious next candidates if reads get heavy again.

If you want something, open an issue — the roadmap is mostly "what someone asked for."

Building from source

git clone https://github.com/wcole3/DoStuff
cd DoStuff
bun install
bun run package

bun run package produces a .vsix. In VSCode, right-click the file and choose Install Extension VSIX.

Changelog

License

MIT — see LICENSE.txt.