claude-issueops

claude-issueops

Persist session context and decisions across Claude Code sessions via GitHub Issues.

English | 日本語

Status: v0.1.0 released — continuity hooks, the session-closer skill (capture / close), the decision marker protocol, and cross-issue memory escalation are all on master. L3 acceptance verified (Epic #7 closed). A marketplace listing will follow. Origin: this is the OSS extraction of insight-blueprint#132.

What & Why

Claude Code sessions lose context at five predictable boundaries: session start, mid-session drift, automatic compaction, session end, and the next session start. Existing memory mechanisms cover personal preferences but not "what was I doing on this issue, and why did we decide X instead of Y?". claude-issueops makes the GitHub Issue itself the persistent memory layer: hooks read recent comments at session start and after compaction, and a skill captures decisions back to the issue when the session ends. Cross-issue knowledge escalates to Claude's standard memory as reference entries.

Install

Via Claude Code marketplace (recommended)

/plugin marketplace add etoyama/claude-issueops
/plugin install claude-issueops@claude-issueops

(etoyama/claude-issueops is shorthand for the GitHub repo; the SSH form git@github.com:etoyama/claude-issueops.git also works.)

Skills are namespaced under the plugin name, so commands appear as /claude-issueops:<skill> once installed.

Locally for development

git clone https://github.com/etoyama/claude-issueops.git
claude --plugin-dir ./claude-issueops

--plugin-dir loads the plugin without going through the marketplace machinery; useful when iterating on the plugin itself.

A community marketplace listing (Anthropic's claude-plugins-community) is tracked in #60.

Quickstart

1. Work on a branch named after an issue, e.g. feat/132-session-continuity.
2. Open Claude Code. The first prompt of the session triggers a briefing: a one-line list of in-progress issues, plus the current issue's body excerpt and any prior decisions.
3. Make decisions. When you reach a meaningful conclusion, run /claude-issueops:session-closer --capture to extract and post the decision as a comment on the current issue.
4. End the session with /claude-issueops:session-closer (no flag). The skill captures any remaining decisions, posts a session summary, and escalates cross-issue learnings to Claude's standard memory.

If you forget to invoke the skill, a SessionEnd hook posts a minimal summary as a fallback.

Decision marker protocol

Decisions are recorded as issue comments using a frozen format. The format is part of the protocol and must not be customized; downstream tooling depends on the exact shape.

## Decision: <kebab-case-slug>

**What:** <one sentence describing what was decided>
**Why:** <reasoning, constraints, or motivation>
**Alternatives considered:**
- <option> -> <reason for rejection>
**Consequences:** <what this gains, what this gives up, what may break later>

Extraction uses two combined regexes: ^## Decision: (?<slug>[a-z0-9-]+)\s*$ for the heading, immediately followed by ^\*\*What:\*\* to reject false positives (quoted text, code blocks).

A slug is kebab-case, unique within the issue. Re-using a slug requires deleting or rewriting the prior comment by hand; the capture flow refuses to overwrite.

Configuration

Defaults ship with the plugin. Override per-project in .claude/settings.json:

{
  "issueops": {
    "stateDir": "${CLAUDE_PROJECT_DIR}/session-state",
    "branch": {
      "issuePattern": "(?:feat|fix|chore|refactor)/(\\d+)-",
      "fallback": "latest-in-progress"
    },
    "projects": {
      "enabled": false
    },
    "memory": {
      "escalate": true,
      "type": "reference"
    }
  }
}

Key	Default	Purpose
stateDir	${CLAUDE_PROJECT_DIR}/session-state	Per-session state file location. Must be gitignored. CLAUDE_PROJECT_DIR is the env var Claude Code exposes to plugin scripts.
branch.issuePattern	(?:feat|fix|chore|refactor)/(\d+)-	Regex with one capture group for the issue number.
branch.fallback	latest-in-progress	What to do when the pattern does not match. Alternative: none.
projects.enabled	false	Opt in to GitHub Projects v2 integration (added in v0.2).
memory.escalate	true	Whether cross-issue decisions are written to Claude's standard memory.
memory.type	reference	Memory type to use when escalating.

Hooks behavior

Three hooks ship in v0.1: