Skip to content

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 with gh 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

  1. LINEAR_API_KEY env var
  2. ~/.config/linear/key (plain text file)
  3. 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_KEY in environment for Linear results
  • GitHub requires gh CLI authenticated (gh auth login)
  • --limit N flag controls max issues per team/repo (default 15)