Session Sitter

see every agent session · switch in one click · supervise what they pause on

Install · First run · Supervision · Docs · Development

A VS Code extension that does two things for your coding agents.

It shows you your sessions. One live panel across
Claude Code,
IBM Bob IDE, Codex and
VS Code Chat — which are alive right now, one click to switch, across windows.

It supervises what they pause on. When an agent stops for approval, it classifies that action
into a traffic light against your team's own practices and acts: approve it, correct it, or reach
you with a countdown. Silence is never approval. Optional — off until you turn it on.

Install

Two commands, from source:

git clone https://github.com/eranra/session-sitter.git
cd session-sitter
make install

That builds the extension and installs it. Then reload the window — Ctrl+Shift+P →
Developer: Reload Window. Done.

make install shells out to code. Point it at any other CLI:

make install CODE=bobide     # IBM Bob IDE
make install CODE=cursor     # Cursor
make install CODE=code-insiders

Grab the .vsix from the latest release, then either:

• In the IDE: Extensions panel → ··· → Install from VSIX…
• From a terminal: code --install-extension session-sitter-*.vsix

Every pull request also attaches a build, under the CI run's Artifacts — handy for trying a
change before it lands.

npm ci        # once
make check    # type-check + lint + 602 tests

Then press F5 for an Extension Development Host with live reloading — no packaging step.
make on its own lists every target.

What you need

Not on the Marketplace yet, so installation is by VSIX.

Upgrading from before 0.5.0? The project was renamed, and every setting now lives under one
sessionSitter.* namespace — earlier names are no longer read. The old-to-new table is in
CHANGELOG.md. Your supervision state directory carries over untouched.

First run

Open the Secondary Sidebar — Ctrl+Alt+B, or View → Secondary Side Bar. The
Session Sitter panel is there. Open a Claude or Bob session and it shows up within seconds.

The main list is a live worklist — only sessions you can act on right now. Claude and Bob are
judged by what their extension hosts report as open, unioned across every window, so a session
open in another window still appears here. Codex and Chat expose no such signal, so they count as
active while recently updated. Everything else moves to History.

Each row carries a status dot: 🟢 running tools · 🟡 waiting on the agent · ⚫ idle, waiting on you.

Supervision (optional)

Coding agents do not stop when you close the laptop. Supervision is for the moments you are not
there: it classifies each action an agent pauses on and acts.

Turning it on takes one setting plus a classifier.

1. In your user settings.json:

{
  "sessionSitter.supervisorStateDir": "/home/you/.ai-sessions/state",   // required
  "sessionSitter.dataRepoPath": "/home/you/work/team-corpus",           // where your rules live
  "sessionSitter.knowledge.user": "your-slug",
  "sessionSitter.knowledge.project": "your-project",
  "sessionSitter.knowledge.team": "your-team"
}

2. Pick a classifier and a channel in your workspace's .env:

SUPERVISOR_ENGINE=bob          # or: claude
BOB_API_KEY=…
MESSAGING_CHANNEL=stub         # writes decision cards to files — try it with no account
# MESSAGING_CHANNEL=telegram   # …then switch to real cards on your phone
# TELEGRAM_BOT_TOKEN=…  TELEGRAM_CHAT_ID=…

3. Write your first rule. Copy
knowledge/bottom-line.template.md to
data/knowledge/teams/<your-team>/bottom-line.md in your corpus repo and edit it.

There is nothing to run. The supervisor runs inside the extension — no daemon, no interpreter,
no background script. Watch decisions land in the Supervision activity panel. Turn it off with
sessionSitter.autoSupervise: false.

→ docs/SUPERVISION.md for the lifecycle, the CLI, and troubleshooting.

Rules that skip the supervisor entirely

Prompts you never want to see again are resolved by rule, before any model call:

"sessionSitter.autoRespond": [
  { "toolPattern": "read_file|list_files|glob|grep", "decision": "approveOnce" },
  { "matchPattern": "Do you want to continue\\?", "response": "Yes" }
]

First match wins. Anything unmatched goes to the supervisor, or stays for you. A user-facing
question is never auto-answered.

Features

• Four sources in one panel — Claude Code, IBM Bob IDE, Codex CLI, VS Code Chat.
• Live status per row, refreshed every 5 s.
• Cross-window switching — clicking a session owned by another window brings that window
  forward.
• Hover preview of the last few messages.
• Copy transcript as handoff-clean markdown: user and assistant prose only, tool calls and
  scaffolding stripped. All four sources.
• Smart titles — Claude's AI-generated title, Bob's task title, Codex's thread name, Chat's
  first request.
• Traffic-light supervision with a deterministic tier, so read-only actions never cost a model
  call.
• Auto-respond and auto-approve rules, scopable per project and per IDE.
• Supervision activity feed — every decision, with failures expanding to their recorded error.
• Upload to corpus — add a session to the store your rules are learned from, secrets redacted
  before anything is committed.

How it finds your sessions

Only by reading what the agents already write — no reimplementation of their internals:

Acting on a blocked session is a different problem: a task waiting at a permission prompt cannot
be reached by a chat message. That path uses each agent's own approval emitter, reached in-process
through the V8 inspector. → docs/ARCHITECTURE.md

Documentation

Development

make with no target lists everything. The ones you will use:

make check      # type-check + lint + 602 tests — the same gate CI applies
make test       # just the tests
make install    # build the .vsix and install it
make package    # build the .vsix without installing
make clean      # remove build output

Everything CI runs is a make target or a script in ci/, so a green pipeline means make check
told you the truth. Tests are vitest: no network, no real agent, no VS Code
instance.

Releasing: bump version in package.json, then push a matching tag —
git tag v0.1.1 && git push origin v0.1.1. CI verifies the tag agrees with package.json, runs
the full gate, and publishes the .vsix to a GitHub Release.

Known limitations

• Linux / WSL for Claude liveness detection — it reads /proc/<pid>/stat. Elsewhere sessions
  still list; the open/closed signal is weaker.
• A new Claude session appears after its first message — that is when Claude Code writes the
  session file.
• Bob cannot report which task is open in its sidebar, so a running task plus a recency window
  is the best available signal.
• Codex and Chat have no liveness signal at all — recency is the proxy
  (sessionSitter.probelessActiveWindowMinutes).
• python3 is required for Bob sessions — a VS Code extension has no SQLite driver, and a
  native module would break VSIX portability. Confined to one file, read-only.
  → why
• Claude message injection targets one conversation — the sessionId↔channel link lives in
  Claude's webview, not its extension host.
• Supervision needs a classifier CLI — bob or claude on your PATH.

Contributing

Issues and pull requests welcome. Run make check before you push; CI runs the same thing.

License

MIT