File-native task coordination for developers and AI agents
Claim, track, and tether your work directly to the repository.
Modern development, especially with AI assistants lacks a simple, shared "source of truth" for what needs to be done, what's in progress, and what's finished. You might have tasks scattered across sticky notes, GitHub issues, Notion pages, chat messages, or your AI agent's context window. None of these live inside your repository where both you and your tools can reliably find them.
The result: duplicated work, missed steps, and broken handoffs between human and AI.
TetherTask keeps tasks where your code lives, inside the repo itself, as plain Markdown files. A sidebar panel gives you a clean visual interface, while the underlying .teather-task/*.md files remain fully human- and machine-readable. No database, no cloud sync, no proprietary format.
Whether it's you managing your own sprint, or an AI agent claiming tasks autonomously, TetherTask gives everyone human and agent alike, a single, transparent place to coordinate.
| Feature | Description |
|---|---|
| File-Based Storage | Tasks live as plain .md files in .teather-task/ — fully readable, diffable, and version-controllable. |
| Sidebar Tree View | Browse all task lists and tasks in a collapsible sidebar panel. |
| Kanban Board View | Visualize tasks in a drag-and-drop board organized by status. |
| Create Task Lists | Generate timestamped task files instantly from the sidebar or Command Palette. |
| Toggle Completion | Click any task to mark it done or undone — the file updates automatically. |
| Inline Editing | Rename tasks directly from the sidebar with the pencil icon. |
| Task Claiming | Claim tasks with your name or agent ID to prevent conflicts. Stale claims auto-release. |
| Live File Sync | Edit .md files directly in your editor — the sidebar refreshes in real time. |
| Cross-Repo Aggregation | Point TetherTask at additional folders outside the current workspace to see tasks from multiple repos. |
| AI-Agent Ready | Agents can read, write, claim, and complete tasks using standard filesystem tools — no special APIs needed. |
TetherTask creates a .teather-task/ folder at your workspace root. Each task list is a Markdown file with a timestamp name:
your-project/
└── .teather-task/
├── 2026-08-14_09-00-task.md
└── 2026-08-01_14-30-task.md
There are two supported file shapes:
Legacy checklist files — created by Create Task List, hold multiple simple tasks per file as standard Markdown checkboxes. These have no owner/priority/claiming concept:
- [ ] Set up CI pipeline
- [x] Initialize project structure
- [ ] Write integration testsRich task files — created by Create Task, hold exactly one task per file, with YAML frontmatter carrying status, priority, and claim metadata. The task's description is the Markdown body below the frontmatter, not a frontmatter field:
---
# ── TetherTask agent protocol — read before editing this file ──
# No locking daemon or server enforces task ownership; this is a
# cooperative, file-based convention. Before acting on this task:
# - If `owner` is set to someone other than you AND `status` is
# `in_progress` or `blocked`, do NOT edit this file — it is claimed.
# - If `status: pending` (owner: null), you may claim it: set `owner`
# to your own name/agent id and `status` to `in_progress`.
# - Only execute the task described below if `owner` equals your own
# name/agent id. Never act on a task owned by someone else.
id: "implement-user-authentication-1755158400000"
status: in_progress
priority: high
owner: claude-code
claimed_at: 2026-08-14T09:12:00Z
created_at: 2026-08-14T09:00:00Z
tags: []
history: []
---
Implement user authenticationstatus is one of pending, in_progress, completed, blocked (underscore, not hyphen). Ownership is tracked via owner, not claimed_by. The leading # comment block is written into every rich task file automatically (see "No locking daemon, by design" below) — you never need to write it by hand.
Human → Creates task via sidebar UI
Agent → Reads .md file → Claims task → Executes → Marks complete
Human → Sees update live in sidebar
Both sides see the same ground truth. No sync required.
TetherTask is distributed through Open VSX — the open extension registry used by VS Code, VSCodium, Windsurf, Cursor, Gitpod, and most non-Microsoft editors that support VS Code extensions.
Status: not yet published — the listing below is where it will live once released. Until then, use Build and Run From Source further down to try it today.
- Open your editor's Extensions panel (
Ctrl+Shift+X). - Search for TetherTask.
- Click Install.
Or install directly from the registry page: open-vsx.org/extension/MrFByte/tethertask.
If your editor only supports the Microsoft Marketplace (e.g. stock VS Code with default settings already does — this is the same install flow), the same steps apply; TetherTask has no editor-specific code.
Want to try it before it's published, or hack on it yourself? Clone and run it directly:
git clone https://github.com/MrFByte/TetherTask.git
cd TetherTask
npm install
npm run compileThen, from VS Code:
- Open the cloned
TetherTaskfolder in VS Code. - Press F5 (or Run → Start Debugging). This launches an Extension Development Host — a second VS Code window with TetherTask already loaded.
- Open any folder/workspace in that new window and use the extension normally (see below).
To install a built copy into your own everyday editor instead of running the dev host, package it into a .vsix and install that:
npx @vscode/vsce packageThis produces tethertask-<version>.vsix in the project root. Install it via the Extensions panel's ⋯ menu → Install from VSIX…, or from the command line:
code --install-extension tethertask-<version>.vsix(Substitute code with code-insiders, codium, or your editor's CLI as needed.)
Open the TetherTask panel in the Activity Bar, then click the + button — or run from the Command Palette:
TetherTask: Create Task List
A new timestamped .md file is created in .teather-task/ and appears in the sidebar immediately.
- Add a task — Click the
+icon next to any task list. - Toggle complete — Click the task name.
- Edit — Hover the task and click the ✏️ icon.
- Delete — Hover the task and click the 🗑️ icon.
- Claim a task — Right-click a task and select Claim Task (or use the Command Palette). Your name or agent ID is recorded in the file.
In Settings (Ctrl+,), search for tethertask.defaultOwner and set it to your name, GitHub username, or agent identifier (e.g. claude-code, cursor). This value is written to any task you claim.
All commands are available via the Command Palette (Ctrl+Shift+P):
| Command | Description |
|---|---|
TetherTask: Create Task List |
Creates a new timestamped task file |
TetherTask: Create Task |
Creates a new rich task with metadata |
TetherTask: Add Task |
Adds a task to the selected list |
TetherTask: Toggle Task Complete |
Toggles a task's completion state |
TetherTask: Edit Task |
Edits a task's text |
TetherTask: Delete Task |
Deletes a task |
TetherTask: Refresh Tasks |
Re-scans and refreshes the sidebar |
TetherTask: Claim Task |
Claims a task under your identity |
TetherTask: Release Task |
Releases a claimed task |
TetherTask: Complete Task |
Marks a claimed task as complete |
TetherTask: Release Stale Claims |
Auto-releases tasks claimed too long ago |
| Setting | Default | Description |
|---|---|---|
tethertask.defaultOwner |
"" |
Your name or agent ID shown when claiming tasks. |
tethertask.staleWarningMinutes |
20 |
Minutes before a claim is highlighted as stale (orange). |
tethertask.staleReleaseMinutes |
30 |
Minutes before a stale claim is auto-released (red). |
tethertask.extraTaskPaths |
[] |
Additional folder paths to scan for .teather-task/*.md files. |
TetherTask is purpose-built for workflows involving AI coding assistants.
Why it works for agents:
- Tasks are plain Markdown — any agent with filesystem access can read and write them without any SDK or API.
- The claiming system guards against two agents (or a human and an agent) working on the same task at once.
- Stale-claim detection means a crashed or stuck agent doesn't block work indefinitely.
- Timestamped filenames make it trivial for an agent to find the most recent task list.
No locking daemon, by design: TetherTask does not run a background lock server or any process to enforce exclusivity. Coordination is a cooperative, file-based convention — an agent claims a task by writing owner/status: in_progress to the file, and every rich (v2) task file carries a short instructional comment inside its own frontmatter explaining exactly that: check owner before touching a task, don't edit one claimed by someone else, and only execute the task you've actually claimed under your own name/agent id. This means the rule travels with the file itself — any agent that reads the file (even one with no prior knowledge of TetherTask) sees the protocol, not just ones that were told about it in advance.
Recommended agent workflow:
1. Agent scans .teather-task/ on startup.
2. Agent claims an open task (writes owner + claimed_at to frontmatter, status: in_progress).
3. Agent executes the task.
4. Agent marks the task complete (status: completed).
5. Human sees the update in the TetherTask sidebar in real time.
- 🎉 Initial release as TetherTask
- Sidebar tree view with collapsible task lists
- Kanban board view
- Create, add, toggle, edit, and delete tasks
- Task claiming with stale-release enforcement
- Live file sync with
.teather-task/*.mdfiles - Cross-repo aggregation via
extraTaskPaths - Full AI-agent compatibility
Contributions, issues, and feature requests are welcome. Please open an issue or submit a pull request on GitHub. See Build and Run From Source above to get set up locally.
Farhan Mahmood
linkedin.com/in/farhan-mahmood-n
MIT — see LICENSE for details.
Built for developers who want their tasks as close to their code as possible.