You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/09/13 19:48:28 UTC
(magpie) branch main updated: docs(readme): say what Magpie is, and show it (#1215)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new b5bd7ef6 docs(readme): say what Magpie is, and show it (#1215)
b5bd7ef6 is described below
commit b5bd7ef69caf1a92957dd7704227b93843222e8b
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Mon Sep 14 02:18:23 2026 +0630
docs(readme): say what Magpie is, and show it (#1215)
The README opened on "high-quality recipes for agent-assisted software
project maintenance" — true of a great many things, and it gave a reader
nothing to decide with. It now says what Magpie does in one paragraph and
what makes it different in three bullets, each of which is a commitment
the project can be held to rather than a claim:
- nothing is sent in your name — every comment, email, label and PR is
drafted by the agent and posted by a person, and there is no
autonomous mode;
- the agent is confined before it reads anything real — sandbox, clean
environment, and a guard that inspects each shell command before it
runs rather than a prompt asking it nicely;
- it is an Apache project, not a product — Apache-2.0, vendor-neutral,
no account, no service in the middle, telemetry opt-in and off by
default (PRINCIPLES.md §10, whose wording this matches rather than
overstating).
**A demo the README can actually show.** The site's "See it in action"
is a JavaScript step-through component, and GitHub markdown strips
scripts and iframes, so it cannot be embedded. The same ten-step story —
marketplace install, isolate and guard, privacy, import, triage, fix,
CVE — is now a generated animation beside it, produced by the existing
render-wizard tooling: SMIL only, no script or style, which is the form
GitHub's renderer preserves. It is labelled illustrative, and links to
the interactive version on the site for the full output of each command.
Also brings the install block up to date: it still said "always take
this one" for magpie-setup alone and "two commands", both of which
predate the baseline of three.
Generated-by: Claude Opus 5
Claude-Session: https://claude.ai/code/session_017suKVbpWX8XT46uRbDxk8y
---
README.md | 64 +++++++++++++++++++++++++++++++++++-----------
assets/quickstart/demo.svg | 60 +++++++++++++++++++++++++++++++++++++++++++
tools/dev/render-wizard.py | 49 +++++++++++++++++++++++++++++++++++
3 files changed, 158 insertions(+), 15 deletions(-)
diff --git a/README.md b/README.md
index e453bf12..0a27a1bf 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,7 @@
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Apache Magpie](#apache-magpie)
+ - [See it in action](#see-it-in-action)
- [Install](#install)
- [Usage](#usage)
- [Update / maintain](#update--maintain)
@@ -23,16 +24,41 @@
[](https://magpie.apache.org/)
-**Adopt a Magpie.** Apache Magpie provides high-quality recipes for
-agent-assisted software project maintenance.
-
-These recipes allow human maintainers working with AIs to efficiently handle
-the repetitive parts of running an open-source project: issue triage, PR
-review, mentoring contributors, managing security reports, and more.
+**Adopt a Magpie.** Magpie is a curated set of skills for the AI agent you
+already use — Claude Code, Codex, Gemini CLI, Copilot and others — that take
+on the repetitive parts of running an open-source project: triaging issues and
+pull requests, reviewing code, mentoring contributors, drafting fixes, and
+handling security reports end to end.
+
+**Three things make it different from a folder of prompts:**
+
+- **Nothing is sent in your name.** Every comment, email, label and PR is
+ *drafted* by the agent and posted by a person. There is no autonomous mode.
+- **The agent is confined before it reads anything real.** A filesystem and
+ network sandbox, a credential-stripped environment, and a deterministic
+ guard that inspects each shell command *before* it runs and denies the ones
+ that break a hard rule — not a prompt asking it nicely.
+- **It is an Apache project, not a product.** Apache-2.0, vendor-neutral
+ across agents, no account and no service in the middle. Telemetry is opt-in
+ per project and off by default — install it and never run a skill, and it
+ generates no outbound traffic at all.
Magpie is currently in development for ASF projects + Python Core team
friendlies. Testers welcome!
+## See it in action
+
+One security report, start to finish — installed from the marketplace, the
+agent sandboxed and guarded, then the report imported, triaged against the
+project's history, fixed, and published as a CVE:
+
+
+
+*Illustrative — a written transcript, rendered deterministically, not a
+recording.* The [**interactive version**](https://magpie.apache.org/#see-it-in-action)
+on the project site steps through the same story with the full output of each
+command.
+
> [!IMPORTANT]
> The motivation, scope, and design commitments behind this work
> live in [`MISSION.md`](MISSION.md) — the founding mission of the
@@ -42,19 +68,27 @@ friendlies. Testers welcome!
## Install
-**Start here → [Quick start](docs/quick-start.md)** — two commands, in the
-agent you already use.
+**Start here → [Quick start](docs/quick-start.md)** — a handful of commands,
+in the agent you already use. Nothing is written to your repository.
```text
-/plugin marketplace add apache/magpie # Claude Code
-/plugin install magpie-setup@apache-magpie # always take this one
-/plugin install magpie-pr-management@apache-magpie # + whichever families you need
+/plugin marketplace add apache/magpie # Claude Code
+/plugin install magpie-setup@apache-magpie # install this one first
+/plugin install magpie-agent-guard@apache-magpie # the baseline:
+/plugin install magpie-utilities@apache-magpie # take all three
+/plugin install magpie-pr-management@apache-magpie # + the families you need
```
-Install **one plugin per family you actually want** — that keeps the always-on
-context cost proportional (~0.2–2.0k tokens a family). There is no
-install-everything plugin: every installed skill costs context on every turn,
-used or not, so the framework asks you to pick.
+Those first three are the **baseline** — and the same set a project commits as
+its floor when it adopts Magpie, so taking them is taking what a project would
+recommend to every contributor. After that, install **one plugin per family you
+actually want**: every installed skill costs context on every turn, used or
+not (~0.2–2.0k tokens a family), so there is deliberately no
+install-everything plugin.
+
+Once `magpie-setup` is in, you never type these again — ask in plain language
+(*"install the Magpie families for PR review"*) and the setup skill runs the
+installs for you.
Codex, VS Code / Copilot, and Gemini are one-liners too — the
[quick start](docs/quick-start.md) has all four, plus what to run next to put
diff --git a/assets/quickstart/demo.svg b/assets/quickstart/demo.svg
new file mode 100644
index 00000000..b21a444a
--- /dev/null
+++ b/assets/quickstart/demo.svg
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 705 760"
+ width="705" height="760" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated walk-through: Magpie installed from the marketplace, the agent sandboxed and guarded, privacy configured, then a security report imported, triaged, fixed and published as a CVE">
+ <title>One security report, start to finish</title>
+ <desc>Illustrative animation of the security lifecycle end to end. Not a recording.</desc>
+ <rect width="705" height="760" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="705" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="705" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /plugin marketplace add apache/magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="104" fill="#7f9f7f" opacity="0"> ✓ apache-magpie added - 12 plugins<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0388;0.0398;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="152" fill="#8abeb7" opacity="0">> /magpie-setup<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0776;0.0786;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#7f9f7f" opacity="0"> ✓ detected example-org/example-app - configuration written<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1163;0.1173;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#8abeb7" opacity="0">> /magpie-setup:isolated-setup-install<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1551;0.1561;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#7f9f7f" opacity="0"> ✓ sandbox, clean env, guard hook - 3 settings changes, 1 sudo<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1939;0.1949;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#8abeb7" opacity="0">> /magpie-setup:privacy-llm<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2327;0.2337;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#7f9f7f" opacity="0"> ✓ gate passed - third-party names redacted: N-a3f9d2, E-7c1b04<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2714;0.2724;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#8abeb7" opacity="0">> /magpie-security:issue-import<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3102;0.3112;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#c5c8c6" opacity="0"> Opened #41 and #42 in example-app-security<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3490;0.3500;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#8abeb7" opacity="0">> /magpie-security:issue-triage<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3878;0.3888;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#c5c8c6" opacity="0"> #41 path traversal in archive extraction high<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4265;0.4275;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="488" fill="#8a8f94" opacity="0"> #42 not a vulnerability - reported behaviour is intended<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4653;0.4663;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8abeb7" opacity="0">> /magpie-security:issue-fix 41<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5041;0.5051;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="560" fill="#c5c8c6" opacity="0"> Fix drafted, PR opened - title and body carry no CVE,<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5429;0.5439;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="584" fill="#8a8f94" opacity="0"> no security wording, and no link back to the tracker.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5816;0.5826;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="632" fill="#8abeb7" opacity="0">> /magpie-security:cve-allocate 41<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6204;0.6214;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="656" fill="#7f9f7f" opacity="0"> ✓ CVE-2026-XXXXX published, advisory drafted<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6592;0.6602;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="704" fill="#d8a657" opacity="0"> Every message that leaves the project was drafted here<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6980;0.6990;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="728" fill="#d8a657" opacity="0"> and sent by a person. Nothing was posted unattended.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7367;0.7377;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <rect x="26" y="715" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/tools/dev/render-wizard.py b/tools/dev/render-wizard.py
index 2fff01dd..dd7bc3af 100644
--- a/tools/dev/render-wizard.py
+++ b/tools/dev/render-wizard.py
@@ -61,6 +61,7 @@ from xml.sax.saxutils import escape
OUT_DIR = Path("assets/quickstart/wizard")
SETUP_SVG = Path("assets/quickstart/magpie-setup.svg")
HERO_SVG = Path("assets/quickstart/install.svg")
+DEMO_SVG = Path("assets/quickstart/demo.svg")
STEP_INSTALL_SVG = Path("assets/quickstart/step-install.svg")
STEP_ISOLATION_SVG = Path("assets/quickstart/step-isolation.svg")
STEP_GUARD_SVG = Path("assets/quickstart/step-guard.svg")
@@ -248,6 +249,46 @@ def hero_script() -> list[tuple[str, str]]:
]
+def demo_script() -> list[tuple[str, str]]:
+ """The README demo: one security report, install to published CVE.
+
+ The same arc the site's interactive replay walks, in the one form a
+ GitHub README can actually show -- the site component is JavaScript and
+ markdown strips it. Ten steps compressed to the line each needs: what
+ was run, and the one fact that proves something happened.
+ """
+ return [
+ (CMD, "> /plugin marketplace add apache/magpie"),
+ (OK, " ✓ apache-magpie added - 12 plugins"),
+ (FG, ""),
+ (CMD, "> /magpie-setup"),
+ (OK, " ✓ detected example-org/example-app - configuration written"),
+ (FG, ""),
+ (CMD, "> /magpie-setup:isolated-setup-install"),
+ (OK, " ✓ sandbox, clean env, guard hook - 3 settings changes, 1 sudo"),
+ (FG, ""),
+ (CMD, "> /magpie-setup:privacy-llm"),
+ (OK, " ✓ gate passed - third-party names redacted: N-a3f9d2, E-7c1b04"),
+ (FG, ""),
+ (CMD, "> /magpie-security:issue-import"),
+ (FG, " Opened #41 and #42 in example-app-security"),
+ (FG, ""),
+ (CMD, "> /magpie-security:issue-triage"),
+ (FG, " #41 path traversal in archive extraction high"),
+ (MUTED, " #42 not a vulnerability - reported behaviour is intended"),
+ (FG, ""),
+ (CMD, "> /magpie-security:issue-fix 41"),
+ (FG, " Fix drafted, PR opened - title and body carry no CVE,"),
+ (MUTED, " no security wording, and no link back to the tracker."),
+ (FG, ""),
+ (CMD, "> /magpie-security:cve-allocate 41"),
+ (OK, " ✓ CVE-2026-XXXXX published, advisory drafted"),
+ (FG, ""),
+ (WARN, " Every message that leaves the project was drafted here"),
+ (WARN, " and sent by a person. Nothing was posted unattended."),
+ ]
+
+
def step_install_script() -> list[tuple[str, str]]:
"""Walkthrough step 1: the marketplace install, on one agent.
@@ -474,6 +515,14 @@ def build() -> dict[Path, str]:
cfg = _load("check_skill_config", Path("tools/dev/check-skill-config.py"))
desc = cfg.descriptions()
out: dict[Path, str] = {
+ DEMO_SVG: render(
+ "One security report, start to finish",
+ "An animated walk-through: Magpie installed from the marketplace, the "
+ "agent sandboxed and guarded, privacy configured, then a security report "
+ "imported, triaged, fixed and published as a CVE",
+ "Illustrative animation of the security lifecycle end to end. Not a recording.",
+ demo_script(),
+ ),
HERO_SVG: render(
"Install Magpie, and use it",
"An animated first look: three install commands, then a triage run "