pi-session-context

A pi coding agent extension that tracks and displays what the agent is working on in the footer — worktree, Jira ticket, GitLab/GitHub MR, pipeline status, MR review activity, or any custom key.

🌿 my-repo  feat/SDK-1234-fix-auth   📋 SDK-1234   🔀 #771   🟡 deploy   🔍 deploy  1/2

Entries are clickable OSC 8 hyperlinks in supported terminals. Pipeline and MR monitor icons update automatically as status changes.

How it works

Context entries are stored as a map. Each entry has a value, an optional type that controls rendering, and an optional icon:

type	rendering	value
"dir"	git root + branch (branch is a clickable link to the remote)	filesystem path
"link"	clickable hyperlink with a friendly label	full URL
(omit)	icon key value plain text	anything

The agent calls set_context with a map of entries to update. Keys not mentioned are left unchanged. Pass value: "" to clear a key. An optional label field overrides the auto-derived display text for link entries.

Well-known keys

Three keys have default icons and extra behaviour:

key	icon	extra behaviour
worktree	🌿	Sets the bash working directory — no cd needed
ticket	📋	—
mr	🔀	—

Any other key is shown with · as the default icon.

Passive detection

The extension scans every tool call for paths inside PI_WORKTREE_BASE. When a worktree path is found it automatically sets worktree and detects the branch — no explicit set_context call needed.

---

Use cases

Worktree

Use type: "dir" with the worktree key. The extension resolves the git root, detects the current branch, and reads the remote URL so the branch name becomes a clickable link.

The bash tool is automatically redirected to run from that directory for the rest of the session.

{
  "context": {
    "worktree": {
      "value": "~/Development/worktree/my-repo/feat/SDK-1234-fix-auth",
      "type": "dir",
      "icon": "🌿"
    }
  }
}

Renders as: 🌿 my-repo feat/SDK-1234-fix-auth (branch links to https://gitlab.example.com/…/-/tree/feat/SDK-1234-fix-auth)

Clearing the worktree key also resets the bash CWD back to the session default:

{ "context": { "worktree": { "value": "" } } }

---

Jira ticket

Use type: "link" with the full Jira issue URL. The extension extracts the ticket key (SDK-1234) as the display label and renders it as a clickable hyperlink.

{
  "context": {
    "ticket": {
      "value": "https://myorg.atlassian.net/browse/SDK-1234",
      "type": "link",
      "icon": "📋"
    }
  }
}

Renders as: 📋 SDK-1234 (clickable, opens the issue in the browser)

---

GitLab / GitHub MR or PR

Use type: "link" with the full MR or PR URL. The extension extracts the number and displays it as #771.

{
  "context": {
    "mr": {
      "value": "https://gitlab.example.com/myorg/my-repo/-/merge_requests/771",
      "type": "link",
      "icon": "🔀"
    }
  }
}

Renders as: 🔀 #771 (clickable, opens the MR in the browser)

Works identically for GitHub pull requests (/pull/42 → #42).

---

Custom entries (plain text)

Any key without a type is displayed as icon key value. Useful for tracking things like environment, target branch, or task status.

{
  "context": {
    "env":    { "value": "staging", "icon": "🌐" },
    "target": { "value": "develop", "icon": "🎯" }
  }
}

Renders as: 🌐 env staging 🎯 target develop

---

Pipeline monitoring

Use monitor_pipeline after triggering a CI/CD pipeline. The extension fetches the status immediately, shows a live clickable badge in the footer, and polls until the pipeline finishes. A pi notification fires on completion.

When the pipeline fails, the extension automatically injects a user message so the agent responds without manual intervention. Use notify_on to control which terminal statuses trigger a prompt (default: ["failed"]). Set auto_prompt: false to suppress all prompts.

{
  "url":              "https://gitlab.com/org/repo/-/pipelines/12345",
  "label":            "deploy",
  "interval_seconds": 30,
  "auto_prompt":      true,
  "notify_on":        ["failed"]
}

Supported URL formats:

Platform	Pattern
GitLab pipeline	https://<host>/group/project/-/pipelines/ID
GitLab job	https://<host>/group/project/-/jobs/ID
GitHub Actions run	https://github.com/owner/repo/actions/runs/ID

Self-hosted GitLab is supported — any host is accepted.

Status icons — update automatically in the footer:

Icon	Status
⏳	pending / queued
🟡	running
✅	success
❌	failed
⊘	canceled
⏭	skipped
⚠️	fetch error (bad token / network)

---

MR / PR monitoring

Use monitor_mr after opening a merge request to track review activity without polling manually. The extension polls every 1 minute by default (configurable, min 15s) and updates the footer with the live approval ratio.

{
  "url":              "https://gitlab.example.com/myorg/my-repo/-/merge_requests/771",
  "label":            "deploy",
  "interval_seconds": 60,
  "auto_prompt":      true
}

Supported URL formats:

Platform	Pattern
GitLab MR	https://<host>/group/project/-/merge_requests/IID
GitHub PR	https://github.com/owner/repo/pull/NUMBER

What is tracked:

Event	Footer	Notification	Auto-prompt
New source-code (diff) comments	💬 deploy 1/2	✅	✅ (if auto_prompt: true)
All required approvals met	✅ deploy 2/2	✅	✅ (if auto_prompt: true)
Approval count changes	🔍 deploy 1/2 → 2/2	—	—
MR merged	🎉 deploy merged	✅	✅ (if auto_prompt_merged: true)
MR closed	🚫 deploy closed	✅	—

Approval ratio — displayed as x/y in the footer label:

• GitLab: sourced from the /approvals endpoint (approved_by / approvals_required)
• GitHub: unique approvers from /reviews; required count from branch protection (cached after first fetch, shown as x/? if unavailable)

Comment tracking: only source-code / diff comments count (inline review threads). General MR description comments are ignored. All comments present at registration are marked as already seen — only comments added after monitor_mr is called trigger notifications.

Status icons:

Icon	Status
🔍	monitoring
💬	new comments detected
✅	fully approved
🎉	merged
🚫	closed
⚠️	fetch error

---

Removing monitors

stop_monitor works for both pipeline and MR monitors — identify by label:

{ "label": "deploy" }

Interactive removal via slash commands:

Command	Covers
/pipeline-monitors	Pipeline monitors
/mr-monitors	MR / PR monitors

---

Putting it all together

A typical full workflow — start work, open MR, monitor pipeline and reviews:

// set_context — starting work
{
  "context": {
    "worktree": { "value": "~/Development/worktree/my-repo/feat/SDK-1234-fix-auth", "type": "dir" },
    "ticket":   { "value": "https://myorg.atlassian.net/browse/SDK-1234", "type": "link" }
  }
}

// set_context — after MR is opened
{
  "context": {
    "mr": { "value": "https://gitlab.example.com/myorg/my-repo/-/merge_requests/771", "type": "link" }
  }
}

// monitor_pipeline — after push
{ "url": "https://gitlab.example.com/myorg/my-repo/-/pipelines/12345", "label": "deploy" }

// monitor_mr — track review activity
{
  "url":   "https://gitlab.example.com/myorg/my-repo/-/merge_requests/771",
  "label": "deploy"
}

Footer: 🌿 my-repo feat/… 📋 SDK-1234 🔀 #771 🟡 deploy 🔍 deploy 0/2

When the task is done, clear everything:

{
  "context": {
    "worktree": { "value": "" },
    "ticket":   { "value": "" },
    "mr":       { "value": "" }
  }
}

// stop_monitor — removes both pipeline and MR monitors by label
{ "label": "deploy" }

---

Installation

pi install npm:pi-session-context
# or directly from GitHub:
pi install git:github.com/it-ony/pi-session-context

Configuration

Variable	Default	Description
PI_WORKTREE_BASE	~/Development/worktree	Base directory scanned for git worktrees
GITLAB_TOKEN	—	GitLab personal access token (read_api scope). Required for private projects.
GITHUB_TOKEN	—	GitHub personal access token. Required for private repos.
PI_MONITOR_DEFAULT_INTERVAL	10	Default pipeline poll interval in seconds (min 5).

Set in your shell config (e.g. ~/.config/fish/config.fish or ~/.zshrc):

export PI_WORKTREE_BASE="$HOME/code/worktrees"

License

MIT