Sage

Research, clarify, plan. The AI agent that turns scattered conversations into executable development workflows.

Sage is the Plan phase of PDERO (Plan, Delegate, Execute, Review, Observe). It observes team conversations, researches across integrations, asks clarifying questions, and produces structured plans that become relay workflow definitions.

How it works

You @sage in Slack (WhatsApp and Telegram in V2). Sage:

1. Researches — searches the web and your GitHub repos for context
2. Clarifies — asks probing questions before jumping to solutions
3. Remembers — persistent memory across conversations via Supermemory
4. Plans (V3) — synthesizes everything into executable relay workflows

Architecture

V1 (Current)

Single-agent Slack webhook server with web search and GitHub integration.

Slack Events API → Hono server → Sage agent (Sonnet 4.6) → Slack response
                                    ├── OpenRouter (web search)
                                    ├── GitHub (via Nango)
                                    └── Supermemory (persistent memory)

V2

Multi-platform (Slack + WhatsApp + Telegram) with multi-agent swarm under the hood via @agent-relay/gateway.

V3

Full planning pipeline. Planner agent (Opus 4.6) synthesizes context into structured plans and generates executable relay workflow definitions.

Setup

Prerequisites

• Node.js 20+
• agent-relay CLI installed
• A Slack app (Events API, not Socket Mode)
• Nango account with GitHub integration
• OpenRouter API key
• Supermemory API key

1. Install dependencies

npm install

2. Configure environment

cp .env.example .env

Fill in:

| Variable | Source | Purpose | |----------|--------|---------| | OPENROUTER_API_KEY | openrouter.ai/keys | Sonnet 4.6 + web search | | SUPERMEMORY_API_KEY | supermemory.ai | Persistent memory | | SLACK_BOT_TOKEN | Slack app → OAuth & Permissions | Bot identity (xoxb-) | | SLACK_SIGNING_SECRET | Slack app → Basic Information | Webhook verification | | NANGO_SECRET_KEY | app.nango.dev → Settings | Nango API access | | NANGO_GITHUB_CONNECTION_ID | app.nango.dev → Connections | Your GitHub connection | | SAGE_WORKSPACE_ID | You choose (e.g. "default") | Memory namespace | | PORT | Optional (default: 3000) | Server port |

3. Create Slack app

1. Go to api.slack.com/apps → Create New App → From scratch
2. OAuth & Permissions → Bot Token Scopes:
   • app_mentions:read
   • chat:write
   • channels:history
   • channels:read
3. Install to workspace → copy Bot Token
4. Basic Information → copy Signing Secret
5. Event Subscriptions → Enable → Subscribe to bot events: app_mention
6. Set Request URL to your public URL + /api/webhooks/slack

4. Run locally

npm run dev          # Starts Hono server on :3000
ngrok http 3000      # Expose webhook URL for Slack

Paste the ngrok URL into Slack Event Subscriptions as the Request URL:

https://your-ngrok-id.ngrok.io/api/webhooks/slack

5. Use it

Mention @sage in any Slack channel:

• "What's the best queue library for Node.js?" → web search + synthesis
• "What open issues do we have about auth?" → GitHub search
• "I want to add real-time notifications" → clarifying questions before planning
• Come back to the same thread later → Sage remembers the context

Building with workflows

Sage is built by relay workflows. To rebuild from scratch:

bash workflows/run-v1.sh      # Build V1 (~80 min)
bash workflows/run-v2.sh      # Build V2 (~130 min)
bash workflows/run-v3.sh      # Build V3 (~125 min)
bash workflows/run-all.sh     # Build everything (~5.5 hours)

See workflows/wave-plan.md for the full execution plan.

Project structure

src/
├── server.ts              # Hono HTTP server — webhook entry point
├── slack.ts               # Slack signature verification + event parsing
├── openrouter.ts          # OpenRouter client (Sonnet 4.6 + web search)
├── memory.ts              # Supermemory persistence layer
├── prompt.ts              # Sage system prompt / persona
├── nango.ts               # Nango client wrapper
└── integrations/
    ├── types.ts            # Shared integration types
    └── github.ts           # GitHub search, file read, PR diff via Nango

Part of PDERO

| Phase | Agent | Role | |-------|-------|------| | Plan | Sage (this repo) | Research, clarify, plan | | Delegate + Execute | Pear | Agent orchestration GUI | | Review | MSD + Trajectories | Code review + decision recording | | Observe | NightCTO | AI CTO over messaging | | Communication | Agent Relay | Inter-agent messaging |