Task Beacon
A lens for owned work — not another place to run it.
Official, Private, and Agent in one VS Code sidebar.
Keep Jira, Hermes, Claude Code, GitHub Actions, and OpenCode. A wiki folder is enough.
Agents already have boards and crons. Companies already have Jira. Personal work already lives in a vault. Those stay where they are.
Task Beacon does not replace them. It reads a wiki folder, optional Jira, and the local job files those tools already write — then shows company, personal, and agent work as one tree you can filter and open.
That is the product: one sidebar, three owners, the files you already have. You do not need Jira, and you do not need Hermes.
Why it stays easy
- Install and look. Click the beacon icon. Sample Official / Private / Agent rows are already there. A Get Started walkthrough opens after install.
- A folder is enough. Point at the vault or repo root that contains
Tasks/. Wiki tasks show up with no agent runtime and no Jira.
- Skip what you do not use. Jira, Hermes, AI, and Grafana stay empty until you fill them. Official still works from wiki notes tagged
official.
- Filter, then open. Cycle All → Official → Private → Agent. Click a row to open the Jira ticket, the markdown task, or the cron script.
- Agents use the same files. Any agent writes
Tasks/*.md (category: agent-task or agent-cron) and optionally .task-beacon/jobs.json. See AGENTS.md.
Live cron is merged when the files exist: Hermes, Claude Code scheduled_tasks.json, Claude Desktop scheduled-tasks/*/SKILL.md, GitHub Actions on.schedule, OpenCode scheduler files, and .task-beacon/jobs.json. Each job gets a ♥ / 💔 from its own file: did the last due fire happen? Cursor / Codex / Copilot cloud automations are not local files — keep those as wiki agent-cron (and the jobs file if you want a schedule line). Pause / resume / run now are Hermes-only.
The shape is still Jira’s: epics group work, tasks are the items. Inspired by GitLens and Todo Tree, but the unit here is owned work, not comments in source.
| Owner |
What you manage |
| Company (Official) |
Team epics and tasks — wiki official, plus Jira if you use Jira |
| Personal (Private) |
Your own epics and tasks in the wiki |
| Agent |
Agent-owned wiki tasks and recurring jobs. Any agent writes the same files |
Getting started
- Install Task Beacon from the Marketplace, or search the name in Extensions (
Ctrl+Shift+X).
- A Get Started walkthrough opens after install (Command Palette → Task Beacon: Get Started). Follow the steps — samples first, then your folder.
- Click the beacon icon in the Activity Bar. The tree already has sample Official / Private / Agent tasks.
- When you want your own work, pick the vault or repo root (the folder that contains
Tasks/, not Tasks itself). Jira, Hermes, AI, and Grafana stay optional.
Wiki tasks work with no agent runtime. Hermes is optional — one live adapter among several, not the definition of cron.
Command Palette → Task Beacon: Settings...
What you see
The tree is the same epic → task outline Jira uses, split by owner. Cycle owners with the filter (All → Official → Private → Agent).
| Owner |
Epics & tasks from |
Cron |
| Official |
Wiki official (+ Jira only if configured) |
— |
| Private |
Wiki private |
— |
| Agent |
Wiki agent-task / agent-cron |
Hermes, Claude Code, GitHub Actions, OpenCode, .task-beacon/jobs.json |
Wiki tasks can set epic: / epic_link: in frontmatter so they nest under an epic, just like Jira issues with an Epic Link. Items with no epic stay flat.
Click a row to open the ticket, the markdown task, or the cron script.
Next to the tree:
- Summary — details for the selected item, optional AI summary
- Table — sortable grid of the same items
- Chart — counts over time (local snapshot history)
- Cron Runs — recent job output
- Settings — the same setup UI as the command
A bottom Task Beacon panel (same strip as Terminal) shows Official / Private / Agent counters, a matching priority feed, and optional AI insights.
Wiki categories
Each tasks/*.md file can set category: in frontmatter. The extension only displays it.
| Category |
Meaning |
official |
Team / company work |
private |
Personal |
agent-task |
Agent-owned tasks |
agent-cron |
Recurring automation |
Older veda-task / veda-cron values still load; they show as agent-task / agent-cron.
Delegate to an agent
Longer work you do not want to babysit: Task Beacon: Delegate to Agent… (or right-click a task / epic → Delegate to Agent (split this)).
What happens, in files you can read:
- If AI is configured, the brief is split into 1–6 subtasks by kind —
research, analysis, implement, schedule. Without AI you get one task and a note saying so.
- Finished tasks in the same wiki (
status: done) with overlapping words are attached as references — in the frontmatter (refs:) and in the body — so similar work follows the shape that already worked. Set todoView.aiEmbeddingModel to re-rank that shortlist with your provider's /embeddings; if the call fails, word overlap stands.
- Task Beacon writes
Projects/<slug>.md plus Tasks/<slug>-NN-<kind>.md, each category: agent-task. A schedule subtask becomes agent-cron and a row in .task-beacon/jobs.json.
- Each file carries the rules the agent needs: work alone, write under Result, set
status: done or status: blocked.
Running is still your runtime's job. Set todoView.agentRunner to a command template and Run with Agent (or Run n now after delegating) opens a terminal per task:
hermes chat -q "Read {file} and do it. Set status: done when finished."
claude -p "Do the task in {file}. Set status: done when finished."
Only agent-task / agent-cron rows can be handed off. Official and Private never run unattended. Nothing runs if the runner is empty — the files are still written, and the board shows them.
Cron health — is anything still ticking?
Every scheduler dies the same way from the outside: a job's due time passes and no run gets recorded. Hermes, Claude Desktop, and .task-beacon/jobs.json all look "active" in their files long after the process that ticks them is gone. Task Beacon judges each live job from its own file and shows a heart:
- ♥ on time — the last due fire (
next_run, or schedule computed after last_run) was honoured, or is within a 10-minute grace.
- 💔 overdue — the due time passed and no run was recorded since. The scheduler that owns it may be down.
- ♡ unknown — no
next_run and no last_run, or a schedule that is not a cron expression / simple interval.
- ☁ cloud — GitHub Actions and other vendor-ticked jobs. Not checked locally, never shown green.
The heart sits on the Agent root, on the Cron subhead, in a Health row per source (Hermes, Task Beacon, Claude, OpenCode, GitHub Actions), on overdue jobs themselves, in the status bar, and as a bottom-panel tile. Task Beacon: Cron Health… lists the same by source; the Hermes entry can run hermes cron status in a terminal (that CLI cold-starts in ~10 s, so it is never run automatically). Task Beacon does not look at process lists or the OS scheduler — "on time" means the file says it fired, nothing more.
The epic follows its subtasks on every refresh: all done → done; the rest finished but one blocked → blocked; otherwise in-progress. Only epics Task Beacon wrote (type: Epic with delegated:) are updated; hand-written epics are never touched. Both fields live in Settings → Agent.
Requirements
| Need |
Why |
| VS Code 1.80+ |
Extension host |
| Hermes |
Optional. Live feed with pause / resume / run |
| Python 3 |
Only if you use scripts/show_todo.py for Jira |
| A wiki folder |
Obsidian vault with Tasks/*.md, or a repo with scripts/show_todo.py |
Optional — skip anything you do not use:
- Jira — only if your company uses Jira. Official still works from wiki tasks tagged
official (Linear, GitHub Issues, Notion, etc. stay in the wiki).
- AI — xAI (Grok) first, then Ollama, then LiteLLM, OpenAI, or Anthropic. xAI uses the same Hermes login as SuperGrok / X Premium+ (
hermes auth add xai-oauth), not a console API key.
- Grafana / AI Health — set
todoView.grafanaUrl (Settings → AI) to show the bottom AI Health panel with LiteLLM / vLLM stats. Empty keeps the panel hidden. Command: Task Beacon: Open AI Health (Grafana)…
Empty settings stay empty on purpose. No machine paths ship in the install.
Settings
Open Task Beacon: Settings..., or edit these keys:
| Setting |
Default |
Purpose |
todoView.llmWikiRoot |
(empty) |
Vault with Tasks/*.md, or a repo with show_todo.py |
todoView.pythonPath |
python |
Python used to run that script |
todoView.jiraBaseUrl |
(empty) |
Optional Jira site. Empty = Official is wiki-only |
todoView.hermesProfile |
default |
Hermes profile for cron |
todoView.autoRefreshSec |
0 |
Auto-refresh; 0 is off |
todoView.aiProvider |
xai |
xai / ollama / litellm / openai / anthropic |
todoView.aiBaseUrl |
https://api.x.ai/v1 |
OpenAI-compatible API |
todoView.aiApiKey |
sk-local |
Optional. xAI uses Hermes login; local proxies use a proxy key |
todoView.aiDefaultModel |
(empty) |
Default model id |
todoView.grafanaUrl |
(empty) |
Grafana URL. Set it to show the AI Health panel |
todoView.agentRunner |
(empty) |
Command template for Run with Agent: {file}, {title}, {root}. Empty = write files only |
todoView.aiEmbeddingModel |
(empty) |
Embedding model on the same provider to re-rank references. Empty = word overlap |
Useful commands
| Command |
Does |
| Task Beacon: Get Started |
Walkthrough for first-time users |
| Task Beacon: Choose Wiki Folder... |
Folder picker (do not type a path) |
| Task Beacon: Settings... |
Jira, AI, and optional paths |
| Task Beacon: Refresh |
Reload Jira / wiki / cron |
| Task Beacon: Cycle Filter |
All → Official → Private → Agent |
| Task Beacon: Search / Filter Tree... |
Filter the tree |
| Task Beacon: Select AI Model... |
Pick a model when AI is configured |
| Task Beacon: Delegate to Agent... |
Split a brief into agent task files, attach finished references, hand off to your runner |
| Task Beacon: Cron Health... |
♥ / 💔 per scheduler source; open the job file or run hermes cron status |
| Task Beacon: Log in to xAI via Hermes |
Device login (hermes auth add xai-oauth) |
How data is loaded
Wiki tasks come from Tasks/*.md (or tasks/*.md) in the wiki root. If scripts/show_todo.py is present, that script still supplies Jira + wiki JSON.
Live cron is merged from:
- Hermes
jobs.json (profile or %LOCALAPPDATA%\hermes\cron\)
<wiki>/.task-beacon/jobs.json (any agent)- Claude Code
.claude/scheduled_tasks.json (wiki/workspace or ~/.claude)
- Claude Desktop
~/.claude/scheduled-tasks/<name>/SKILL.md (frontmatter, best-effort field names)
- GitHub Actions
.github/workflows/*.yml with schedule
- OpenCode
~/.config/opencode/scheduler/**/jobs/*.json
Agents that only have a cloud scheduler should still write wiki agent-cron and/or .task-beacon/jobs.json. Copy AGENTS.md into the wiki root so the next agent sees the contract.
Charts use an append-only log under the extension’s global storage (history.jsonl). Delete that file to reset the chart.
Develop
npm install
npm run build
Press F5 for an Extension Development Host, or:
npm run package
code --install-extension task-beacon-*.vsix --force
Each package.json version bump on main cuts a GitHub Release (vX.Y.Z + task-beacon-X.Y.Z.vsix) and publishes to the Marketplace when VSCE_PAT is set.
If the repo is damaged, paste AI-RECOVERY.md into a coding agent.
If Task Beacon is useful: github.com/sponsors/YangKangSung.
License
MIT
