GraphyLoop

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%.

1. 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).

1. 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 , 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 mcpgraphyloop (e.g. mcpgraphyloopswarm_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.

1. 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 memory_search] --> G0[Goal + proof state what & check] G0 --> B{Size the work} B -- "inline ≤ 8 known files" --> I[Inline edit any mix of layers] B -- "2+ independent slices (~5+ min each)" --> C[ctx pack + contract ctx-slug.md + contract-slug.md] C --> D[One wave 1–3 lanes, driver keeps a slice] D --> E[Proof, not claims run it, real browser / URL] I --> E E --> F[Report Changed / Files / Verified / Skills / Blocked] F --> G[Record 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- .md (path:line, current code, pattern to copy) so lanes start editing instead of rediscovering.
6. Freeze the contract — contract- .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 wor