{"id":49716101,"url":"https://github.com/ytrofr/claude-code-quest","last_synced_at":"2026-05-08T20:00:52.415Z","repository":{"id":356326182,"uuid":"1232002690","full_name":"ytrofr/claude-code-quest","owner":"ytrofr","description":"RPG-style project roadmap dashboard for Claude Code users — themed maps, auto-progress from plan checkboxes, multi-project tracking, zero dependencies","archived":false,"fork":false,"pushed_at":"2026-05-07T14:45:47.000Z","size":88,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-07T16:37:44.077Z","etag":null,"topics":["anthropic","anthropic-claude","claude-code","dashboard","developer-tools","gamification","kanban-alternative","localhost-app","multi-project","personal-knowledge-management","productivity","project-management","python","roadmap","rpg","self-hosted","solo-developer","static-site","todo-list","zero-dependencies"],"latest_commit_sha":null,"homepage":"https://github.com/ytrofr/claude-code-quest#install","language":"Go Template","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ytrofr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T13:48:29.000Z","updated_at":"2026-05-07T15:01:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ytrofr/claude-code-quest","commit_stats":null,"previous_names":["ytrofr/claude-code-quest"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ytrofr/claude-code-quest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ytrofr%2Fclaude-code-quest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ytrofr%2Fclaude-code-quest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ytrofr%2Fclaude-code-quest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ytrofr%2Fclaude-code-quest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ytrofr","download_url":"https://codeload.github.com/ytrofr/claude-code-quest/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ytrofr%2Fclaude-code-quest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32795416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","anthropic-claude","claude-code","dashboard","developer-tools","gamification","kanban-alternative","localhost-app","multi-project","personal-knowledge-management","productivity","project-management","python","roadmap","rpg","self-hosted","solo-developer","static-site","todo-list","zero-dependencies"],"created_at":"2026-05-08T20:00:20.282Z","updated_at":"2026-05-08T20:00:52.403Z","avatar_url":"https://github.com/ytrofr.png","language":"Go Template","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code Quest\n\n\u003e RPG-style project roadmap dashboard for Claude Code users — themed maps, auto-progress from plan checkboxes, multi-project tracking, zero dependencies.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Zero dependencies](https://img.shields.io/badge/deps-zero-brightgreen.svg)](#architecture-choices-and-what-we-said-no-to)\n\n**Live demo URL** (after install): \u003chttp://localhost:8770\u003e\n\n---\n\n## What is this?\n\nA localhost dashboard that turns your Claude Code plans into a gamified visual roadmap. Each project becomes a themed map; each plan becomes a quest with status, tasks, branch, KPI, and \"Why this matters.\" A small `/quest` skill manages the data; an async hook keeps it in sync with your `~/.claude/plans/*.md` files automatically — **without ever calling an LLM.**\n\nYou see all your projects at a glance, click into any quest, expand a deed to read its problem → solution. Filter by status, swap themes, drop in your own.\n\n## Who is this for?\n\n- **Solo devs juggling 3+ codebases** under one Claude Code install — you're losing track of what's blocked vs in-progress vs shipped, and you want a single visual.\n- **Multi-project freelancers / consultants** who plan work via plan files and want a dashboard that updates itself when you check off boxes.\n- **Anyone using Claude Code's plan mode** seriously — if you write `~/.claude/plans/*.md` files, this turns them into a navigable game world.\n\n## How is this different from Linear / Notion / Trello / Jira?\n\n| | Quest | Linear | Notion | Trello | Jira |\n|---|---|---|---|---|---|\n| Lives offline / localhost | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Reads plans you already write | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Zero LLM tokens / API cost | ✅ | n/a | n/a | n/a | n/a |\n| Account / login required | ❌ | ✅ | ✅ | ✅ | ✅ |\n| Themable (drop-in folders) | ✅ | ❌ | partial | ❌ | ❌ |\n| Built for one person | ✅ | ❌ (team) | partial | partial | ❌ (team) |\n| Setup time | \u003c2 min | ~15 min | ~10 min | ~5 min | hours |\n| Your data leaves your machine | ❌ | ✅ | ✅ | ✅ | ✅ |\n\nIt's not trying to compete with team-issue trackers. It's the personal layer above your codebases — the bird's-eye view you can't get from `git log` or your editor's tab bar.\n\n## What's in the box\n\n| Component | What |\n|---|---|\n| `/quest` skill | `status`, `init`, `add`, `update`, `done`, `theme`, `style`, `render`, `reset`, `chapters` subcommands |\n| Hand-rolled renderer | Zero-dep Python (~430 LOC). `{{var}}`, `{{#each}}`, `{{#if}}`, `{{\u003e partial}}` |\n| Two ready themes | Pokémon (cartoon, Fredoka) + Storybook (parchment, Eczar) — 3 views × 7 landmark SVGs each |\n| Shared partials | `_back-link`, `_taskslist`, `_meta-row`, `_progress-bar`, `_pills`, `_why`, `_next-step` |\n| Trainer Hall home index | Pokémon-themed card grid at `/` — one card per project with level pill, gold XP bar, 3 stat pills, \"Currently Battling\" callout, and Begin Adventure + Pokédex buttons. Per-project `accent` (hex) + `icon` (landmark) overrides via `/quest style`. |\n| Click-to-expand briefs | Each task and the next-step expand to show \"Problem → Solution\" sentences |\n| Multi-select status filter | Active / Visited / Sealed pills toggle independently on quest-log, persisted per-project in `localStorage`. Plus \"Show All\" / \"Active Only\" quick-actions. |\n| Hide-done deeds toggle | Per-quest plan-card has a \"Hide done\" toggle that hides ticked sub-tasks; shares the same `localStorage` key as the status filter. |\n| Storyline rendering | Plan-card meta box shows **Sequel to** ◀ (predecessors from `depends_on`), **Leads to** ▶ (auto-computed successors), and **Plans** (originating plan + sub-plans). Quest names are clickable links. |\n| Auto-progress hook | PostToolUse async, parses `## Section 13` checkboxes into `tasks[]` + `progress` — **zero LLM calls** |\n| Plan sub-bullet parser | `- [x] Title` followed by `- Problem: …` / `- Solution: …` becomes click-expandable detail |\n| systemd unit | localhost:8770, hardened (`ProtectSystem=strict`), auto-starts on boot |\n\n## Install\n\n```bash\ngit clone https://github.com/ytrofr/claude-code-quest ~/claude-code-quest\ncd ~/claude-code-quest\n./install.sh\n```\n\nThen:\n1. Edit `~/.claude/quest/config.json` to add your real project paths\n2. Wire the hook in `~/.claude/settings.json` (see below)\n3. Open \u003chttp://localhost:8770/\u003e\n\n### Wiring the hook\n\nAdd to `~/.claude/settings.json` under `hooks.PostToolUse`:\n\n```json\n{\n  \"matcher\": \"Write|Edit\",\n  \"hooks\": [\n    {\"type\": \"command\", \"command\": \"/home/YOU/.claude/hooks/quest-plan-autosync.sh\", \"async\": true}\n  ]\n}\n```\n\nThe hook only fires on writes to paths matching `*/plans/*.md` or `*/.claude/plans/*.md` — everything else exits in microseconds.\n\n## How it works\n\n```\n┌─────────────────────┐    write plan    ┌──────────────────────┐\n│  ~/.claude/plans/   │ ───────────────\u003e │ quest-plan-autosync  │  (PostToolUse async)\n│  \u003cfeature\u003e.md       │                  │     ~30ms / no LLM   │\n└─────────────────────┘                  └──────────┬───────────┘\n                                                    │\n                                                    v\n                                ┌────────────────────────────────────┐\n                                │    autosync.py                     │\n                                │    1. resolve project (BLUF/path)  │\n                                │    2. parse §13 checkboxes         │\n                                │    3. parse Problem:/Solution:     │\n                                │       sub-bullets per checkbox     │\n                                │    4. extract git branch + commit  │\n                                │    5. update or add quest          │\n                                │    6. trigger render               │\n                                └─────────────────────┬──────────────┘\n                                                      │\n                                                      v\n┌────────────────────┐                 ┌──────────────────────────┐\n│ quests.json (v2)   │ \u003c─── source ─── │ render.py                │\n│ central truth      │                 │ → site/\u003cid\u003e/{route,log,  │\n└────────────────────┘                 │           plan-card}.html│\n                                       └──────────────┬───────────┘\n                                                      │\n                                                      v\n                                           localhost:8770 (systemd)\n```\n\n## Themes — drop-in extensible\n\nAdding a third theme is dropping a folder. The renderer scans `themes/*/theme.json`. Each theme provides:\n\n```\nthemes/\u003cname\u003e/\n  theme.json          # { name, version, positions: { \"1\": \"translate(x,y)\", ... } }\n  route.html.tmpl     # full-page map view\n  quest-log.html.tmpl # listing view (with filter bar)\n  plan-card.html.tmpl # per-quest detail (with click-expand briefs)\n  landmarks/\n    house.svg.tmpl   tower.svg.tmpl   mill.svg.tmpl\n    bridge.svg.tmpl  camp.svg.tmpl    cave.svg.tmpl   castle.svg.tmpl\n```\n\nShared partials (`themes/_shared/_*.html.tmpl`) cover cross-theme structure — themes provide CSS for the `qd-*` class hooks. See `skills/quest/themes/README.md` and `docs/theming.md`.\n\n## Data schema (v2)\n\n`quests.json` per-quest, all v2 fields optional:\n\n| Field | Type | Source |\n|---|---|---|\n| `id`, `n`, `name`, `desc`, `landmark`, `status`, `progress`, `xp_reward`, `plan`, `next_step` | core | hand-set or `/quest` |\n| `tasks[]` | `[{title, done, problem?, solution?}]` | auto-parsed from plan §13 checkboxes + sub-bullets |\n| `last_touched` | ISO8601 | auto-set by autosync |\n| `branch`, `last_commit{sha,msg,date}` | git | auto-pulled from local repo |\n| `why`, `kpi` | string | hand-set |\n| `next_step_problem`, `next_step_solution` | string | hand-set |\n| `blockers[]`, `tags[]`, `depends_on[]`, `links[{project,quest}]` | arrays | hand-set |\n| `effort{estimate_hr,actual_hr}` | object | hand-set |\n\nSee `examples/quests.json` for fully-populated samples (apollo, atlas, nova) and `docs/data-schema.md` for the full reference.\n\n## Plan markdown — auto-progress shape\n\nWrite your plans normally. Sub-bullets under each checkbox become click-expandable briefs:\n\n```markdown\n## Section 13 — Post-Validation\n- [x] Wire OAuth callback handler\n  - Problem: Google deprecated the old endpoint; existing flow throws 400.\n  - Solution: Migrate to /v3 endpoint + update redirect URI in console.\n- [ ] Add session refresh middleware\n  - Problem: Tokens expire mid-request, causing silent 401s.\n  - Solution: Refresh proactively at 90% TTL with sliding window.\n```\n\nThe hook parses checkbox state → `progress`, sub-bullets → `problem` / `solution` per task. Backward-compatible: plain checkboxes without sub-bullets render as non-clickable rows.\n\n## Natural-language triggers (with Claude Code)\n\nOnce installed, an auto-loaded rule teaches Claude to recognize:\n\n| You say | Claude runs |\n|---|---|\n| \"what's the status of apollo?\" | `/quest status` + cites the URL |\n| \"mark X done\" | `/quest done \u003cproject\u003e \u003cid\u003e` |\n| \"switch atlas to pokemon theme\" | `/quest theme atlas pokemon` |\n| Write a plan with `**Project**: \u003cid\u003e` BLUF | quest auto-appears, no command needed |\n\n## FAQ\n\n**Does this cost anything?** No. Everything runs on your machine. Zero LLM calls, zero API tokens, zero cloud services.\n\n**Does my data leave my machine?** No. The systemd service binds to `127.0.0.1:8770`, the JSON lives in `~/.claude/quest/data/`, and the public engine repo only ships fictional example data (apollo, atlas, nova). Your real projects stay private.\n\n**Do I need to run Claude Code for it to work?** No. Once installed, the dashboard runs as a systemd service. The auto-progress hook only fires inside Claude Code sessions, but you can run `/quest` commands manually anytime.\n\n**Can I add my own theme?** Yes — drop a folder under `themes/\u003cname\u003e/` with a `theme.json`, three view templates, and seven landmark SVGs. The renderer auto-discovers it. See `docs/theming.md`.\n\n**Does it work on Windows / macOS?** Linux + WSL fully supported (systemd unit included). macOS and Windows: the renderer + skill work fine, but you'll need to start the static server manually (`python3 -m http.server 8770 --directory ~/.claude/quest/site`) instead of via systemd. Or use `launchd` (macOS) or NSSM (Windows) — PRs welcome.\n\n**What's the difference between Quest and Linear / Trello?** Linear and Trello are team issue trackers — they assume a server, accounts, multi-user collaboration. Quest is the personal birds-eye layer above your codebases — it reads plans you already write, runs offline, costs nothing. See the comparison table above.\n\n**How do I add a new project?** Run `/quest init \u003cid\u003e`, edit `~/.claude/quest/config.json` to add the path mapping, optionally drop a `quest-link.md` pointer in the project's `.claude/` dir. See `docs/adding-projects.md`.\n\n**Can the parser handle nested plans / Hebrew / non-English content?** Yes. UTF-8 throughout. The parser only looks for the `- [x]`/`- [ ]` checkbox pattern in `## Section 13`; it doesn't care what's between the brackets.\n\n## Architecture choices (and what we said NO to)\n\n- ✅ Zero-dep Python renderer — no jinja, no node, no build step\n- ✅ Static HTML output — `python3 -m http.server` is enough; no Flask/FastAPI\n- ✅ systemd-managed service — restart, logging, lifecycle handled\n- ✅ Local-only dashboard — bound to 127.0.0.1; no external surface\n- ✅ Vanilla JS for filter UI — no framework, ~25 lines, accessible (`role=\"tab\"`, `aria-selected`)\n- ❌ No tiered XP — flat 25 per quest, cosmetic only\n- ❌ No LLM-driven progress — pure markdown parsing; never burns tokens\n- ❌ No auto-edits to your plans — read-only consumption\n- ❌ No remote sync — git the data file if you want it synced\n- ❌ No JS framework / npm — keeping the install footprint near zero\n\n## Repo layout\n\n```\nclaude-code-quest/\n├── README.md           ← you are here\n├── LICENSE             ← MIT\n├── CITATION.cff        ← academic citation metadata\n├── install.sh          ← one-shot installer\n├── skills/quest/       ← the skill (SKILL.md + 3 .py + themes/)\n├── hooks/              ← quest-plan-autosync.sh\n├── systemd/            ← quest-dashboard.service template\n├── examples/           ← sample quests.json + config.json\n├── docs/               ← theming, schema, adding-projects guides\n└── .github/            ← issue templates\n```\n\n## Contributing\n\nThemes welcomed. PRs that add: new theme directory + landmarks + minimal docs in `themes/\u003cname\u003e/README.md`. Keep zero-dep philosophy — if it needs npm install, it's a different project.\n\nBug? Open a [bug report](https://github.com/ytrofr/claude-code-quest/issues/new?template=bug_report.yml). Idea? File a [feature request](https://github.com/ytrofr/claude-code-quest/issues/new?template=feature_request.yml).\n\n## License\n\nMIT — see `LICENSE`.\n\n---\n\n\u003csub\u003eTags: claude-code, anthropic, project-management, roadmap, dashboard, rpg, gamification, developer-tools, productivity, todo-list, multi-project, kanban-alternative, zero-dependencies, self-hosted, localhost-app, solo-developer, personal-knowledge-management\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fytrofr%2Fclaude-code-quest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fytrofr%2Fclaude-code-quest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fytrofr%2Fclaude-code-quest/lists"}