KachiBox

Daily tasks in VS Code — one JSON file per task. Markdown checklists, notes, filters, and Git-friendly storage in the sidebar.

• Portable — plain JSON on disk; edit in the UI or open the task file
• Project + global — workspace tasks in .vscode/tasks plus an optional machine-wide folder
• Built for flow — quick capture, focus views (Today / Overdue / Blocked), keyboard shortcuts, export/import

Install: Visual Studio Marketplace — search KachiBox, or install from a release .vsix.

Getting started

1. Install KachiBox from the Marketplace (publisher BeagleRidgeLLC) or from a .vsix.
2. Click the checklist icon in the Activity Bar (left sidebar).
3. Open the Tasks panel. Expand Actions at the bottom and click + Global Task or + Project Task, or use + in the panel title bar / KachiBox: New Task.

The sidebar has two views: Tasks (list) and Actions (new-task buttons, Save to Git, storage summary). Task detail opens in editor tabs beside the sidebar.

Panel toolbar (top of the Tasks view):

Button	Action
+	New task
Refresh	Reload tasks from disk
Gear	Open KachiBox settings

Creating and editing tasks

New task

Use + Global Task (primary) or + Project Task in the Actions footer, the + button in the Tasks panel title bar, or KachiBox: New Task from the command palette. Enter a title; a detail editor tab opens with the title focused.

New tasks appear at the top of the list when sort is Manual (default).

Task cards

Click a card to open that task in an editor-area detail tab (not a sidebar overlay). You can keep multiple tasks open at once — one tab per task; clicking a card again reveals its existing tab. The sidebar card for the active detail tab is highlighted.

• Title and other fields auto-save as you type (same debounce as before).
• Notes sit in a right-hand pane (rendered Markdown by default). Edit notes switches to an in-place Markdown text editor in that pane; Preview returns to the rendered view.
• Condensed (toolbar): title and progress ring only.
• Full: labels, priority, due date, and more on the card.

Detail editor

Tab	Contents
Checklist	Checklist items on the left pane
Details	Status (To Do / In Progress / Blocked / Done), due date, labels, priority
Meeting	Shown when linked from KaigiBox — open the source meeting

The detail editor uses a vertical splitter: left (~25% by default) holds the title and Checklist / Details / Meeting tabs; right holds Notes. Drag the splitter (or use Left/Right / Home / End when focused) to resize; the ratio is remembered for the session.

Header: checklist progress on the left; JSON on the right. Task actions (Done, Move, Delete) are in the title ⋯ menu. Close the editor tab with the tab’s ×, Escape, or KachiBox: Close Task Detail.

KaigiBox integration

When KaigiBox links a meeting action to a task:

• The task stores sourceMeetingId, sourceActionId, and sourceMeetingPath.
• Meeting actions focus chip shows only linked tasks; task cards show a Meeting badge.
• Open meeting on the Meeting tab opens the source meeting in KaigiBox.
• Marking the task done or re-open syncs the meeting action checkbox (always on).
• With kachibox.syncLinkedActions (default on), editing the task title, due date, or assignee (assignee: label) syncs back to the meeting action; saving the meeting syncs changes to the task.

Requires KaigiBox installed for meeting navigation and field sync.

Done and closed tasks

1. Actions → Done marks the task complete, checks all checklist items, and removes it from the active list.
2. Toolbar Closed shows completed tasks (with closed date under the title).
3. Actions → Re-open returns a closed task to To Do on the active list.

Checklists

Tasks store checklists as Markdown inside the JSON file:

- [ ] Todo item
- [x] Completed item

• Click a checkbox (or item text) to toggle done.
• Double-click item text to edit; changes save automatically.
• Drag the ⋮⋮ grip to reorder items.
• ⋯ menu on each row: Indent, Outdent, Delete (or Tab / Shift+Tab while editing).
• Nested sub-items use two leading spaces per level in the JSON.
• Add item appends a line at the root level.
• Use [label](https://url) for links (click the link when not editing).

When checklist items exist, progress is calculated from how many are checked. With no checklist items, set progress on the Details tab.

Notes (Markdown)

Notes are stored as Markdown in the task JSON description field. In the task detail editor they appear in the right pane, rendered by default (headings, lists, bold, code, links).

Markdown	Rendered
# Heading	Heading
**bold** / *italic*	Formatted text
`inline code`	Monospace span
Fenced code blocks (triple backticks)	Code block
- item or 1. item	Bullet or numbered list
> quote	Blockquote
[label](https://url)	Clickable link (opens in browser)

Click Edit notes to swap the right pane to an in-place Markdown text editor (auto-saves as you type). Click Preview (or press Escape) to return to the rendered view. Content stays in the task JSON — no .md file on disk. KachiBox: Open Task Notes still opens notes in VS Code’s native markdown editor if you prefer that.

Collapsible header and footer

Click Search & filters at the top of the Tasks panel to expand or collapse focus chips, optional statistics, search, filters, and the view menu. Click Actions at the bottom to expand or collapse + Global Task, + Project Task, Save to Git, and storage info. When the footer is collapsed, the bar shows the current task count (e.g. 3 tasks). Your choices are remembered for the session so the task list can use more space. MCP enable/connection lives in the separate MCP sidebar view.

Statistics

Turn on ⋯ → Statistics to show a single compact line below the focus chips (off by default). Counts use all tasks on disk, not only the filtered list. The line always shows active; other segments appear only when their count is greater than zero (e.g. 5 active · 2 today · 1 overdue · 3 done/wk · 12 closed). Your show/hide choice is remembered for the session.

Focus views

When kachibox.showFocusViews is enabled (default), focus chips appear above the search box inside the expanded header: All, Today, Overdue, Blocked, In progress, and Meeting actions (KaigiBox-linked tasks). Set kachibox.showFocusViews to false in settings to hide them.

Chip	Shows
All	Every active task (respects search and Filters)
Today	Due date is today (local calendar)
Overdue	Due date before today
Blocked	Status is Blocked (or legacy blocked: true)
In progress	Status is In Progress

Focus combines with search, status/priority/label/storage filters, and sort. Switching to Closed resets focus to All.

Search, filters, and sort

Search — filters by title, Notes, checklist item text, and labels (case-insensitive substring).

Filters — open from ⋯ → Filters (or when filter chips are active). Status, priority, labels (all selected labels must match), and Storage (Project / Global) when both stores are active.

Sort — Manual, Updated, Created, Priority, Due date, Title, or Progress. Use ↑ / ↓ for direction (hidden for Manual sort).

Manual reorder — set sort to Manual, then drag by the grip on the right of each card. Order is saved in the task file (order; lower values appear higher). New tasks are inserted at the top.

View menu (⋯) — next to search: Condensed cards, Closed list, Filters, Select tasks (bulk actions), Statistics, Export to Markdown…, and Import from Markdown…. Sort options are in the same menu below a separator.

Export and import

Action	What it does
Export to Markdown…	Saves the currently visible task list (search, filters, focus, active/closed mode, sort) to a .md file. Each task becomes a ## section with optional notes and checklist lines.
Import from Markdown…	Creates new tasks from a file. KachiBox export files round-trip metadata (status, priority, labels, due date). Any file with ## headings splits into multiple tasks; a checklist-only file (lines like - [ ] / - [x]) becomes one task titled from the filename. You choose project or global storage when both are available.

Commands: KachiBox: Export Tasks to Markdown and KachiBox: Import Tasks from Markdown (also on the Tasks panel title bar).

Bulk actions — ⋯ → Select tasks, then choose tasks (checkbox or card click), then Mark done, Set priority, or Add label. Use All / Clear to select the visible list. Not available on the Closed view.

Highlights

Condition	Appearance
Past due	Yellow (due date before today)
Blocked	Red; set status Blocked on the Details tab

Settings

Open with the gear on the panel, KachiBox: Open Settings, or VS Code Settings → kachibox.

Setting	Default	Description
kirokubox.homeDirectory	(empty → ~/.kirokubox)	Shared global home for KaigiBox and KachiBox (meetings/, config/, tasks/); registered by KaigiBox — set in KaigiBox/KirokuBox settings or settings.json
kachibox.storageLocation	automatic	automatic — both project (.vscode/tasks) and global tasks in one list; project or global — single store
kachibox.newTaskStorage	project	Default store for KachiBox: New Task from the command palette when both stores are visible
kachibox.tasksDirectory	~/.kirokubox/tasks	Global tasks directory (machine scope). Supports ~ and %ENV_VAR%.
kachibox.gitSyncTarget	both	Which task folder(s) Save to Git uses to find git repos (both, project, or global); each sync commits the whole worktree, not only tasks/
kachibox.showFocusViews	true	Show All / Today / Overdue / Blocked / In progress / Meeting actions chips above search
kachibox.syncLinkedActions	true	Sync linked task title, assignee, and due date with KaigiBox meeting actions
kachibox.showStatusBar	true	Active / overdue / blocked summary in the status bar
kachibox.dueDateNotifications	true	Notify for tasks due today (and overdue summary)
kachibox.autoRefresh	true	Refresh when files change on disk
kachibox.mcp.enabled	false	Start a local MCP HTTP server so AI agents can manage tasks
kachibox.mcp.port	3847	Preferred localhost port (0 = ephemeral). Falls back if busy

Legacy DevPad settings (devpad.tasksDirectory, devpad.autoRefresh) still work as fallbacks. Data in ~/.kachibox or ~/.kaigibox migrates to ~/.kirokubox on first activation.

MCP (AI agents)

KachiBox can expose a Model Context Protocol server on the local machine so any MCP client (VS Code Copilot / Agent, Claude Desktop, and others) can read and update tasks while the extension is running.

1. Open the MCP view in the KachiBox sidebar (or run KachiBox: Show MCP). When the server is running, a status-bar chip also opens this view.
2. Turn on Enable (sets kachibox.mcp.enabled).
3. Copy the URL, token, or client config into your MCP client’s HTTP server settings.

The server listens on http://127.0.0.1:<port>/mcp only (not the public network). Every request needs Authorization: Bearer <token>. The token is stored in VS Code Secret Storage (not in settings.json). Regenerate token invalidates previous clients.

Tools:

Category	Tools
Query	list_tasks, get_task, get_task_stats, list_labels, get_storage_info, get_task_file_path, get_git_status
CRUD	create_task, update_task, append_notes, complete_task, reopen_task, archive_task, delete_task (requires confirm: true), move_task, reorder_tasks
Labels	add_label, remove_label
Checklist	list_checklist, add_checklist_item, set_checklist_item, toggle_checklist_item, remove_checklist_item, reorder_checklist_item, indent_checklist_item
Bulk	bulk_complete_tasks, bulk_set_status, bulk_set_priority, bulk_add_label, bulk_archive_tasks
UI	open_task_window, close_task_window, save_active_task_window
Git	sync_to_git (requires confirm: true; may stage the whole repo root)

list_tasks supports search, multi status/priority, labels, focus views (today, overdue, …), and sort. Checklist tools prefer itemIndex (0-based among items). UI tools open/close the editor task detail panel and flush pending autosave from the active window.

Inside VS Code, KachiBox also registers itself via the MCP server definition provider so the built-in agent can discover it when the server is running.

Example HTTP MCP client entry (after Copy client config):

{
  "kachibox": {
    "url": "http://127.0.0.1:3847/mcp",
    "headers": { "Authorization": "Bearer YOUR_TOKEN" }
  }
}

Theming

KachiBox follows your active VS Code theme: sidebar background, text, inputs, accent highlights (button / focusBorder colors), list surfaces, and priority/status colors use workbench tokens. Switch themes in VS Code and the Tasks panel updates automatically (reload the webview if it was open during the switch).

With default settings and a workspace open, you see project and global tasks together. Open a task → Actions → Move to project or Move to global to relocate its JSON file (same task id; the list updates after refresh). Each card shows a P or G badge on the right, just left of the drag grip (grip appears when sort is Manual). Use Filters → Storage to show only one type. The footer has + Global Task and + Project Task side by side. The footer shows Project: {name} + Global in mixed mode.

Per-repo tasks — with default settings, open a project folder and tasks live beside your code. The .vscode/tasks folder is created only when you add a Project Task (or move a task into the project)—opening the workspace alone does not create it.

my-repo/
  .vscode/
    tasks/
      2026/
        2026-05-31-ship-feature.json

Commit .vscode/tasks if you want tasks in git with the repo, or ignore that folder in .gitignore for personal-only tasks.

Sync across machines (global) — set kachibox.storageLocation to global and point kachibox.tasksDirectory at a cloud folder:

{
  "kachibox.storageLocation": "global",
  "kachibox.tasksDirectory": "D:/CloudSync/kachibox/tasks"
}

Task files

Tasks are grouped by creation year under the active tasks directory (project or global):

~/.kirokubox/tasks/
  2026/
    2026-05-31-ship-kachibox-v1.json
  2025/
    2025-12-15-year-end-wrap-up.json

Naming: {YYYY-MM-DD}-{title-slug}.json — files rename when you change the title (with a short id suffix if the name collides).

• JSON in the detail header — edit the file in VS Code.
• Open folder in the footer — open the tasks directory in your file manager.

Example file:

{
  "id": "a1b2c3d4e5f67890",
  "title": "Ship KachiBox v1",
  "description": "Polish UI and publish",
  "status": "in-progress",
  "priority": "high",
  "labels": ["kachibox"],
  "progress": 50,
  "blocked": false,
  "order": 1000,
  "createdAt": "2026-05-31T12:00:00.000Z",
  "updatedAt": "2026-05-31T14:30:00.000Z",
  "dueDate": "2026-06-07",
  "checklist": "- [x] Build UI\n- [ ] Write docs"
}

Field	Values / meaning
status	todo, in-progress, blocked, done, archived
priority	low, medium, high, urgent
blocked	Mirror of status === "blocked" (kept for older JSON / consumers)
order	Manual sort (lower = higher in list)
closedAt	Set when marked done or archived

Git sync

If the task folder(s) selected by kachibox.gitSyncTarget are inside a git repo, Save to Git appears in the footer.

gitSyncTarget	Which folder(s) start sync
both (default)	Project .vscode/tasks and global folder, each if it is in a git working tree
project	Only the workspace .vscode/tasks folder
global	Only the global tasks directory

For each selected folder, KachiBox finds the git repository root and stages/commits the entire worktree (not only files under tasks/). That way a shared home like ~/.kirokubox (with tasks/, meetings/, and config/) does not leave sibling changes uncommitted.

• Uncommitted changes — accent border, dot, and hint text when the repo that contains the selected target(s) has any dirty files.
• With upstream — commit all local changes → pull --rebase --autostash → push.
• Without upstream — local commit only.
• Commit messages — task-only: Task updates: …; meeting-only (shared repo): Meeting updates: …; mixed: KirokuBox updates: … with counts and a bullet list in the body.
• Conflicts — if pull/rebase/push fails, KachiBox shows numbered recovery steps, lists conflicted files, and offers Open tasks folder in the footer and in the error notification.

Project tasks usually commit into your workspace repository (everything dirty in that repo, not only .vscode/tasks). Global tasks commit into whatever repo contains your global tasks path (often ~/.kirokubox itself).

Keyboard shortcuts

Default keybindings (rebind in File → Preferences → Keyboard Shortcuts, search kachibox):

Shortcut (Windows / Linux)	Mac	Command	When
Ctrl+Alt+T	Cmd+Alt+T	Show Tasks	Anywhere
Ctrl+Alt+N	Cmd+Alt+N	New Task	Anywhere
Ctrl+Shift+K	Cmd+Shift+K	Quick Capture	Anywhere
Escape	Escape	Close task detail	Click inside Tasks panel; an editor detail tab is active
Alt+↓ / Alt+↑	Alt+↓ / Alt+↑	Next / previous task	Click inside Tasks panel; list has tasks
Ctrl+Shift+Enter	Cmd+Shift+Enter	Mark task done	Click inside Tasks panel; active editor detail is an open task
Ctrl+Alt+F	Cmd+Alt+F	Focus search	Click inside Tasks panel

Panel shortcuts are handled inside the webview (sidebar webviews do not receive VS Code’s webviewFocused key chords). Click the task list so the sidebar has focus before using them.

Next / previous opens the next task in an editor detail tab and wraps at the ends of the current filtered list. Mark done applies to the task whose detail tab is active (checklist completed, task closed). Close closes that active detail tab.

Quick capture

Capture tasks without opening a detail editor tab.

Command	What it does
KachiBox: Quick Capture	Title-only prompt → saved immediately (uses kachibox.newTaskStorage)
KachiBox: Capture Selection as Task	Editor selection → task (see rules below)

Default keybinding: Ctrl+Shift+K / Cmd+Shift+K anywhere in VS Code (see Keyboard shortcuts).

Selection → task rules:

• One short line → task title
• One long line → shortened title + full line in description
• Multiple lines → first line title, rest in description
• No selection → same as Quick Capture (title prompt)

KachiBox: New Task still opens a detail editor tab with the title focused (full edit flow).

Status bar

When kachibox.showStatusBar is enabled (default), the status bar shows a live summary, for example:

$(checklist) 5 active · 1 today · 2 overdue · 1 blocked

• Warning background when any task is overdue
• Error background when any active task is blocked (and none overdue)
• Click the item (or run KachiBox: Show Tasks) to open the Tasks sidebar

Counts refresh when task files change on disk.

Due-date notifications

When kachibox.dueDateNotifications is enabled (default), KachiBox shows a VS Code notification if you have active tasks due today or overdue:

• One summary shortly after VS Code starts (if anything is due or overdue)
• Again when a new task becomes due today (same calendar day)
• Periodic re-check every 30 minutes while VS Code is open

Notifications include View Tasks (opens KachiBox) and Dismiss. Overdue-only days use a warning-style notification.

Set "kachibox.dueDateNotifications": false in settings to turn them off.

Commands

Command	Description
KachiBox: Show Tasks	Open the KachiBox sidebar
KachiBox: View Overview	Screenshots and quick tour (command palette)
KachiBox: New Task	Create a task (opens detail editor tab)
KachiBox: Quick Capture	Fast title-only capture
KachiBox: Capture Selection as Task	Task from selected editor text
KachiBox: Export Tasks to Markdown	Export the filtered list to .md
KachiBox: Import Tasks from Markdown	Import tasks from .md
KachiBox: Open Task Notes	Open notes in VS Code’s native markdown editor (optional; detail pane also edits in place)
KachiBox: Refresh	Reload from disk
KachiBox: Open Settings	Extension settings (gear on the Tasks panel)
KachiBox: Show Log	Output → KachiBox (scan warnings, resolved paths)
KachiBox: Show MCP	Focus the MCP sidebar view (enable server, copy URL/token/client config)

Panel shortcuts (Close detail, Next / previous task, Mark done, Focus search) are listed under Keyboard shortcuts.

Troubleshooting

Issue	Try
Tasks not updating	Refresh; check kachibox.autoRefresh
MCP client cannot connect	Enable MCP in the MCP view; copy a fresh token; confirm URL is 127.0.0.1 and VS Code is running; check Output → KachiBox
Wrong folder	Check kachibox.storageLocation and kachibox.tasksDirectory; project tasks are under .vscode/tasks
Typing loses focus	Reload the window if title/description reset
Git sync failed	Read the notification; git status in tasks folder
Bad JSON file	Fix or remove it; KachiBox skips unreadable files — details in Output → KachiBox or KachiBox: Show Log
Missing tasks / wrong folder	KachiBox: Show Log lists project/global paths at activation; check kachibox.tasksDirectory on Remote/WSL
No tasks in Remote - WSL	Extension runs in Linux: use a WSL path (/mnt/c/Users/.../tasks), not C:\.... Set kachibox.tasksDirectory under the Remote (WSL) settings scope, not only Windows.
Settings gear shows empty list	Reinstall or use a current build; settings filter must match publisher BeagleRidgeLLC (@ext:BeagleRidgeLLC.kachibox). Search kachibox in Settings as a fallback.

License

MIT