Sage - Make AI agents think before they code

The problem

Fast code is cheap. Wrong code is expensive.

Most agents can edit files. The hard part is knowing which decisions the team already made, which helpers exist, and which changes should pause before touching production paths.

It reads the rules first.

The pipeline makes knowledge lookup mandatory instead of hoping an agent happens to open the right doc.

It reuses what your team built.

Services, helpers, components, conventions, and decisions are surfaced before new code is invented.

It blocks reckless changes.

Block rules reject unsafe output. Ask rules stop and wait for a human before high-risk code lands.

Before and after

The same agent. A much better first thought.

Sage is not another coding agent. It is the cognition layer your existing agents read before they act.

Agent alone output-first

xStarts editing before checking team decisions.

xMisses existing services and recreates similar code.

xTreats payment, auth, and data paths like normal files.

xMemory stays personal, implicit, and hard to review.

Agent with Sage context-first

+Reads approved rules from plain Markdown in git.

+Names the reuse path before creating anything new.

+Reports risk and applies proceed / warn / ask / reject.

+Captures new team decisions as reviewable files.

Install

One command makes cognition enforceable.

It asks which AI tools you use (multi-select), fetches the protocol and commands, and wires up the ones you pick. Re-run any time to update. Your own knowledge is never overwritten.

Get started MIT / Open Source

01 Bash — macOS / Linux / git-bash

bash -c "$(curl -fsSL https://cdn.jsdelivr.net/gh/qorstack/sage@latest/install.sh)"

02 PowerShell — Windows

irm https://cdn.jsdelivr.net/gh/qorstack/sage@latest/install.ps1 | iex

03 Then seed knowledge from your code

Pick from Claude Code, Codex, Cursor, Copilot, Gemini, Windsurf, Cline — the installer wires up the ones you choose. Run /sage-learning once to capture your team's real patterns — then just use /sage.

/sage-learning     # scan the repo, write team knowledge to agents/sage/

Getting started

Run in this order.

Each command builds on the last — learn first, then code with full context, then document for your team.

/sage-learning · once after install, + after big changes

Learns your codebase's real patterns (rules + decisions) and researches current best practices for your stack (skills) — one run. Gives Sage a knowledge baseline before it touches anything.

/sage · every change (enforced by AGENTS.md)

Full pipeline before and after every code change — pick role, read team knowledge, assess risk, code, capture, summarize. It also shows a short checklist. Auto mode selects the recommended set and continues; ask mode uses the best picker the host exposes. Then it runs the right specialist itself: /sage-flow, /sage-unit-test, /sage-e2e-test, /sage-security-review. You mostly just type /sage.

/sage-docs · on demand

Turn any spec, README, or meeting note into a plain-Markdown flow doc in docs/ — end-to-end ASCII diagram, full step-by-step, complete API spec, open questions. Reads on GitHub, diffs in a PR — no HTML, CSS, or JS. Use when a teammate needs to read — not when an AI needs to follow.

Commands

You mostly just run /sage.

Before each change, /sage shows a short checklist. Auto mode continues without prompting; ask mode prefers native checkboxes, then structured or compact fallbacks. Sage runs the right specialist itself: design the flow (/sage-flow), write tests (/sage-unit-test, /sage-e2e-test), review security (/sage-security-review), refresh docs (/sage-docs), and continues across handoffs until a material gate or completion.

/sage before + after every change

Role    : debugger — fix infinite API loop
Model   : sonnet 4.6 @ effort:medium
Intent  : stop useCallback recreating every render
Touches : BoqUsagePlanSection.tsx
Risk    : LOW — dep array fix only
Decision: proceed

... [fix applied] ...

── Sage ────────────────────────────────
Role      : debugger — fix infinite loop
Model     : sonnet 4.6 @ effort:medium
Domain    : frontend  |  Risk: LOW
Root cause: useLoadingScreen() returns a
            new object on every render.
            Adding it to useCallback deps
            triggers refetch on each render.
Mechanism : render → new ref → callback
            recreated → useEffect fires →
            API called → setState → repeat
Fix       : removed unstable refs from
            deps, kept only [materialId]
Validated : network tab: 1 call on load,
            0 repeated calls
Slipped   : hook API looks stable but
            returns {} without useMemo
Knowledge : [new] decisions/
              usecallback-unstable-deps.md
────────────────────────────────────────

/sage-learning learn + research · once per repo

/sage-learning

── Sage Learning ───────────────────────
Stack     : TypeScript, Next.js 15,
            React 19, MUI, Valibot
Domains   : frontend, api, auth, billing
From code :
  [new]     frontend/rules.md
  [new]     decisions/
              usecallback-unstable-deps.md
  [updated] roles/role-frontend.md
Research  :
  [new]     frontend/skills/
              server-component-boundaries.md
Next      : flip status: approved on
            entries you want enforced
────────────────────────────────────────

/sage-docs on demand · human-readable

/sage-docs [paste spec or describe doc]

Language · English
Doc type · api-flow
Output   · docs/checkout-flow.md
Systems  · Website, Service, Gateway

Sections
- Actors & Systems
- End-to-end overview (ASCII flow)
- Step-by-step + full API spec
- Edge cases · Security
- Open Questions
Coverage · 7 steps · 8 endpoints
           6 errors — all covered
Plain Markdown — reads on GitHub,
diffs in a PR. No HTML/CSS/JS.

Team memory

Knowledge that survives the session.

Sage stores decisions in your repo, not in a hidden chat memory. Humans review the Markdown. Git shares it with every teammate and every future agent.

agents/sage/payment/decisions/use-idempotency-keys.md

---
title: Use idempotency keys
domain: payment
status: approved
enforcement: block
---

All payment calls MUST pass an idempotency key.
Reuse payments/idempotency.py; never roll your own.

Human-governed

AI can propose knowledge, but approved decisions are plain files your team can review, diff, and change.

Tool-agnostic

Claude Code, Cursor, Codex, Copilot, and other agents can read the same protocol and the same rules.

Strict when it matters

Block rules refuse unsafe output. Warn rules proceed with caveats. Ask rules stop for confirmation.

Ship aligned code

Make every agent inherit your team's judgment.

No server. No build. No runtime. Just a protocol, a folder of Markdown commands, and your team's knowledge — one command sets it up and makes cognition part of the coding workflow.

Install Sage View on GitHub