Agent Chat Bridge

Turn any AI agent chat session into an async agent. Register a timer, shell command, or webhook — the bridge automatically resumes the session with your prompt when the trigger fires.

Core flow: agent does work → POST /jobs (one call) → ends session normally → bridge fires prompt back to that session when the trigger fires. Poll GET /jobs/:id to read the agent's reply.

Supported IDEs: VS Code (GitHub Copilot Chat), Windsurf (Cascade)

Quick Start

# 1. Verify the bridge is running (after IDE reload)
curl --noproxy localhost http://localhost:9801/health

# 2. Register a 10-second timer (simplest test)
curl --noproxy localhost -X POST http://localhost:9801/jobs \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"YOUR_SESSION_ID","prompt":"Timer fired — I am back.","seconds":10}'
# → { "job_id": "uuid", ... }

# 3. Agent ends its turn. 10 seconds later the prompt appears in that session.

# 4. Poll for the agent's reply (optional — see "Reading the reply" below)
curl --noproxy localhost http://localhost:9801/jobs/JOB_ID
# → { "status": "responded", "response_text": "..." }

⚠️ Always use --noproxy localhost in IDE terminals if a corporate proxy is configured. Without it, curl routes through the proxy (a remote server) which cannot reach localhost on your machine — you get binary garbage or a proxy error instead of JSON. --noproxy localhost,127.0.0.1 tells curl to connect directly for loopback addresses.

⚠️ Default port is 9801. Double-check the port in your curl commands.

Installation

One VSIX works in all supported IDEs:

# VS Code
code --install-extension agent-chat-bridge-*.vsix --force

# Windsurf
windsurf --install-extension agent-chat-bridge-*.vsix --force

Reload the IDE after install (Cmd+Shift+P → Developer: Reload Window).

Compatibility

Windsurf — macOS Permission Prompts

On macOS, Windsurf stores the API key used to talk to its language server in the system Keychain. The extension reads this key so it can make authenticated RPC calls to Cascade. When this happens, macOS shows a password dialog:

"windsurf" wants to use your confidential information stored in "Windsurf Safe Storage" in your keychain.

This is expected and safe. The extension reads the key once at startup to authenticate Cascade RPCs (e.g. sendMessage). It is never stored, logged, or transmitted outside of your local machine.

If you click "Deny": Cascade RPC calls (sending messages to sessions) will fail. You can manually restart the IDE to re-trigger the prompt, or reload the window (Cmd+Shift+P → Developer: Reload Window).

API

The bridge listens on http://localhost:9801 (configurable in IDE Settings → "Agent Chat Bridge").

POST /jobs — register a job

curl --noproxy localhost -X POST http://localhost:9801/jobs \
  -H 'Content-Type: application/json' \
  -d '{
    "session_id": "SESSION_ID",
    "prompt":     "The task finished. Continue.",
    "seconds":    30
  }'

Fields:

Mode is auto-detected from the fields you provide:

No trigger fields = webhook mode. The job sits idle until you call POST /jobs/:id/fire. Use this when an external system (CI, Teams bot) fires the callback itself.

Response:

{ "ok": true, "job_id": "uuid", "mode": "timer", "fires_in": "30s", "session_id": "...", "fallback": "new_chat", "model": null, "workspace": "/path/to/ws" }

For webhook mode the response includes fire_url instead:

{ "ok": true, "job_id": "uuid", "mode": "webhook", "fire_url": "/jobs/JOB_ID/fire", ... }

GET /jobs/:id — poll job status and read the reply

curl --noproxy localhost http://localhost:9801/jobs/JOB_ID

Poll this endpoint to follow a job through its lifecycle and read the agent's reply once it arrives.

Status progression:

{
  "job_id":        "uuid",
  "session_id":    "aaaabbbb-...",
  "status":        "responded",
  "mode":          "timer",
  "prompt":        "Timer fired — I am back.",
  "response_text": "I've reviewed the output. The build passed and...",
  "model":         null,
  "fallback":      "new_chat",
  "started_at":    "2026-05-15T21:00:00.000Z",
  "running_for":   "47s",
  "instance":      "local"
}

response_text is null while the agent is still running (delivered status) and populated once the model finishes (responded). After responded the job moves to history where response_text is also preserved.

Typical polling loop:

while true; do
  RESP=$(curl -s --noproxy localhost http://localhost:9801/jobs/JOB_ID)
  STATUS=$(echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status','?'))")
  case "$STATUS" in
    waiting|fired|delivered) sleep 2 ;;
    responded) echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('response_text',''))"; break ;;
    *) echo "done: $STATUS"; break ;;
  esac
done

POST /jobs/:id/fire — manually trigger a job

curl --noproxy localhost -X POST http://localhost:9801/jobs/JOB_ID/fire

Immediately fires any job regardless of trigger type. Useful for testing and external webhooks (CI, GitHub Actions, Teams bots, deployment pipelines, etc.).

DELETE /jobs/:id — cancel a job

curl --noproxy localhost -X DELETE http://localhost:9801/jobs/JOB_ID

GET /jobs — list active jobs

curl --noproxy localhost http://localhost:9801/jobs

Returns both local (this bridge instance) and remote (other bridge instances) jobs:

{
  "jobs": [
    {
      "job_id": "uuid",
      "session_id": "...",
      "mode": "timer",
      "status": "waiting",
      "prompt": "...",
      "model": null,
      "fallback": "new_chat",
      "workspace": "/path/to/ws",
      "command": null,
      "poll_interval": null,
      "poll_attempts": null,
      "seconds": 30,
      "fires_at": "2026-05-15T21:00:00.000Z",
      "started_at": "2026-05-15T20:59:30.000Z",
      "running_for": "30s",
      "instance": "local"
    }
  ],
  "count": 1,
  "local": 1,
  "remote": 0
}

GET /sessions — list all known chat sessions

# All workspaces, most recent first
curl --noproxy localhost 'http://localhost:9801/sessions'

# Filter to a specific workspace
curl --noproxy localhost 'http://localhost:9801/sessions/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4'

# Single session detail
curl --noproxy localhost 'http://localhost:9801/sessions/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/SESSION_ID'

# Paginate
curl --noproxy localhost 'http://localhost:9801/sessions?limit=10&offset=20'

Scans session storage across all workspaces and returns sessions sorted by last activity (most recent first). Sessions with no messages sent are excluded.

Response:

{
  "sessions": [
    {
      "session_id":     "aaaabbbb-cccc-dddd-eeee-ffffaaaabbbb",
      "workspace_hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "workspace_path": "/home/user/workspace/my-project",
      "last_modified":  "2026-05-08T12:34:56.000Z",
      "first_prompt":   "Help me build the async callback system",
      "title":          "Async callback system"
    }
  ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

Query params: ?limit=N (max 200, default 20), ?offset=N

Get the current window's workspace hash from GET /health → current_workspace_hash.

GET /health

curl --noproxy localhost http://localhost:9801/health
# → { "status": "ok", "port": 9801, "configured_port": 9801, "jobs": 0,
#     "current_workspace": "/path/to/workspace",
#     "current_workspace_hash": "a1b2c3d..." }

GET /registry — see all running bridge instances

curl --noproxy localhost http://localhost:9801/registry
# → { "registry": { "/path/to/workspace-a": 9801, "/path/to/workspace-b": 9802 } }

Shows the shared port registry file. Use this to see which workspace is on which port.

GET /history — completed/cancelled/fired jobs

curl --noproxy localhost http://localhost:9801/history
# → { "history": [ { "job_id": "...", "status": "fired", "prompt": "...", ... } ], "count": 12 }

Persistent history of all jobs that have finished (fired, delivered, responded, cancelled, or failed). Trims to the last 500 entries on disk; in-memory cache serves the last 100. Includes response_text when the agent replied.

GET /events — SSE live updates

curl --noproxy localhost http://localhost:9801/events

Server-sent events stream for real-time updates. Emits jobs, history, and registry events whenever data changes. The dashboard UI subscribes to this to refresh tables without polling.

GET /ui — dashboard HTML

open http://localhost:9801/ui

Serves the standalone dashboard (same UI used inside the IDE webview). Can be opened in any browser. It auto-detects whether it is running inside a VS Code webview and switches from fetch to postMessage accordingly.

POST /config — update a setting

curl --noproxy localhost -X POST http://localhost:9801/config \
  -H 'Content-Type: application/json' \
  -d '{"key":"port","value":9802}'

Updates a setting (e.g. port) directly from the dashboard or an external script. Requires a window reload for the new value to take effect.

GET /models — list available models

Returns every chat model the current IDE window can see. Use the family value as the model string shorthand, or the full object for exact targeting.

curl --noproxy localhost http://localhost:9801/models

{
  "models": [
    {
      "id": "...",
      "name": "Claude Sonnet 4.5",
      "family": "claude-sonnet-4.5",
      "vendor": "copilot",
      "maxTokens": 128000,
      "source": "vscode_lm"
    }
  ],
  "total": 12
}

Note: Model availability depends on your subscription and IDE version. Always use GET /models for the current list.

Known models (GitHub Copilot, as of 2026-05-18)

These may not work — model IDs change when the IDE updates. If the IDE can't find a matching model, the prompt won't fire. Always verify with GET /models.

Getting Session ID

VS Code (GitHub Copilot): Inside a Copilot agent session, the session ID is available as VSCODE_TARGET_SESSION_LOG — a file path inside the debug-logs directory. The session ID is the UUID directory name. This is a template variable injected into the agent's system prompt, not a shell env var — echo $VSCODE_TARGET_SESSION_LOG in a terminal returns empty. The agent embeds the value literally into the curl command.

Windsurf (Cascade): Use GET /sessions to list sessions. The most recent session is typically the current one. Get the current workspace hash from GET /health → current_workspace_hash.

If you don't need a specific session, omit session_id — the prompt opens in a new chat.

Examples

Timer — simplest test

curl --noproxy localhost -X POST http://localhost:9801/jobs \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"SESSION_ID","prompt":"Timer fired — I am back.","seconds":10}'

Webhook — fire on demand

# Register — creates a webhook job
RESULT=$(curl -s --noproxy localhost -X POST http://localhost:9801/jobs \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"SESSION_ID","prompt":"Fired on demand."}')
JOB_ID=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")

# Fire it when ready
curl --noproxy localhost -X POST "http://localhost:9801/jobs/$JOB_ID/fire"

Read the agent's reply

# Register a timer job
JOB_ID=$(curl -s --noproxy localhost -X POST http://localhost:9801/jobs \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"SESSION_ID","prompt":"Summarise what you just built.","seconds":2}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")

# Poll until responded
while true; do
  RESP=$(curl -s --noproxy localhost "http://localhost:9801/jobs/$JOB_ID")
  STATUS=$(echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status','?'))")
  [ "$STATUS" = "responded" ] && echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin)['response_text'])" && break
  [ "$STATUS" = "waiting" ] || [ "$STATUS" = "fired" ] || [ "$STATUS" = "delivered" ] || break
  sleep 2
done

No session_id — opens a new chat

curl --noproxy localhost -X POST http://localhost:9801/jobs \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Task done. Starting fresh.","seconds":5}'

Cross-workspace — fire into another workspace

curl --noproxy localhost -X POST http://localhost:9801/jobs \
  -H 'Content-Type: application/json' \
  -d '{
    "workspace": "/home/user/workspace/my-api",
    "prompt":    "Deployment to prod finished. Check the logs.",
    "seconds":   1
  }'

Poll until a GitHub PR is merged

curl --noproxy localhost -X POST http://localhost:9801/jobs \
  -H 'Content-Type: application/json' \
  -d '{
    "session_id": "SESSION_ID",
    "prompt": "PR [#123](https://github.com/sathvikc/agent-chat-bridge/issues/123) merged. Proceed with deployment.",
    "command": "gh pr view 123 --repo owner/repo --json merged -q .merged | grep -q true",
    "poll_interval": 30
  }'

Webhook from CI/CD

# 1. Register — get job_id
JOB_ID=$(curl -s --noproxy localhost -X POST http://localhost:9801/jobs \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"SESSION_ID","prompt":"CI passed. Review and tag."}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")

# 2. Fire from your pipeline or external system:
curl -X POST http://YOUR_TUNNEL_URL/jobs/$JOB_ID/fire

Configuration

Set in IDE Settings (Cmd+, → search "Agent Chat Bridge"):

Edge Cases

seconds: 0 is rejected

seconds must be strictly > 0. Use seconds: 1 to fire near-immediately. To fire on demand, omit seconds (webhook mode) and call POST /jobs/:id/fire.

Timer expires while IDE is closed

The job persists in a shared file (~/.local/state/agent-chat-bridge/jobs.json). When the IDE reopens, remaining time is recalculated. If elapsed and fireExpiredOnRestore is true (default), the prompt fires immediately on startup.

Job targets a different workspace

When workspace doesn't match the current window, the bridge keeps the job in the shared jobs file, spawns the IDE with that workspace path, and fires the prompt when that window's extension restores the job.

Multiple IDE windows open

Each window auto-assigns its own port (9801, 9802 … 9810, first available). A shared registry file (~/.local/state/agent-chat-bridge/ports.json) maps each workspace to its port. When a job's workspace field targets a different window, the bridge looks up its port in the registry and forwards the request directly — no manual port config needed.

If you want a predictable port for a specific workspace (e.g. for CI pipelines), configure it:

{ "agentChatBridge.port": 9802 }

If that port is already taken, the bridge silently auto-assigns the next free one in the range 9801–9810 and logs the new port.

Job Persistence

Jobs survive IDE window reloads (Developer: Reload Window):

Jobs are stored in ~/.local/state/agent-chat-bridge/jobs.json (shared across all IDE windows) and cleared when fired or cancelled. delivered and responded states are transient — they are not persisted and do not survive a window reload.

License

MIT — see LICENSE