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). Lines draw in when the numbers refresh.
- Cron Runs — recent job output, with a moving time marker
- 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. Lanes is on that strip: Hermes sessions on one time axis. Play walks the window. Live keeps the lines and gantt moving from that computer's Hermes database. Prompt text is not read.
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.hermesHome |
(empty) |
Hermes home for Lanes. Empty uses HERMES_HOME, then the local install |
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: Open Hermes Lanes |
Session gantt in the bottom panel. Play and Live animate it |
| 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
