pending-issues

Cross-session deferred-issue ledger for AI coding agents. Track work that escaped the current task; survive the clear.

pending-issues is a Claude Code / OpenCode / Codex plugin that maintains a single markdown ledger (<cwd>/pending-issues.md) tracking work you want to defer. The ledger is auto-injected at session start (Claude Code) or surfaced through the skill description (other agents), so the next session picks up exactly where the last one stopped.

Why this exists

Deferred work gets lost between AI sessions. CLAUDE.md and MEMORY.md are too coarse; GitHub Issues are too heavy for in-repo TODOs. You need a structured, queryable, file-format-stable ledger that:

• Auto-loads on every new session
• Standardizes entries with IDs, priority, status
• Auto-archives resolved entries (max 10 most recent, older ones to yearly archives)
• Supports arbitrary filter queries (/pending-issues --priority high --files backend)
• Imports known issues from other agents (Codex, OpenCode, project AGENTS.md, gh issue list, git grep)
• Works across Claude Code, OpenCode, and Codex with one shared core

Features

• Single-file convention — one pending-issues.md per project, no user-level file
• Auto-injection — Claude Code SessionStart hook reads the ledger into every new session; other agents load via the SKILL.md description
• Structured entries — id (auto-assigned, pi-NNN), priority (critical/high/medium/low), status (pending/in-progress/resolved), files, source, description, optional added_by/resolution_date/verification
• Auto-archive — Resolved section keeps the 10 most recent; older entries move to pending-issues-archive-YYYY.md
• Short pointers in Pending — resolved entries leave an HTML comment pointer (<!-- pi-001: short summary — resolved YYYY-MM-DD -->) so you see the history at a glance
• Arbitrary filter args — /pending-issues --priority high --status pending --files backend --since 2026-05-01 ...
• Custom file path — PENDING_ISSUES_FILE env var (or /pending-issues set-path <dir> with migration confirmation); the file-header <!-- pending-issues-path: ... --> comment is a self-documenting marker
• Init-time import — scan Codex / OpenCode / project AGENTS.md / gh issue list / git grep for existing TODOs and let the user pick which to import
• Multi-agent — Claude Code, OpenCode, and Codex; each gets a directory-isolated install path
• Cross-platform — scripts in shell and Python; works on Windows / macOS / Linux
• Zero external dependencies — no npm, no pip packages; just a python3 in PATH for the import script

Installation

Prerequisites

The install scripts and hooks are bash + Python based. Most macOS and Linux users have both out of the box. Windows users should install Git for Windows (provides bash) or run under WSL; the SessionStart and PostToolUse hooks invoke bash and will silently no-op if bash is not on PATH.

You don't install this plugin yourself. You tell the AI in your coding agent session:

Install the pending-issues skill from https://github.com/shawn-web/pending-issues

The AI handles everything:

1. Detects your agent (Claude Code / OpenCode / Codex).

2. git clones the repo into a temp directory.

3. Runs the right adapter for your agent:

   Agent	What happens
   Claude Code	claude plugin marketplace add <url> + claude plugin install pending-issues@shawn-web
   OpenCode	git clone into ~/.config/opencode/skills/pending-issues/; OpenCode auto-discovers the SKILL.md
   Codex	git clone into $CODEX_HOME/skills/pending-issues/; append AGENTS.md snippet; auto-patch config.toml

4. Verifies the install and reports back.

If you'd rather do it manually, see docs/manual-install.md — but for the common case, just tell the agent the URL.

The repository ships a .claude-plugin/marketplace.json so Claude Code treats it as a marketplace and one-shot installs pending-issues. OpenCode and Codex have no equivalent CLI, so the AI uses git clone to a path the agent already auto-discovers.

Quick start

You:  What pending issues are there?
AI:   The ledger at ./pending-issues.md is empty (or has N pending entries).

You:  Add a pending issue: the Vite build is 3MB from unused d3 imports
AI:   Appended pi-001 to Pending. Priority default medium; status pending.

You:  Mark pi-001 as resolved — I cleaned up the d3 imports
AI:   Moved pi-001 to Resolved; verification: build size dropped to 1.8MB.

You:  /pending-issues --priority high --status pending
AI:   Lists matching entries in priority order.

File format

See skills/pending-issues/references/format-spec.md for the full schema. A minimal example:

# Pending Issues

<!-- pending-issues-version: 0.1.1 -->
<!-- pending-issues-path: ./pending-issues.md -->

## Pending

### [2026-06-09] Object.values(Map) drops geo_position writes
- **id**: pi-001
- **priority**: high
- **status**: pending
- **description**: `Object.values(modelMap)` returns `[]` for `Map` instances, so `manager.save(SceneModel, [])` writes nothing.
- **source**: e2e failure in geo-maps test
- **files**: `backend/src/scenes/scenes.service.ts:batchUpdateModels`
- **added_by**: claude-session-2026-06-09

## Resolved

### [2026-05-12] Camera frustum clipping on small screens
- **id**: pi-002
- **priority**: medium
- **status**: resolved
- **resolution_date**: 2026-06-01
- **verification**: `pnpm test viewer` passes; manual test on 1024x768 viewport

Slash command reference

/pending-issues [filters...]

Filters (combinable, any number):
  --priority <critical|high|medium|low>
  --status   <pending|in-progress|resolved>
  --id       <pi-NNN>
  --files    <substring>          # match in files field
  --source   <substring>          # match in source field
  --since    <YYYY-MM-DD>         # added on or after
  --until    <YYYY-MM-DD>         # added on or before
  --resolved-since <YYYY-MM-DD>   # resolved on or after
  --limit    <N>                  # cap results
  --sort     <priority|date|status>
  --format   <table|list|json>

Subcommands:
  /pending-issues set-path <dir>    # change file location, with migration prompt
  /pending-issues archive           # force archive of old resolved entries
  /pending-issues import            # scan other agents for known issues

How it differs from...

Tool	Purpose	Boundary with this plugin
CLAUDE.md	Project-level permanent instructions	orthogonal — doesn't change between sessions
MEMORY.md (claude-mem)	Cross-session observation memory	memory = past observations; pending-issues = actionable to-dos
make-plan skill	Plan the current task	plans = current work; pending-issues = deferred work
GitHub Issues	Heavyweight tracking for teams	GitHub Issues = cross-repo, async; pending-issues = single-project, in-session

Architecture

pending-issues/
├── skills/pending-issues/        # shared core (used by all 3 agents)
│   ├── SKILL.md                  # main instructions
│   ├── references/               # format-spec, workflow, triggers, filter-syntax, archive-policy
│   ├── assets/                   # templates
│   ├── examples/                 # worked examples
│   └── scripts/                  # detect-agent, inject-context, import-issues, archive-resolved, validate-format
└── adapters/                     # per-agent thin adapters
    ├── claude-code/              # hooks + install scripts
    ├── opencode/                 # opencode.json fragment + install
    └── codex/                    # config.toml snippet + AGENTS.md + install

Each agent's install puts the skill in its own dedicated directory (~/.claude/skills/pending-issues/ / ~/.config/opencode/skill/pending-issues/ / ~/.codex/skills/pending-issues/), so no agent reads another agent's config.

Configuration

Knob	Where	Default	Notes
File location	PENDING_ISSUES_FILE env var	<cwd>/pending-issues.md	Highest priority
File location	<!-- pending-issues-path: ... --> in file header	(inherits env var / default)	Parsed at runtime by scripts/_lib.sh:resolve_ledger_path
Archive cap	Hard-coded	10	Resolved section size; older → archive file
Archive year	Auto	Current year	pending-issues-archive-YYYY.md
Trigger phrases	SKILL.md description	25+ phrases	See references/triggers.md

Security

The install scripts in adapters/ are file-copy only (no eval, no curl | bash); they just cp -r the skill into the agent's directory and edit a small JSON/TOML config. The remaining risk is the same as any git clone && bash install.sh workflow: always review the repo before cloning. If you only want to read the plugin, you can browse the skills/pending-issues/ and adapters/ directories directly without running any installer.

Known limitations

• Single agent per <cwd>: two AI agents writing to the same pending-issues.md concurrently can race on the resolved/archived counts and corrupt the file. Run only one agent on a given project directory at a time. If you need to work on the same project with multiple agents, give each its own worktree (or a separate copy of the directory) and merge the ledgers later by hand. An advisory lock file is planned for v0.2.0; see references/workflow.md for the long-form discussion.
• Plugin version vs. ledger version drift: the <!-- pending-issues-version: X.Y.Z --> header in your ledger is informational only; the AI is expected to read it and offer to migrate, but it does not auto-migrate. v0.1.x ledgers stay forward-compatible.
• Trigger phrases in the SKILL.md description are the authoritative list. Adding the same phrase to the custom triggers config files (user-level or project-level) is a no-op; the built-in matcher already covers it.

Contributing

The file format (<cwd>/pending-issues.md) is the public API. Backward compatibility is a hard requirement. Open issues / PRs against main.

License

MIT — see LICENSE.