convez.ai
SkillDesenvolvimento WebAvançado
danielmedinac22

Mirador — Colaboração Contextual via IA

danielmedinac22/mirador

Artefato único, múltiplas lentes IA — colaboração contextual versionada

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill para publicar e colaborar em documentos HTML versionados no Vercel, onde múltiplos agentes IA refinam um artefato compartilhado, cada um através de seu próprio contexto. Integra Git, CLI nativa e agentes IA (Claude Code, Codex, Gemini) para convergência colaborativa em direção a uma visão comum.

Instalação

$npx convez-ai danielmedinac22/mirador

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
1
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
1
Contribuidores
2

Casos de uso

  • Equipes refinando documentos estratégicos (Q3 plans, narrativas) com visões privadas convergindo
  • Documentação viva onde múltiplos agentes contribuem, cada um lendo pelo seu contexto
  • Workflows colaborativos Git-native com handoffs estruturados entre máquinas IA

Veredito

Ferramenta ambiciosa que reinventa colaboração: transforma artefatos em espaços onde cada agente IA aplica lógica própria. Exige Node 20+ e mentalidade contextual, mas oferece fluxo único — menos 'diff cru', mais 'briefs contextuais'. Estado V1, pronto para equipes que pensam em convergência, não em merge.

README

A tradução para o português deste README ainda está na fila.

Same artifact. Your lens.

The medium where many minds converge on one living artifact — each through their own AI, guided toward an owned vision. Git-native CLI + agent shim. The HTML is just a view.

npm version npm downloads Node License

npm i -g mirador-cli

macOS, Linux, Windows. Node 20+. Works with Claude Code, Codex, or Gemini.

"My agent read it the way I would. Not the way you wrote it."


[!IMPORTANT] Status: V1 — the convergence era.

Mirador was an HTML publisher. Internal use showed it "felt like an HTML generator with extra steps," and "solo even when shared." So it was redefined: the artifact is now a document many people refine — each through their own AI — converging toward a vision. Publish-era users keep everything (mirador upgrade). Design + per-slice build plans live in docs/superpowers/. Bugs → GitHub issues.


The idea

Google-Docs-with-AI has multiplayer editing but no per-person lens. Notion sees the shared workspace, not your private context. Mirador is the only tool where collaboration is contextual: one artifact, many private contexts, each reading and refining it through their own AI, converging toward one owned vision.

A mirador is a lookout. What you see depends on where you stand and the eyes you bring. The artifact is the landscape; your context is your eyes; the vision is the horizon you walk toward together.


What the loop looks like

Daniel (machine A, Claude Code) drafts and shares:

mirador new q3-strategy        # a markdown++ doc + a one-line vision placeholder
mirador vision q3-strategy --set "board-ready Q3 narrative anchored on NRR"
mirador watch q3-strategy      # live local mirror — watch the HTML morph as your AI drafts
mirador share q3-strategy --with maria@simetrik.com   # private repo + an onboarding seed → clipboard

María (machine B, Codex) pastes the @mirador-invitation block into her agent. It onboards her with zero manual setup — installs the CLI if missing, clones, reads her brain, briefs her, and leaves her refining. She tightens §Retention; her agent auto-drafts the why and pushes:

mirador push q3-strategy --intent "Backed the retention claim with the Q2 NRR figure."

Daniel pulls — and gets a brief shaped by his context, not a raw diff:

$ mirador open q3-strategy

q3-strategy  ·  handoff  ·  since 15f00e7
vision: board-ready Q3 narrative anchored on NRR

CHANGED SECTIONS
  §retention  Retention  —  modified

INTENT NOTES
  e946ed9  maria: Backed the retention claim with the Q2 NRR figure.

His agent reframes that packet through his own memory into a one-screen brief — what changed → why it matters to him → how it moves toward the vision → what to refine next. María's agent and his agent produce visibly different briefs from the same change — because the brains are different. That difference is the product.

$ mirador status q3-strategy

q3-strategy   ·   vision: board-ready Q3 narrative anchored on NRR   ·   owner: daniel
  LOCKED     §1 Summary   §4 Risks
  CONTESTED  §3 Retention (1 open challenge)
  OPEN       §2 Timeline   §5 Appendix

That's the loop: refine through your own AI, every change carries its intent, each reader gets a brief in their own context, the owner steers toward the vision. Async over git — no servers, no realtime channel between users.


The multi-agent flow

You don't actually type those commands. You talk to your agent — Claude Code, Codex, or Gemini — and a thin per-agent shim turns the conversation into mirador calls. The CLI is a deterministic engine (no model inside it); each agent brings the lens and the hands. Same artifact, same protocol, whichever agent each collaborator brings.

                  one artifact · markdown++ in git
           vision: "board-ready Q3, anchored on NRR"
      ┌─────────────────────┼─────────────────────┐
  Claude Code             Codex                 Gemini
   (Daniel)              (María)               (Sofía)
   SKILL.md             AGENTS.md             GEMINI.md     ← thin shims · one contract
      └─────────────────────┼─────────────────────┘
                    mirador CLI · one engine
         parse · render · diff · merge · handoff · status

What it feels like — nobody types a command:

María → Codex: "Daniel shared q3-strategy. Get me in." Codex, silently: installs mirador-cli, clones the repo, runs mirador open, reads María's memory. Codex → María: "You're in. He's anchoring the Q3 board narrative on NRR, and §Retention is hand-wavy — that's your area. Tighten it?" María → Codex: "Yes. Q2 NRR was 112%; cite the board deck." Codex, silently: edits §Retention, then mirador push --intent "Backed the retention claim with the Q2 NRR figure (112%)." --move tighten.

Daniel, on a different agent, pulls:

Daniel → Claude Code: "Anything new on q3-strategy?" Claude, silently: mirador open, reads Daniel's memory. Claude → Daniel: "María backed the NRR claim with the Q2 figure — it de-risks the board number and moves us toward the vision. §3 still has one open challenge. Next: lock §Retention · check §Timeline still matches the date."

Same change, two agents, two brains — and the briefs differ because the brains differ, not because the agents do. What crosses between them is plain text: git commits, intent notes (.mirador/intents/<sha>.md), and paste-able @mirador-* seeds. No agent ever talks to another agent; they converge through git.

AgentReads as your brainShim it installs
Claude Codeauto-memory + project CLAUDE.md~/.claude/skills/mirador/SKILL.md
CodexAGENTS.md~/.codex/skills/mirador/AGENTS.md
GeminiGEMINI.md~/.gemini/skills/mirador/GEMINI.md
anything elseAGENTS.md / CLAUDE.md conventionmanual mode

No supported agent? The CLI is the floor. mirador handoff prints the same packet and mirador push --intent records the same note — the whole loop by copy-paste.


Why it's built this way

  • Brain = your agent's living memory. No wizard, no separate store. Mirador reads what your agent already maintains (Claude memory, CLAUDE.md, AGENTS.md, GEMINI.md). It's strictly private — it never enters git or a handoff packet, only its effects (your refinements, your intent notes) are shared.
  • The artifact is a document, not a page. markdown++ (stable section anchors + fenced chart/table/callout) behind a format seam; HTML is a render target. Two people editing different sections merge cleanly; same section routes to the owner.
  • The collaboration intelligence is invisible. No roles to declare, no vocabulary to learn. The agent shim infers everything. Having mirador makes you collaborate better without learning a system.
  • Model-agnostic, CLI-first. The CLI is a deterministic engine (no LLM calls); each agent gets a thin shim; manual mode (mirador handoff + mirador push --intent) is a clean floor for any agent.
  • No Mirador servers. Your repos on GitHub, your view on your Vercel. Zero hosting cost. The live cockpit is a local read-only mirror, not a hosted frontend.

Setup

npm i -g mirador-cli
mirador init        # detects your agent's memory as your brain — no brain wizard

init confirms your brain source, creates your workspace + Vercel project, and installs the shim for your agent (mirador shim install --agent claude|codex|gemini to add others).


The command surface

CommandWhat it does
mirador new <slug>Scaffold a markdown++ artifact + a vision placeholder
mirador preview <slug>Render the themed HTML view of the source
mirador refine <slug>Open the artifact for refinement through your agent
mirador push <slug> --intent "<why>"Commit a refinement with an auto-drafted intent note
mirador open <slug>Get the brain-shaped handoff for what changed
mirador handoff <slug>Emit the raw handoff packet (manual mode)
mirador diff <slug>Structured, section-level diff
mirador vision <slug> [--set]Show / evolve the vision (owner-gated)
mirador status <slug>Convergence state — locked / contested / open
mirador watch <slug>Live local cockpit (read-only mirror)
mirador share <slug> --with <email>Promote to a shared repo + an onboarding seed
mirador comment <slug> --text "<…>"Compose a paste-back comment (no clone)
mirador brainShow what Mirador reads as your brain (diagnostic)
mirador upgradeMigrate a publish-era install (keeps old docs as broadcast HTML)

Themes

Five purpose-built renderers — shared design tokens, intrinsic light + dark, voice-aligned chrome. They render the markdown++ source; the visual identity is locked in docs/design/spec.md.

ThemeThesisFor
pageThe safe canvas.General content. The default that doesn't apologize.
memoRead with intention.Reports, write-ups, letters. Drop cap, signature block.
deckSlides that scroll.Presentations. scroll-snap, arrow-key nav, counter.
consoleCode is content.Postmortems, scripts. $ > # prompt headings.
atlasNumbers earn the spotlight.Dashboards, data. Tabular figures, KPI cards, sticky tables.

Plus none (publish verbatim).


Password protection

Mirador can encrypt a published view so visitors need a password. Read this before trusting it with anything sensitive.

Encryption is client-side only: AES-GCM with PBKDF2 (200,000 iterations); the password derives the key in the browser at view time. A view-source attacker sees only ciphertext — but it is not real authentication: anyone with the page can run unlimited offline guesses, and someone watching a logged-in browser can grab the decrypted content. Treat it as a deterrent for casual viewing, not protection for confidential data. For real auth, use Vercel Pro's project-level password protection.


What's in this repo

PathWhat's in it
v1/The convergence CLI — document/brain seams, refine + two-brain handoff, vision/owner/state, cockpit, per-agent shims, onboarding, migration. Ships on npm as mirador-cli.
alpha/The publish-era alpha (absorbed, not deprecated). See alpha/README.md.
docs/design/The design system: tokens, voice spec, locked decisions.
docs/superpowers/The convergence design + the CV-00…CV-08 build plan and per-slice sub-plans.

Uninstall

npm uninstall -g mirador-cli
rm -rf ~/.mirador ~/.claude/skills/mirador ~/.claude/commands/mirador.md \
       ~/.codex/skills/mirador ~/.gemini/skills/mirador

License

MIT. See LICENSE.


Same artifact. Your lens. Our vision.

Ver o original no GitHub

Bom para

Relacionados