Workweave

Turn scattered developer signals into a focused, prioritized plan for your day.

Workweave is a CLI tool that ingests activity from GitHub, Linear, and Slack, then synthesizes a time-boxed workday plan — either using deterministic prioritization rules or an AI model of your choice (local, Anthropic, or OpenAI).

---

How it works

GitHub ─┐
Linear ─┼──▶  ingest ──▶  normalize ──▶  correlate ──▶  prioritize ──▶  schedule ──▶  plan
Slack  ─┘                                                      ▲
                                                         (optional AI)

1. Ingest — pull open PRs, assigned issues, mentions, and messages
2. Normalize — map everything to a common Artifact model
3. Correlate — link related items across sources
4. Prioritize — score by urgency, importance, social pressure, staleness, and blocking factors
5. Schedule — fit clusters into your available workday budget
6. Display — rich terminal output or machine-readable JSON

---

Features

• Three AI providers — local model (no key required), Anthropic Claude, or OpenAI
• Rules mode — works fully offline, no API key needed
• JSON output — pipe into scripts, dashboards, or other tools with --json
• Interactive setup — guided workweave setup wizard configures everything
• Connector detection — workweave detect checks which sources are ready before you run
• Configurable workday budget — schedule work to fit your actual available hours

---

Install

npm install -g workweave

That's it. The workweave command is now available globally.

From source (for contributors):

git clone https://github.com/emin93/workweave.git
cd workweave
npm install && npm run build && npm link

---

Quick start

1. Run the interactive setup wizard:

workweave setup

The wizard walks you through:

• GitHub personal access token (repo scope)
• AI provider — downloads a local model (~4 GB, runs on CPU) or configures an API key
• Workday hours (default: 8 h)
• Linear API key (optional)
• Slack user token (optional)

All credentials are stored in a local .env file that is never committed.

2. Check that your connectors are ready:

workweave detect

3. Synthesize your day:

workweave synth

---

Commands

workweave setup

Interactive wizard to configure connectors and AI.

workweave setup

workweave detect

Check which connectors are configured and reachable.

workweave detect

  github   ✓  authenticated as emin93
  linear   ✓  workspace: Acme Corp
  slack    ✗  SLACK_USER_TOKEN not set

Pass --connectors github,linear,slack to check specific sources only.

workweave synth

Fetch signals and produce a workday plan.

# Synthesize your day (AI auto-detected)
workweave synth

# Force a specific provider
workweave synth --provider anthropic

# Adjust available time
workweave synth --workday-minutes 360

# Machine-readable output
workweave synth --json

# Limit to specific connectors
workweave synth --connectors github,linear

# Skip AI and use rules-based prioritization only
workweave synth --no-ai

---

AI provider

Run workweave setup to choose your AI provider. The choice is saved to your .env and used on every run.

Provider	Model	Requires
Anthropic	claude-haiku-4-5	ANTHROPIC_API_KEY
OpenAI	gpt-4o-mini	OPENAI_API_KEY
Local	Qwen 2.5 1.5B (via node-llama-cpp)	~1 GB one-time download, no key

Override for a single run with --provider anthropic|openai|local.

---

Environment variables

Variable	Description
AI_PROVIDER	Active AI provider: anthropic | openai | local (set by workweave setup)
GITHUB_TOKEN	GitHub personal access token (repo scope)
LINEAR_API_KEY	Linear personal API key
SLACK_USER_TOKEN	Slack user token (xoxp-…)
ANTHROPIC_API_KEY	Anthropic API key
ANTHROPIC_MODEL	Model override (default: claude-haiku-4-5)
OPENAI_API_KEY	OpenAI API key
OPENAI_MODEL	Model override (default: gpt-4o-mini)
WORKDAY_MINUTES	Available minutes per day (default: 480)

Variables can be set in a local .env file at the project root (created by workweave setup) or exported in your shell.

---

JSON output

Add --json to any command for machine-readable output. Progress logs are suppressed and only the result is written to stdout.

workweave synth --json | jq '.plan.blocks[].title'

synth output shape:

{
  "plan": {
    "blocks": [...],           // scheduled work blocks
    "synthesisMode": "ai",     // "ai" | "rules"
    "synthesisProvider": "local"
  },
  "meta": {
    "connectors": ["github"],
    "rawEvents": 42,           // raw events ingested
    "artifacts": 18,           // normalized artifacts
    "connectorErrors": []      // non-fatal errors
  }
}

detect output shape:

{
  "connectors": [
    { "id": "github", "ready": true, "detail": "authenticated as emin93" },
    { "id": "linear", "ready": false, "detail": "LINEAR_API_KEY not set" }
  ]
}

---

Project structure

src/
  cli.ts                  # CLI entry point, argument parsing
  setup.ts                # Interactive setup wizard
  display.ts              # Terminal rendering (plan, detect, spinner)
  env.ts                  # .env file loading and writing
  connectors/
    github.ts             # GitHub REST API connector
    linear.ts             # Linear GraphQL connector
    slack.ts              # Slack Web API connector
    registry.ts           # Connector registry + detect-all
  pipeline/
    ingest.ts             # Orchestrate connector fetching
    normalize.ts          # Map raw events → Artifact
    correlate.ts          # Link related artifacts across sources
    prioritize.ts         # Score and rank clusters
    schedule.ts           # Fit clusters into workday budget
    ai-synthesize.ts      # AI-powered clustering and titling
  ai/
    provider.ts           # LLMProvider interface + OpenAI/Anthropic/LlamaCpp impls
    local.ts              # Local model path helpers and download
  types/                  # Shared TypeScript models

---

Contributing

Contributions are welcome. Please open an issue to discuss significant changes before submitting a PR.

npm run build   # compile TypeScript
npm run lint    # ESLint

---

License

MIT