AI codes fast. Raven enforces Discipline — Strategic Thinking, Scalable Structure, Security at Source.
How, in simple terms:
- Strategic Thinking — done by two orchestrators, picked automatically based on what you're doing:
- Andie — for new work and decisions (new repo, new feature, "should we use X or Y?"). Makes a plan, attacks it from three angles (business, technical, data — plus a critic), and waits for your go before touching code.
- Andie-Jr — for bugs in existing code ("why is auth failing?"). Skips the planning ceremony and runs a fast 2-round triage straight to root cause → fix, so brownfield debugging isn't slowed down by process it doesn't need.
- Scalable Structure — every prompt is routed to the right expert automatically. 61 specialists, one per domain, picked by deterministic rules — and you always see a one-line note saying who's handling it and why. Works the same on one repo or a hundred.
- Security at Source — guards run on your machine, at the moment code is written and committed: secrets are blocked, vulnerable libraries are blocked, and edits are blocked until the thinking actually happened. Not a report after the damage — a gate before it.
All local. Zero telemetry. MIT.
Raven is not in an Anthropic-hosted plugin marketplace — /plugin marketplace add giggsoinc/raven will not work. Pick one:
- Clone + install —
git clone https://github.com/giggsoinc/raven.git && claude plugin install ./raven/plugin - Download zip + install — grab
raven-plugin-v4.1.0.zipfrom releases, unzip it, thenclaude plugin install /path/to/extracted/plugin - Let Claude do it — inside a Claude Code session, ask Claude to clone the repo and run the install command for you (same two steps as Option 1, just delegated)
Full walkthrough (enterprise admin upload, org-wide managed deployment, troubleshooting): claude_plugin_readme.md
Then restart your session. You should see the Raven greeting:
🪶 Raven ✅ | {your-project} | {stack}
Andie is your discipline layer. What are you working on?
The plugin gives Claude the skills and guards. Each project still needs a one-time setup pass for hooks, engine scripts, and a manifest:
bash <(curl -fsSL https://raw.githubusercontent.com/giggsoinc/raven/main/install.sh) # once per machine
cd your-project && raven-setup # once per projectTwo files come out of this setup, in plain terms:
.raven/manifest.json— your project's config card: what language/stack you use, solo or team mode, which guard rules are on. Andie and the guards read this before doing anything, so they act like a Postgres expert on a Postgres project instead of guessing..raven/manifest.secrets.json— only needed if you want commit/block email or Slack alerts. It holds those notification credentials, is gitignored by default, and everything works fine without it (Raven just skips notifications silently).
raven-setup finds no file signatures in an empty directory, so it asks 1–3 quick questions (mode: solo/team/enterprise, primary language, cloud provider) and builds .raven/manifest.json entirely from your answers. Start working normally — Andie routes every prompt and guards activate as soon as files exist.
raven-setup runs a detector that auto-classifies the work type (code / infra / data / docs / salesforce / odoo / mixed) from file signatures already in your repo. Known limitation: that only sets the work-mode label — it does not read package.json/requirements.txt/etc. to auto-fill the manifest's stack fields, so you'll still be asked to manually pick languages, databases, and cloud provider even though that info is already in the repo. If .raven/manifest.json already exists, setup skips straight to "already configured."
This is also where Andie-Jr earns its keep: once the manifest is in place, any bug report on this existing codebase gets a 2-round root-cause triage instead of an open-ended investigation — faster than either a from-scratch plan (Andie) or no structure at all (plain Claude).
| You type | What happens |
|---|---|
why is auth failing since yesterday? |
routed to andie-jr — 2-round triage: root cause → fix → audit note |
should we use Postgres or Mongo here? |
routed to andie — one mode card, 3-angle review, you approve each step |
/andie or /andie-jr |
force the route explicitly |
git commit with a staged API key |
hard block at the pre-commit gate, with the line that triggered it |
rename this variable |
routed nowhere — trivial edits skip the ceremony |
- 2 orchestrators — Andie (plan-first, one hard gate, critic voice) and Andie-Jr (brownfield debug, max 2 rounds)
- Deterministic routers — repo-state + intent routing with visible one-line toasters; never routes silently
- 61 domain skills — FastAPI, Postgres, K8s, Terraform, Salesforce, Odoo, Oracle, AWS/GCP/Azure, and more, loaded only when your work matches
- Local guards — secret scan + CVE check (CVSS >7 blocks) at every commit; optional edit gate (
raven-skill-gate, shadow/soft/hard modes); style and architecture checks - Cost-aware model routing — prompts classified to the cheapest adequate tier; secret-laden context forced to a local model
- Audit + memory — JSONL audit logs, session notes, token dashboard (docs/DASHBOARD.md) — all on local disk
| Scenario | Raven | Plain Claude | Notes |
|---|---|---|---|
| Brownfield bug — "Why is auth timing out?" | ✅ Faster | ❌ | 2-round triage beats open-ended; forces root cause before fix. |
| Architecture decision — "Should we migrate to Postgres?" | ✅ Better | ❌ | Triad (Functional/Tech/Data) catches angles one perspective misses. |
| Commit-time security — prevent secrets/CVEs shipping | ✅ Hard-block | ❌ | Pattern-based detection; reduces risk, not foolproof. |
| Routine feature work — "Build me a login form" | ❌ Slower | ✅ Faster | Raven adds ceremony; plain Claude is direct. |
| Quick lookup — "What's the CloudRun pricing?" | ❌ Overkill | ✅ Direct | No decision needed; Raven's routing overhead is wasted. |
Runs a Drama panel debate when your decision has tradeoffs:
- Functional Lead — business/domain owner perspective
- Technical Lead — system/implementation owner perspective
- Data Lead — metrics/integration owner perspective
Each panelist argues their angle. You steer the debate. Final output: decision + rationale + rejected alternatives + risks.
For broken systems: problem → diagnosis → fix → audit.
- Round 1: 2 clarifying questions that isolate the root cause.
- Round 2: Root-cause explanation + fix + verification steps + audit note.
Not for greenfield builds; only for existing systems showing symptoms (errors, timeouts, regressions).
| Scenario | Route | How |
|---|---|---|
| Brownfield bug ("why is X broken?") | andie-jr | Repo >1 commit + symptom language detected |
| Greenfield or architecture ("should we...?") | Andie | Repo ≤1 commit OR Drama-mode intent |
| Data question ("what is...?", "list...", "show...") | Direct | No change verbs (build, fix, create); no routing overhead |
Force path (/andie, /andie-jr) |
Explicit | User typed the skill name — routing wins always |
UserPromptSubmit (every message)
↓
triage-router.py [deterministic repo-state]
├─ Brownfield (>1 commit) → andie-jr
├─ Greenfield (≤1 commit) → Andie
├─ Data question (read/list/explain, no change verbs) → direct
└─ Force path (/andie, /andie-jr) → always wins
↓
[Specialist runs, edit/commit allowed]
↓
PostToolUse: secret-scan.py (after Write/Edit)
├─ AWS keys, OpenAI keys, GitHub tokens, SSH, bearer tokens → WARN
└─ Send intent to audit log (`.raven/audit/YYYY-MM-DD.log`)
↓
Pre-commit hook (.git/hooks/pre-commit)
├─ secret-scan.py → HARD BLOCK if secrets staged
├─ cve-check.py (new imports) → HARD BLOCK if CVSS >7
├─ style-enforcer (line count, type hints, docstrings) → HARD BLOCK if violated
├─ architecture-guard (doc alignment) → WARN now, block in 24h
├─ db-guard (inline SQL, missing ERDs, migration order) → WARN
└─ notify.py (SMTP + Slack) → send pass/fail summary + audit
↓
Commit lands (or blocked + approval flow starts)
| Guard | Fires | Detects | Action |
|---|---|---|---|
| manifest-checker | SessionStart | Missing .raven/manifest.json |
Hard stop with setup guide |
| secret-guard | PostToolUse + pre-commit | AWS keys, tokens, SSH, PII in staged files | Warn on edit / hard block on commit |
| cve-check | New import X statement |
Library vulnerabilities (CVSS >7) | Warn during coding / hard block at commit |
| stack-validator | Import detected + not in approved list | Unapproved libraries (Polars vs Pandas, etc.) | Warn / block at commit |
| style-enforcer | File edit | Line count >200, missing type hints, no docstrings | Advise / block at commit |
| architecture-guard | New file created | Missing .raven/architecture.md documentation |
Warn / hard block after 24h grace |
| db-guard | File edit (SQL, migrations) | Inline SQL in non-SQL files, missing ERDs, broken migration numbering | Warn in audit log |
Fires from pre-commit hook on success or block:
- Commit pass: Confirmation email + Slack (to recipients in
.raven/manifest.secrets.json) - Commit blocked: Alert with violation count + Slack
- Override used: Log to audit trail + email
- Token warning: 75% / 90% thresholds
Rule: enforcement runs in Python hooks, outside the model — it costs zero tokens. Gates, guards, scanners, audit logs, and the pre-commit pipeline never enter Claude's context. Only the thin advisory layer does:
| Layer | Frequency | Tokens |
|---|---|---|
| Hooks: skill gate, secret scan, CVE, pre-commit, token guard | every tool call / commit | 0 |
| Skill-reminder + router toasters (context injection) | per message | ~100 |
| Session boot (greeting + transparency banner) | once per session | ~500 |
| Specialist SKILL.md load (when a skill actually runs) | once per session | ~1–2k |
| Violation messages (block/warn) | only on violation | ~50 |
Steady-state: ~2% overhead on a typical session — and the model router (0-token hook) claws that back by tiering simple prompts to cheaper models and routing secret-laden context to a free local model. Full breakdown, including where Raven saves tokens: docs/TOKENOMICS.md · diagrams: business view · technical view.
New:
- Token metering —
token-meter-write.pyStop hook records tokens, cost, and call counts per session (session JSON + monthly rollup + audit log). Session-end meters printed in-terminal. - Dashboard upgrade — local HTML dashboard (
~/RavenVault/dashboard.html) now shows tokenomics with a Raven-metered vs Claude-reported cost comparison. See docs/DASHBOARD.md. - Knowledge-graph icons — picture-map UI for non-programmers; SVG icons inlined for offline
file://use. Zero-code guide: docs/VIBE-CODER-MAP.md. - Andie v6.4 (one hard gate, implicit GO, GATES ledger, critic voice) + routing toasters — Raven never routes silently.
- Vault-backed cross-session memory with graph export; see docs/CHANGELOG-4.2.0-vault-graph.md and docs/RAVENVAULT-GRAPH-AND-MEMORY.md.
New:
- Privacy hardening: Changelog cleared from manifest, personal emails replaced with org email across all registries.
- Critical routing fix: Deterministic repo-state logic replaces regex classification. Brownfield →andie-jr, greenfield → Andie, data questions → direct. Fixes misclassification of debug as new-work.
Maintained from v4.0:
- Andie Drama mode (3-panelist debate on tradeoffs)
- Andie-jr fast triage (2-round root-cause flow)
- 61 domain skills (ML, Salesforce, Odoo, K8s, Terraform, etc.)
- Commit-time secret + CVE scanning
- Cross-session memory (
.raven/memory/) - SMTP + Slack notifications
- Rewritten README: no false claims, honest ROI section, per-persona messaging.
- Verified 61 skills (corrected from earlier miscount).
- CLAUDE.md per-turn discipline contract at top; Raven/Lucky gate; real hook names.
- First onboarding in Andie: brownfield self-detect vs greenfield setup (≤2 questions).
/andie+/andie-jrforce-path commands; plugin now bundles 12 commands.notify.py: real SMTP + Slack wired into pre-commit.install-claudemd.py: append-only CLAUDE.md installer (never deletes user content).- Session-start transparency banner.
See CHANGELOG.md for v3.x and earlier.
- v4.0 → v4.1: Drop-in replacement. Run
/raven-syncto sync manifests; no config changes needed. - v3.x → v4.0+: Not backward-compatible. See migration guide in CONTRIBUTING.md.
Claude Desktop (ZIP): download raven-plugin-v4.1.0.zip → Settings → Extensions → Add plugin → drop the ZIP → restart.
From source:
git clone https://github.com/giggsoinc/raven.git
cd raven && bash plugin/make-plugin.sh # builds plugin/raven-plugin-v4.1.0.zipRaven is MIT licensed. Contributions welcome. See CONTRIBUTING.md for:
- How to add a skill
- How to write a guard agent
- Style standards (Giggso code style — type hints, docstrings, logging, ≤200 LOC per file)
- Pre-commit hook requirements
This repo is the free tier — everything runs local, MIT-licensed, complete as-is.
Raven Enterprise (paid, sold separately) adds what teams and compliance departments need on top: Hub dashboards across developers and repos, per-developer token attribution and chargeback, compliance/audit reporting, centralized policy sync, and commercial support.
- Bug reports: GitHub Issues
- Questions: Start a discussion in GitHub Discussions
- Security vulnerabilities: Email
rv@giggso.com(do not open public issue)
Built by Giggso · GitHub · MIT License
Raven v4.1.0 — Governance for AI coding at the speed of thought.