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, or any custom key.

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

Entries are clickable OSC 8 hyperlinks in supported terminals. Pipeline icons update automatically as the build progresses.

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.

{
  "url":              "https://gitlab.com/org/repo/-/pipelines/12345",
  "label":            "deploy",
  "interval_seconds": 30
}

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)

Removing a monitor:

• Agent: call stop_monitor({ label: "deploy" })
• User: type /pipeline-monitors → interactive list → select → confirm

---

Putting it all together

A typical agent call when starting work on a ticket:

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

After pushing and opening the MR, add it. Then kick off CI and monitor it:

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

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

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

When the task is done, clear everything:

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

Stop any remaining monitors:

// stop_monitor
{ "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