GraphyLoop

GraphyLoop is a one-command agentic workflow kit for AI coding agents: it wires Claude Code, OpenCode, Codex, Cursor, Gemini CLI, Oh My Pi and DeepSeek Harness with Workflow v3 (inline-first, one parallel wave, proof before done), a 25-agent squad, persistent memory, Agent Skills and an MCP server. It also ships as a Claude Code plugin and an MCP Registry server. Zero dependencies.

Landing page · npm · Harness guide · Reference · llms.txt

Quick Start

Pick one of three install channels:

1. npx installer (all 7 harnesses)

npx graphyloop        # a bare command installs — it wires every harness it detects# restart your harness, open a real project, then ask your agent:/chadi-init

Requires Node.js ≥ 20. On a fresh machine with no harness yet, GraphyLoop wires all seven so you are ready whichever one you open first. Target specific ones with --harness claude,omp. Nothing is written into your workspace — everything lives in your home config (~/.graphyloop/ plus each harness's own directory).

2. Claude Code plugin marketplace

Inside Claude Code:

/plugin marketplace add chadixearth/graphyloop/plugin install graphyloop@graphyloop# then start the workflow with:/graphyloop:chadi-init

The marketplace manifest is .claude-plugin/marketplace.json and the plugin lives at integrations/claude-code/ (15 /graphyloop:chadi-* commands, 26 agents, 3 core skills, and the graphyloop MCP server). Use the plugin OR npx graphyloop --harness claude for Claude Code, not both (installing both registers duplicate tools and agents).

3. MCP Registry

Server name: io.github.chadixearth/graphyloop (server.json). Any MCP client that resolves from the official MCP Registry runs the graphyloop npm package over stdio via:

npx -y graphyloop mcp

Supported harnesses

Per-harness file locations, verification, dsh notes, and the Gemini CLI sign-in change (personal Google sign-ins stopped working on June 18, 2026; an API key still works): docs/harnesses.md.

Setup with any AI assistant (copy-paste)

Paste the block below into your AI harness — it installs, verifies (GRAPH_LOOP_DOCTOR_OK), and reports on its own. Raw copy: docs/SETUP-PROMPT.md.

You are setting up GraphyLoop (github.com/chadixearth/graphyloop, npm package `graphyloop`) — a one-command agentic workflow kit for AI coding agents: a 25-agent squad, parallel wave planning, persistent memory, a harness-neutral workflow and an MCP server that works in any harness. Zero dependencies.
Goal: install it for THIS machine's harness(es), verify the install actually works, and report. Do NOT edit any config file by hand — run only the installer. Do NOT run npm publish, npm login, or anything unrelated.
Steps:1. Prerequisites:   - Run `node --version` — must be 20 or newer. If older, tell the user to install Node.js 20+ and stop there.   - Detect which harnesses exist on this machine (check for any of): ~/.config/opencode/  (OpenCode), ~/.claude.json or ~/.claude/  (Claude Code), ~/.codex/  (Codex), ~/.cursor/  (Cursor / Windsurf), ~/.dsh/ or $DSH_HOME  (DeepSeek Harness / `dsh`), ~/.omp/  (Oh My Pi / `omp`), ~/.gemini/  (Gemini CLI). On Windows, ~ = %USERPROFILE%.2. Install:   - Run:  npx --yes graphyloop     (a bare `graphyloop` is the install command: it wires every detected harness, or all 7 on a fresh machine.)   - To target specific harnesses:  npx --yes graphyloop --harness claude,omp   (names: opencode, claude, codex, cursor, dsh, omp, gemini)   - Optional Claude Code plugin path (use the plugin OR `npx graphyloop --harness claude`, not both): inside Claude Code run `/plugin marketplace add chadixearth/graphyloop` then `/plugin install graphyloop@graphyloop`.   - If npx asks "Ok to proceed?", answer yes. If npx is missing, stop and tell the user to install Node.js 20+ (npx ships with npm).3. Verify — every applicable check must pass:   - `npx --yes graphyloop doctor` prints one row per harness (present / wired) and its LAST line must be GRAPH_LOOP_DOCTOR_OK. If it prints GRAPH_LOOP_DOCTOR_ISSUES <n>, run the `fix:` command it shows for each unwired row, then run doctor again.   - Core engine files exist: ~/.graphyloop/graphyloop/cli.mjs , ~/.graphyloop/mcp-server.mjs , ~/.graphyloop/lib/mcp.mjs , ~/.graphyloop/lib/engine.mjs .   - OpenCode (if present): ~/.config/opencode/opencode.json contains plugin entries "./plugins/graphyloop/plugin.js" and "./plugins/server-guard/plugin.js", and ~/.config/opencode/agents/ contains 26 .md files.   - Claude Code (if present): ~/.claude.json has an mcpServers.graphyloop entry, ~/.claude/rules/graphyloop-workflow.md exists, and ~/.claude/agents/ is populated (unless using the Claude Code plugin instead).   - Codex (if present): ~/.codex/config.toml contains a [mcp_servers.graphyloop] section, and ~/.agents/skills/graphyloop-workflow/SKILL.md exists.   - Cursor (if present): ~/.cursor/mcp.json has a "graphyloop" entry, and ~/.agents/skills/graphyloop-workflow/SKILL.md exists (Cursor uses no home rules file; the workflow loads from ~/.agents/skills/graphyloop-workflow).   - DeepSeek Harness (if present): ~/.dsh/cordis.patch.yml contains a row `id: graphyloop-mcp` naming '@deepseek-ai/dsh-mcp-client', ~/.dsh/AGENTS.md exists, and ~/.dsh/skills/ holds graphyloop-squad. Optional deeper check: `dsh --profile headless --dump-config` prints that row. In dsh the tools are namespaced — call them as mcp__graphyloop__<name> (e.g. mcp__graphyloop__swarm_state).   - Oh My Pi (if present): ~/.omp/agent/mcp.json has mcpServers.graphyloop, and ~/.omp/agent/agents/ holds the squad .md files. An existing ~/.omp/agent/AGENTS.md is intentionally kept — the workflow then loads from the bundled skill graphyloop-workflow.   - Gemini CLI (if present): ~/.gemini/settings.json has mcpServers.graphyloop, ~/.gemini/commands/chadi-init.toml exists, and graphyloop-workflow/SKILL.md exists in ~/.gemini/skills/ (or ~/.agents/skills/ when Codex/Cursor is also installed). An existing ~/.gemini/GEMINI.md is intentionally kept.   - If any check fails: re-run the install with --force (automatic backups) and re-verify. Still failing? Report the exact error and stop.4. Wrap up: tell the user to RESTART their harness (close/reopen the terminal or editor), open a real project (not their home directory), and start the workflow: ask for /chadi-init (OpenCode, Claude Code, Gemini CLI — or /graphyloop:chadi-init with the Claude Code plugin), /prompts:chadi-init (Codex), or "run the graphyloop workflow init" (Oh My Pi, Cursor, Windsurf). In the DeepSeek Harness there are no slash commands: ask the agent to load the `graphyloop-squad` skill instead. Give a one-line summary of what was installed.
Do not ask permission for reversible steps — proceed. Stop only for: Node < 20, an install failure, or a prompt you cannot answer.

How the workflow works

Workflow v3 is harness-neutral: the same 12 rules run in OpenCode, Claude Code, Codex, Cursor, Windsurf, DeepSeek Harness, Oh My Pi and Gemini CLI.

flowchart LR  A[Recall<br/>memory_search] --> G0[Goal + proof<br/>state what & check]  G0 --> B{Size the work}  B -- "inline ≤ 8 known files" --> I[Inline edit<br/>any mix of layers]  B -- "2+ independent slices<br/>(~5+ min each)" --> C[ctx pack + contract<br/>ctx-slug.md + contract-slug.md]  C --> D[One wave<br/>1–3 lanes, driver keeps a slice]  D --> E[Proof, not claims<br/>run it, real browser / URL]  I --> E  E --> F[Report<br/>Changed / Files / Verified / Skills / Blocked]  F --> G[Record<br/>memory_store + why & commit/PR]

1. Recall first, record last — memory_search before planning; memory_store one dense line after, including the why and the commit/PR it landed in.
2. Goal + proof up front — state the end state, the measurable check that proves it, and the invariant it must not break ("prompt the what, not the how"; never weaken a test to make it pass).
3. Inline first (measured) — up to 8 known files in any mix of layers, when the code is known or mappable in one batched read pass; a dispatch costs the driver minutes of waiting while an inline edit costs seconds.
4. Fan out only for 2+ independent slices of about 5+ minutes each — 1–3 lanes (max 4), strictly disjoint files; the driver keeps the largest or most coupled slice and builds it while lanes run.
5. Context pack before dispatch — write ctx-<slug>.md (path:line, current code, pattern to copy) so lanes start editing instead of rediscovering.
6. Freeze the contract — contract-<slug>.md is the only cross-lane dependency.
7. Turn economy — batch reads, first edit by turn 5, done in about 20 turns (40+ = mis-sized).
8. Isolate what collides — a lane that runs servers, databases or browsers gets its own worktree, port and database name.
9. No polling; schedule follow-ups — background jobs or the tool's blocking command; post-deploy checks via the harness's scheduler/loop (e.g. Claude Code /loop or /schedule), never a sleep loop.
10. Proof, not claims — failing-before/passing-after test, real-browser screenshot for UI, before/after numbers from the same machine for performance, the live URL answering for deploys (not "tests pass" alone, typecheck alone, "should work", or a mocked run).
11. Review by blast radius — reviewer/security lanes only for migrations, auth/RBAC, payments, secrets, tenant boundaries, public API contracts and the project's named central files; everything else is covered by proof.
12. Evidence-first report — Changed / Files / Verified (command + verbatim output) / Skills / Blocked.

Keep the rules honest: always-loaded rules stay short while detailed procedures live in skills loaded on demand (progressive disclosure); test workflow guidance with control-vs-treatment runs and delete rules that show no effect; don't hand-manage tokens (compaction works), but persist anything needed after compaction into files (ctx-<slug>.md, contract-<slug>.md, memory). For posters, decks, PDFs and video, the Artifact wave pattern freezes brief-<slug>.md, builds the hero piece first, and fans out one lane per artifact.

The plan_feature MCP tool reports inlineThreshold: 8, writes the contract and context pack, returns the wave plan, and ends every builder lane brief with the turn-economy footer.

Features

Harness alone vs + GraphyLoop

FAQ

What is GraphyLoop?

GraphyLoop is a one-command agentic workflow kit for AI coding agents. It installs a 25-agent squad, parallel wave planning, persistent memory and an MCP server into the harnesses you already use. It is open source (MIT) with zero runtime dependencies.

What changed in Workflow v3?

Workflow v3 (12 rules) raises the measured inline threshold to up to 8 known files (inlineThreshold: 8 in plan_feature), fans out only when there are 2+ independent slices of about 5+ minutes each while the driver keeps the largest or most coupled slice, tightens turn economy to ~20 turns (first edit by turn 5), adds explicit rules for goal + proof up front, isolating colliding resources (worktree, port, DB), scheduling follow-ups instead of polling, proof over claims, and review by blast radius, and adds a "Keep the rules honest" section on progressive disclosure, control-vs-treatment rule testing, and compaction-safe file persistence.

Can I install GraphyLoop as a Claude Code plugin?

Yes. In Claude Code run /plugin marketplace add chadixearth/graphyloop and then /plugin install graphyloop@graphyloop. The plugin (integrations/claude-code/) installs 15 /graphyloop:chadi-* commands, 26 agents, 3 core skills (graphyloop-workflow, graphyloop-waves, swarm-memory) and the graphyloop MCP server. Use the plugin OR npx graphyloop --harness claude, not both, to avoid duplicate tools and agents.

Is GraphyLoop in the MCP Registry?

Yes. It is registered as io.github.chadixearth/graphyloop (defined in server.json) and runs the npm package graphyloop over stdio via npx -y graphyloop mcp. Any MCP client that resolves servers from the MCP Registry can install it by that name.

Does GraphyLoop follow the Agent Skills standard?

Yes. Every bundled skill is a directory with a SKILL.md manifest, and --harness codex and --harness cursor install all 70 bundled skills into ~/.agents/skills — the cross-tool user skills directory read by Codex and Cursor (and also recognized by GitHub Copilot / VS Code and as an alias by Gemini CLI). Untouched shipped skills are refreshed on update, your edited skills are kept, and uninstall removes untouched skills from ~/.agents/skills only when no other GraphyLoop harness using that directory (codex, cursor) stays installed.

Does GraphyLoop work with Claude Code, Cursor and Gemini CLI?

Yes. For Claude Code it registers an MCP server in ~/.claude.json, installs 26 agent files, 15 /chadi-* slash commands, skills and the workflow rule at ~/.claude/rules/graphyloop-workflow.md (or install via the Claude Code plugin instead — use one or the other, not both). For Cursor and Windsurf it adds the MCP server to ~/.cursor/mcp.json and installs the 70 bundled skills into ~/.agents/skills/ — Cursor ignores plain .md files in .cursor/rules/ and keeps global User Rules in its settings UI, so no rules file is written; the workflow loads from the graphyloop-workflow skill in ~/.agents/skills/ (and running workflow init in a project writes <project>/AGENTS.md). For Gemini CLI it adds the MCP server to ~/.gemini/settings.json, installs the commands as TOML files in ~/.gemini/commands/, and installs the bundled skills in ~/.gemini/skills/ (or reuses ~/.agents/skills/ when Codex/Cursor is present) without overwriting an existing GEMINI.md. Note: since June 18, 2026 Google no longer serves personal Google sign-ins in Gemini CLI ("This client is no longer supported for Gemini Code Assist for individuals"); it still works with a Gemini API key, Vertex AI, or a Code Assist Standard/Enterprise license, while Google's successor for individuals — Antigravity CLI (agy) — is not supported yet.

Which other harnesses are supported?

Seven in total: OpenCode, Claude Code, Codex, Cursor, DeepSeek Harness (dsh), Oh My Pi (omp) and Gemini CLI. For Codex, GraphyLoop wires [mcp_servers.graphyloop] in ~/.codex/config.toml, 15 /prompts:chadi-* prompts, AGENTS.md, and the 70 bundled skills in ~/.agents/skills/. Anything else that speaks MCP can use the same server via npx graphyloop mcp or io.github.chadixearth/graphyloop from the MCP Registry. See docs/harnesses.md for what is written where.

Is GraphyLoop free?

Yes. It is MIT licensed and free to use, fork and modify. It uses the model your harness already has; GraphyLoop itself adds no subscription or usage fee.

Does GraphyLoop need API keys?

No. The swarm, memory and MCP tools run locally with no API keys. The only optional key is DEEPSEEK_API_KEY, for letting the engine call DeepSeek directly, and nothing requires it.

How is it different from a plain AGENTS.md or CLAUDE.md?

A rules file is static text that one tool reads. GraphyLoop adds a live engine behind an MCP server (persistent memory, a wave planner that writes the contract and context pack, task and file-ownership tracking) and a 25-agent squad, and installs the same workflow into seven harnesses instead of one.

How do I uninstall GraphyLoop?

Run npx graphyloop uninstall. It removes the MCP entries it added and the agents, commands, skills and rules files that are still byte-identical to what it shipped. It removes the core in ~/.graphyloop/ once no tool uses it, and --harness <name> removes just one tool and leaves the others working. For ~/.agents/skills/, untouched copies are removed only when no Codex, Cursor or Gemini CLI install still uses them. Anything you edited, and all backups, stay.

Does GraphyLoop send my data anywhere, and does it work on Windows?

It sends nothing anywhere: state and memory are plain files in <project>/.graphyloop/, the MCP server runs locally over stdio, and stored credentials are chmod 600 and never returned to the model. It works on Windows, macOS and Linux; CI runs all three on Node 20, 22 and 24, and on Windows a server-guard keeps npm run dev from hanging an agent session.

MCP tools

Once installed, any MCP-capable harness can call:

State and performance details: docs/reference.md. Verify the connection any time:

npx graphyloop doctor   # ends with GRAPH_LOOP_DOCTOR_OK when every present harness is wiredclaude mcp list         # look for: graphyloop ... √ Connectedcodex mcp list          # look for: graphyloop ... enabled

The squad (25 agents)

CLI reference

npx graphyloop                      # same as: install — wires every detected harnessnpx graphyloop install [--harness opencode|claude|codex|cursor|dsh|omp|gemini|all]   # comma list ok: --harness claude,omp                       [--force] [--skip-agents] [--skip-workflow]                       [--no-config-merge] [--config-dir DIR] [--graphyloop-dir DIR]npx graphyloop update [--check]     # refresh an existing install in placenpx graphyloop doctor               # per harness: present / wired / fix: — ends GRAPH_LOOP_DOCTOR_OKnpx graphyloop status [--json]      # swarm status via the graphyloop enginenpx graphyloop uninstall            # remove only what graphyloop addednpx graphyloop mcp                  # run the MCP server directly (stdio)

With no command, bare install flags (--home, --harness, --force, …) still install, but any other flag (--check, --dry-run, --json, a typo like --doctor) exits 1 with unknown option … (no command given) and writes nothing; name the command (graphyloop doctor, graphyloop update --check). Next to an explicit command, unknown flags are ignored.

Safety guarantees (all covered by tests):

• Never overwrites your existing config keys — plugin lists, commands, MCP servers, default_agent, models preserved exactly.
• Every write is preceded by a timestamped backup.
• Re-running is always safe (idempotent).
• Uninstall removes only files byte-identical to the shipped copies — anything you edited is left alone.
• An existing Oh My Pi AGENTS.md or Gemini CLI GEMINI.md is kept, even with --force; the workflow then loads from the bundled graphyloop-workflow skill.

Updates

npx -y graphyloop@latest update           # refresh the install in placenpx graphyloop update --check             # report the drift, write nothingnpx graphyloop doctor                     # installed core version vs this package

update refreshes graphyloop only in the tools it is already installed in. A tool you never added it to stays untouched, and --harness <name> adds one. It overwrites graphyloop-owned files (timestamped backup first), repairs a core tree that is missing newer modules, and leaves your config keys, your own plugins and your edited files alone. --check prints up-to-date / update-available / incomplete / not-installed (add --json for a machine-readable answer) without touching anything. Check doctor first when a graphyloop tool "does not exist" in a harness that is otherwise wired correctly.

Uninstall

npx graphyloop uninstall                    # every toolnpx graphyloop uninstall --harness omp      # just one tool; the others keep working

Removes the agents/prompts/commands it installed and the MCP entries it added, while keeping your config keys, your own files, and all backups. The shared core (~/.graphyloop/) goes with the last tool that uses it.

More documentation

New in 0.6.0 — Workflow v3 + new channels: 12-rule Workflow v3 (inlineThreshold: 8, fan out only for 2+ independent slices while the driver keeps a slice, ~20-turn economy, isolate what collides, schedule follow-ups, proof not claims, review by blast radius, Keep the rules honest); Claude Code plugin marketplace (.claude-plugin/marketplace.json, integrations/claude-code/); MCP Registry server io.github.chadixearth/graphyloop (server.json); and Agent Skills standard (~/.agents/skills for Codex and Cursor). Release notes in CHANGELOG.md and version history in docs/reference.md.

Why this exists

GraphyLoop started as a personal setup — the agents, rules and glue used every day to keep AI coding sessions disciplined, first in OpenCode and then in Claude Code too. It lived in one home directory, copied by hand from machine to machine, and was never meant to leave it.

It got useful enough that keeping it private stopped making sense. This repository is that setup, packaged so it installs anywhere in one command instead of being reassembled by hand — same workflow, same squad, same memory, now shared. Use it, fork it, or take the parts you like. Issues and PRs are welcome.

Support

License

MIT © 2026 Richard Legaspi (@chadixearth)