ADR 0012 — Zero-Token Issue Viewer Hook¶
Status¶
Accepted
Context¶
Checking open issues during a Claude Code session requires prompting Claude, which consumes tokens and adds latency even though the task is pure data retrieval (no LLM reasoning needed).
Claude Code's UserPromptSubmit hook can intercept prompts before they reach the model. Exit code 2 blocks the model entirely — the hook output is shown to the user and zero tokens are spent.
Decision¶
Add a UserPromptSubmit hook (my-issues-hook.py) that intercepts short trigger phrases (issues, my issues, open issues, show issues, gh issues) and prints a formatted issue list from Linear and GitHub, then exits 2.
The backing data script (my-issues.py) runs standalone or is called by the hook.
Data sources¶
- Linear (primary): queries all workspace issues per team via GraphQL, filtered to non-completed/non-canceled states, sorted oldest-first
- GitHub (optional): enumerates repos via
gh repo list, then pulls open issues per repo withgh issue list --sort created --order asc
Trigger → behavior¶
| Prompt | Behavior |
|---|---|
issues / my issues / open issues / show issues |
Linear only |
gh issues |
Linear + GitHub |
Linear API key discovery order¶
LINEAR_API_KEYenv var~/.config/linear/key(plain text file)- Falls back to GitHub-only with a note
Files¶
| Repo path | Installed to |
|---|---|
scripts/my-issues.py |
~/tools/my-issues.py |
claude/hooks/my-issues-hook.py |
~/.claude/hooks/my-issues-hook.py |
Hook is registered in ~/.claude/settings.json under hooks.UserPromptSubmit.
Consequences¶
- Zero LLM tokens spent on issue lookups
- Requires
LINEAR_API_KEYin environment for Linear results - GitHub requires
ghCLI authenticated (gh auth login) --limit Nflag controls max issues per team/repo (default 15)