workstream

Why Workstream?

Modern developers live across 6+ tabs — GitHub, GitLab, Jira, Calendar, AI tools, status pages. Each context switch costs 23 minutes of refocus time (UC Irvine research).

Workstream eliminates that. It's a local-first, single-screen command center that pulls everything into one view — with AI superpowers baked in. No SaaS. No cloud. Your data stays on your machine.

pip install -r requirements.txt && cp .env.example .env && ./run.sh

Features

Pull Requests

Unified view of PRs across GitHub and GitLab. CI status, staleness badges, review state, and an amber "changes since your review" indicator — all at a glance.

One-Click Rebase

Rebase any PR onto its base branch (or a custom target) without merge commits. GitHub uses local git + --force-with-lease; GitLab uses the native API. Conflict detection included.

AI Code Review

Review PRs with OpenAI, Claude, Gemini, or Ollama (local). Copy-prompt mode works with any LLM. Human approval required before posting to VCS.

Jira Integration

Sprint tracking, task counts by role, yearly completion comparison (pro-rated), and deep links to Jira boards and JQL views.

Google Calendar

Side-by-side today + tomorrow agenda with attendee counts and Google Meet join links.

Service Health

Live status monitoring for GitHub, Atlassian, and GitLab. Color-coded header dot with expandable incident details.

AI Readiness Scanner

Score any repo across 6 categories on a research-backed 170-point rubric. Generates bootstrapping files (with optional AI enhancement) and opens draft PRs.

Review Intelligence

Collects merged PR history from any GitHub repo to surface recurring review patterns, feedback themes, and reviewer profiles.

Agents Dashboard

Auto-discovers MCP servers from your Cursor config. Tracks A2A agents with health checks, token/cost telemetry, and a live activity stream.

Developer Ergonomics

Focus banner, keyboard shortcuts, global search, desktop notifications, dark/light mode, weather widget, stretch reminders, and quick notes.

Quick Start

Prerequisites: Python 3.11+, a GitHub PAT

git clone https://github.com/happybhati/workstream.git
cd workstream
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # add your GitHub PAT and username
./run.sh               # or ./install.sh for macOS auto-start

Open localhost:8080 — that's it.

Tip: On macOS, ./install.sh sets up a LaunchAgent so Workstream starts on login and restarts on crash.

Configuration

Everything is controlled via .env. Only GITHUB_PAT and GITHUB_USERNAME are required — every other integration is opt-in.

See docs/CONFIGURATION.md for the full reference with all variables and defaults.

Architecture

flowchart LR
  subgraph client["Browser"]
    UI["Single-page UI<br/>(vanilla JS)"]
  end
  subgraph server["FastAPI Backend"]
    API["REST API"]
    REV["reviewer.py"]
    REB["rebaser.py"]
  end
  subgraph polling["Background Pollers"]
    P["pollers.py"]
    SVC["Service Status"]
  end
  subgraph external["External APIs"]
    GH["GitHub"]
    GL["GitLab"]
    JR["Jira"]
    GC["Google Calendar"]
    AI["AI Providers"]
  end
  DB[("SQLite")]
  INT["intelligence/"]
  RDY["agentic_readiness/"]
  AGT["agents/"]

  UI <-->|"JSON"| API
  API --> REV
  API --> REB
  API <--> DB
  P -->|"poll cycle"| GH & GL & JR & GC
  SVC -->|"status APIs"| GH & GL & JR
  P --> DB
  REV --> AI
  API --> INT & RDY & AGT

Stack: Python 3.11+ · FastAPI · SQLite · Vanilla JS · CSS Variables · No build step

Screenshots

CLI

workstream start          # Start via LaunchAgent
workstream stop           # Stop service
workstream restart        # Restart service
workstream status         # Check if running
workstream open           # Open dashboard in browser
workstream logs           # Tail application log
workstream scan-repo URL  # Scan a repo for AI readiness
workstream collect URL    # Collect PR review history
workstream help           # Show all commands

Project Structure

workstream/
├── app.py                    # FastAPI routes
├── config.py                 # Settings from .env
├── database.py               # SQLite schema & queries
├── pollers.py                # Background polling + service status
├── reviewer.py               # AI review engine (OpenAI, Claude, Gemini, Ollama)
├── rebaser.py                # PR rebase engine (GitHub git + GitLab API)
├── static/index.html         # Single-page frontend (zero dependencies)
├── agentic_readiness/        # AI readiness scanner, scorer, generator
├── intelligence/             # PR review pattern analysis
├── agents/                   # MCP/A2A agent observability
├── mcp_server/               # MCP server for AI tool integration
├── bin/workstream            # CLI
├── tests/                    # pytest suite
└── docs/                     # Documentation

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

Apache License 2.0