# link-ticket-to-session

Adopt this skill: https://proskills.md/skills/other/jayantdevkar-claude-code-karma-skills-link-ticket-to-session

Page: https://proskills.md/skills/other/jayantdevkar-claude-code-karma-skills-link-ticket-to-session
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/link-ticket-to-session/SKILL.md
size: 7276
upstream: https://github.com/jayantdevkar/claude-code-karma/blob/main/skills/link-ticket-to-session/SKILL.md

````text
---
name: link-ticket-to-session
description: Link the current Claude Code session to a ticket (Linear, Jira, GitHub Issues, or GitHub Pull Requests) and cache its title/status in karma. Use when the user explicitly asks to link, attach, associate, or connect this session to a ticket, issue, or PR — e.g. "/link-ticket-to-session ABC-123", "link this session to LINEAR-42", "associate this work with issue #15", "attach session to PR octocat/repo#7". Do NOT auto-invoke from passing ticket-key mentions in normal conversation.
argument-hint: <ticket-ref-or-url>
allowed-tools: Bash, mcp__linear, mcp__claude_ai_Linear, mcp__plugin_github_github, mcp__atlassian
---

You are linking the current Claude Code session (`${CLAUDE_SESSION_ID}`) to: **$ARGUMENTS**

Karma is a read-only observer on the user's machine. It stores the link
and caches title/status for display, but never writes back to the ticket
provider. You fetch metadata via the user's already-configured MCP server.

Karma's API URL comes from `KARMA_API_URL` (set by users on non-default
ports/hosts) with `http://localhost:8020` as fallback. Inline
`${KARMA_API_URL:-http://localhost:8020}` in **every** curl below — bash
variables don't persist across separate Bash tool calls, so a top-of-script
assignment would be empty by the time the next curl runs.

## Step 1 — Parse $ARGUMENTS

Recognized forms:

| Provider           | Short ref           | URL forms                                              |
|--------------------|---------------------|--------------------------------------------------------|
| Linear             | `LINEAR-123`        | `https://linear.app/.../issue/ABC-123`                 |
| Jira               | `PROJ-45`           | `https://*.atlassian.net/browse/PROJ-45`               |
| GitHub **Issue**   | `owner/repo#42`     | `https://github.com/owner/repo/issues/42`              |
| GitHub **PR**      | `owner/repo#42`     | `https://github.com/owner/repo/pull/42`                |

GitHub issues and pull requests share a single numbering namespace —
`owner/repo#42` could be either. **The URL kind (`/issues/` vs `/pull/`)
is the only signal**, and karma's backend preserves it, so when you have
a URL keep it intact when POSTing (Step 4). For a bare `owner/repo#N`
with no URL, default to `/issues/N` — GitHub auto-redirects to `/pull/N`
when N is actually a PR, so the link still resolves.

A bare `#N` (no owner/repo) is **not** accepted — always qualify with
`owner/repo#N`.

## Step 2 — Identify provider and (for GitHub) kind

Set two variables you'll use below:

- `<provider>` ∈ `linear` | `jira` | `github`
- For GitHub: `<kind>` ∈ `issue` | `pull_request` (derived from URL path)

For Linear and Jira this collapses to just `<provider>`.

## Step 3 — Fetch metadata via MCP (when available)

Pick the right MCP tool for the provider and kind:

| Provider · Kind             | MCP tool                                                |
|-----------------------------|---------------------------------------------------------|
| `linear`                    | Linear MCP — search/fetch issue by key                  |
| `jira`                      | Atlassian MCP — fetch by key                            |
| `github` · `issue`          | `mcp__plugin_github_github__issue_read`, method `get`   |
| `github` · `pull_request`   | `mcp__plugin_github_github__pull_request_read`, method `get` |

Calling the wrong GitHub method silently returns the wrong thing because
both shapes look superficially similar — so derive the kind first.

If the relevant MCP isn't installed, **skip this step** and proceed to
Step 4 without title/status. Karma will create the link; the title/status
fields stay NULL and can be refreshed later via Step 5.

Pull at minimum: `title`, `status` (or state), `url`. **Strip large
fields** — karma caps `metadata_json` at 64 KB and a full PR payload
easily exceeds that. Specifically drop:

- GitHub PR: `body`, `commits`, `files`, `reviewers`, `comments`, `labels`,
  `requested_reviewers`, `head` / `base` blobs beyond `ref`
- GitHub issue: `body`, `comments`, `reactions`, `labels`
- Linear / Jira: `description`, `comments`, `subscribers`, `attachments`

### Status semantics by kind

The `status` you cache should reflect *what the provider says now*, not a
generic "open/closed". Karma's UI normalizes these to canonical buckets
at render time, so faithful provider language is the right input:

- **Linear**: workflow state name verbatim — e.g. `Backlog`, `In Progress`,
  `In Review`, `Done`, `Cancelled` (workspace-defined; don't normalize).
- **Jira**: workflow state name — e.g. `To Do`, `In Progress`, `In Review`,
  `Done`.
- **GitHub issue**: `open` or `closed`.
- **GitHub PR**: derive from the flags the PR API returns:

  | `state`  | `draft` | `merged` | Cache as     |
  |----------|---------|----------|--------------|
  | `open`   | `true`  | —        | `draft`      |
  | `open`   | `false` | —        | `open`       |
  | `closed` | —       | `true`   | `MERGED`     |
  | `closed` | —       | `false`  | `closed`     |

## Step 4 — POST the link

The `url` field should be the URL you actually have — `/pull/N` for PRs,
`/issues/N` for issues. **Don't rewrite it.** Karma's parser preserves
the path segment; the UI uses it to distinguish PRs from issues.

```bash
curl -s -X POST "${KARMA_API_URL:-http://localhost:8020}/sessions/${CLAUDE_SESSION_ID}/tickets" \
     -H 'Content-Type: application/json' \
     -d '{"ref":"<key>","provider":"<provider>","url":"<url>","source":"slash_command"}'
```

For GitHub, `<key>` is always `owner/repo#N` regardless of kind — the
URL field carries the issue/PR distinction.

## Step 5 — PUT the metadata (only if Step 3 succeeded)

```bash
curl -s -X PUT "${KARMA_API_URL:-http://localhost:8020}/tickets/<provider>/<key>" \
     -H 'Content-Type: application/json' \
     -d '{"title":"<title>","status":"<status>"}'
```

For GitHub keys with `/` and `#`, URL-encode the key in the path:
`octocat/repo#42` → `octocat%2Frepo%2342`.

## Step 6 — Confirm to the user

One line. For GitHub, distinguish the kind so the user knows what they
just attached:

- `Linked session to LINEAR-123 (Fix login bug, In Progress) — open at https://linear.app/...`
- `Linked session to PROJ-45 (Migrate auth, Done) — open at https://acme.atlassian.net/browse/PROJ-45`
- `Linked session to octocat/repo#42 [issue] (Empty state lies, open) — open at .../issues/42`
- `Linked session to octocat/repo#42 [PR] (Fix linting, MERGED) — open at .../pull/42`

## Notes

- Karma is loopback-only by default. `KARMA_API_URL` overrides for custom
  port or remote host.
- POST is idempotent on `(session, ticket)`; re-running upgrades the
  `link_source` if previously set by branch-detect or dashboard. Order:
  `slash_command > dashboard > branch`.
- If the API is unreachable, tell the user
  `karma not running at ${KARMA_API_URL:-http://localhost:8020}` so they
  see what was tried. Don't silently succeed.
- GitHub issues and PRs sharing `#N` means a single karma row (one
  `(provider, external_key)` pair) covers both views of that number.
  The URL field is what tells karma's UI which one to render. Send the
  URL you actually have.
````

## File: README.md
upstream: https://github.com/jayantdevkar/claude-code-karma/blob/main/README.md

```text
<p align="center">
  <img src="docs/screenshots/banner.png" alt="Claude Code Karma" width="200" />
</p>

<h1 align="center">Claude Code Karma</h1>

<p align="center">
  <strong>Your Claude Code sessions deserve more than a terminal.</strong><br />
  A local-first, open-source dashboard that turns your <code>~/.claude/</code> data into a visual story — sessions, timelines, costs, and live activity, all on your machine.
</p>

<p align="center">
  <a href="https://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache-2.0" /></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10+-blue.svg" alt="Python 3.10+" /></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node-18+-green.svg" alt="Node 18+" /></a>
  <a href="https://kit.svelte.dev/"><img src="https://img.shields.io/badge/SvelteKit-2-FF3E00.svg" alt="SvelteKit 2" /></a>
</p>

<br />

<p align="center">
  <a href="docs/screenshots/home.png" target="_blank">
    <img src="docs/screenshots/home.png" alt="Claude Code Karma Dashboard" width="100%" />
  </a>
</p>

## Why Claude Code Karma?

If you use Claude Code, you already have a goldmine of data sitting in `~/.claude/` — every session, every tool call, every token. But it's all buried in JSONL files you'll never read.

> **Warning: Claude Code only keeps session data for about 30 days.** Older JSONL files in `~/.claude/projects/` are automatically cleaned up. Since Karma reads directly from those files, deleted sessions will disappear from the dashboard too.

Claude Code Karma reads that local data and gives you a proper dashboard. No cloud. No accounts. No telemetry. Just your data, on your machine.

It works with both **Claude Code CLI** and **Claude Desktop** (Claude Code mode) sessions — any session that writes to `~/.claude/` shows up automatically.

## Features

### Session Browser

Browse all your Claude Code sessions in one place. Search by title, prompt, or slug. Filter by project. See live sessions at the top with real-time status badges — and a `>_` button that raises the terminal window a live session is running in.

<p align="center">
  <img src="docs/screenshots/sessions.png" alt="Session Browser" width="100%" />
</p>

### Session Timeline & Overview

Dive into any session to see exactly what happened — every prompt, tool call, thinking block, and response laid out chronologically. The overview tab shows key stats like message count, duration, model used, and which tools were called.

<p align="center">
  <img src="docs/screenshots/session-overview.png" alt="Session Overview" width="100%" />
</p>

<p align="center">
  <img src="docs/screenshots/session-timeline.png" alt="Session Timeline" width="100%" />
</p>

### Session Detail Tabs

Each session page has dedicated tabs that break down different aspects of what happened during the session.

**Tasks** — See all tasks Claude created and completed during the session, displayed in a flow view with status tracking.

<p align="center">
  <img src="docs/screenshots/session-tasks.png" alt="Session Tasks" width="100%" />
</p>

**Files** — Every file operation in a sortable table — reads, writes, edits — with timestamps, actors, and the tools that made each change.

<p align="center">
  <img src="docs/screenshots/session-files.png" alt="Session Files" width="100%" />
</p>

**Subagents** — Agents spawned during the session, grouped by type. Expand each to see message counts, tool calls, and what they were asked to do.

<p align="center">
  <img src="docs/screenshots/session-subagents.png" alt="Session Subagents" width="100%" />
</p>

**Skills** — Skills invoked via `/skill` commands during the session, with their source plugin and invocation count.

<p align="center">
  <img src="docs/screenshots/session-skills.png" alt="Session Skills" width="100%" />
</p>

**Shells** — Long-running background shells spawned during the session, with live status, the command each one ran, and runtime.

<p align="center">
  <img src="docs/screenshots/session-shells.png" alt="Session Shells" width="100%" />
</p>

**Analytics** — Per-session cost breakdown, token usage, cache hit rates, tool distribution with a donut chart, and a ranked list of every tool used.

<p align="center">
  <img src="docs/screenshots/session-analytics.png" alt="Session Analytics" width="100%" />
</p>

### Projects

See all your Claude Code workspaces organized by git repository. Each project card shows session count and when it was last active. Expand git repos to see individual project directories inside them.

<p align="center">
  <img src="docs/screenshots/projects.png" alt="Projects" width="100%" />
</p>

### Analytics

Track your token usage, costs, velocity trends, cache hit rates, and coding rhythm across all projects. See which models you use most and how your usage patterns change over time.

<p align="center">
  <img src="docs/screenshots/analytics.png" alt="Analytics Dashboard" width="100%" />
</p>

### Tools & MCP

See every tool Claude Code uses — built-in ones like Read, Edit, and Bash, plus any MCP integrations you've added (the **MCP** page in the nav). Grouped by server with call counts and session coverage. Switch to the Usage Analytics tab for activity trends and top tools over time.

<p align="center">
  <img src="docs/screenshots/tools.png" alt="Tools Browser" width="100%" />
</p>

<p align="center">
  <img src="docs/screenshots/tool-analytics.png" alt="Tool Usage Analytics" width="100%" />
</p>

Click into any tool for detailed stats — total calls, session count, main vs subagent split, usage trend over time, and a full session history.

<p align="center">
  <img src="docs/screenshots/tool-detail.png" alt="Tool Detail" width="100%" />
</p>

<p align="center">
  <img src="docs/screenshots/tool-history.png" alt="Tool History" width="100%" />
</p>

### Agents

Browse all your agents — built-in, custom, and plugin-provided. See total runs, token consumption, and filter by category to understand how your agent ecosystem is being used. The Usage Analytics view shows activity trends and your most-used agents.

<p align="center">
  <img src="docs/screenshots/agents.png" alt="Agents Browser" width="100%" />
</p>

<p align="center">
  <img src="docs/screenshots/agent-analytics.png" alt="Agent Usage Analytics" width="100%" />
</p>

Drill into any agent for run counts, token usage, average duration, usage trends, project breakdown, and a session history showing every time that agent was used.

<p align="center">
  <img src="docs/screenshots/agent-detail.png" alt="Agent Detail" width="100%" />
</p>

<p align="center">
  <img src="docs/screenshots/agent-history.png" alt="Agent History" width="100%" />
</p>

### Hooks

Visualize all your Claude Code hooks organized by lifecycle phase — session start/end, tool use, agent lifecycle, and permissions. See which hooks can block execution and how many registrations each event has.

<p align="center">
  <img src="docs/screenshots/hooks.png" alt="Hooks Browser" width="100%" />
</p>

### Plugins

View all installed Claude Code plugins with their agents, skills, and commands. Filter between official and community plugins. See version info and when each was last updated.

<p align="center">
  <img src="docs/screenshots/plugins.png" alt="Plugins Browser" width="100%" />
</p>

Click into any plugin to see everything it provides — agents, skills, commands, MCP tools, and hooks — along with usage analytics showing activity trends and top-used components.

<p align="center">
  <img src="docs/screenshots/plugin-detail.png" alt="Plugin Detail" width="100%" />
</p>

<p align="center">
  <img src="docs/screenshots/plugin-analytics.png" alt="Plugin Usage Analytics" width="100%" />
</p>

### Skills

Track which skills are invoked across sessions, grouped by plugin or shown individually. Click into any skill for usage stats, context split (main vs subagent), and a full sess
```
