KG Workflow Plugin

Reusable Graphify + GitNexus workflow for local AI coding projects.

KG Workflow helps coding agents work with more project context. It combines:

• Graphify for project-level architecture and concept graphs.
• GitNexus for symbol-level code indexing, impact analysis, and change detection.
• Claude Code / Codex project instructions so the workflow follows each project.

The goal is simple: before an AI assistant edits code, it can understand the project shape, inspect the blast radius, and check what changed before handoff.

Architecture

flowchart LR
  user["Developer / AI coding agent"] --> kgx["kgx CLI"]

  kgx --> deps["install-deps\nGraphify + GitNexus"]
  kgx --> installers["project installers"]
  kgx --> indexes["local project indexes"]

  installers --> claude["Claude Code\ncommands + hooks + skill"]
  installers --> codex["Codex\nAGENTS.md + plugin metadata"]

  indexes --> graphify["graphify-out/\narchitecture graph + report"]
  indexes --> gitnexus[".gitnexus/\nsymbol graph + impact index"]
  indexes --> kgstate[".kg-workflow/\nupdate lock + pending marker"]

  claude --> update["post-write hook\nkgx update"]
  codex --> rules["workflow rules\nimpact before edits"]

  update --> graphify
  update --> gitnexus

  kgx --> impact["kgx impact <symbol>"]
  kgx --> detect["kgx detect-changes"]
  impact --> graphify
  impact --> gitnexus
  detect --> gitnexus

What You Get

• kgx doctor checks whether the required tools and indexes are available.
• kgx install-deps installs Graphify and GitNexus, with hints for custom Python/npm setups.
• kgx init builds a Graphify graph and GitNexus index for a project.
• kgx impact <symbol> shows architecture context, callers, affected files, and related processes before a risky edit.
• kgx detect-changes maps the current git diff back to indexed symbols and execution flows.
• kgx install claude installs Claude Code commands, hooks, and the KG workflow skill into a project.
• kgx install codex adds Codex-facing workflow instructions to AGENTS.md.
• Claude hooks can refresh indexes after writes with a trailing debounce lock.

Install KG Workflow

Choose one install path.

Option A: Install From GitHub With npm

This is the easiest way to get a global kgx command before the package is published to npm:

npm install -g github:xuanweiH/kg-workflow-plugin

Verify:

kgx doctor

Option B: Clone And Symlink

Use this if you want to edit the plugin locally:

git clone https://github.com/xuanweiH/kg-workflow-plugin.git ~/tools/kg-workflow-plugin
~/tools/kg-workflow-plugin/scripts/kgx install-bin

By default this creates:

~/.local/bin/kgx -> ~/tools/kg-workflow-plugin/scripts/kgx

If install-bin says ~/.local/bin is not on your PATH, add this to your shell profile, then restart your shell:

export PATH="$HOME/.local/bin:$PATH"

Option C: npm Registry

After this package is published to npm, install it with:

npm install -g kg-workflow-plugin

Install Prerequisites

kgx needs Graphify and GitNexus. You can let the script install them:

kgx install-deps

That runs the equivalent of:

python3 -m pip install --user graphifyy
npm install -g gitnexus

For custom environments:

kgx install-deps --python-cmd /path/to/python3
kgx install-deps --npm-cmd /path/to/npm
kgx install-deps --break-system-packages
kgx install-deps --skip-graphify
kgx install-deps --skip-gitnexus

If installation fails, kgx install-deps prints targeted hints for common pip/npm, PATH, and permission problems.

Add It To A Project

Go to the project you want AI agents to work on:

cd /path/to/your-project

Install the project workflow:

kgx doctor
kgx install-deps
kgx install claude
kgx install codex
kgx verify-hooks
kgx init

What this adds to your project:

.claude/
  commands/
  hooks/
  skills/kg-workflow/
AGENTS.md
graphify-out/
.gitnexus/
.kg-workflow/

If you only use Claude Code, you can skip kgx install codex.

If you only use Codex, you can skip kgx install claude and kgx verify-hooks.

Claude Code And Codex Support

This repository can be used in three complementary ways:

• npm CLI package: package.json exposes kgx as a global command.
• Claude Code project workflow: kgx install claude installs project-local commands, hooks, and the kg-workflow skill.
• Codex project/plugin workflow: .codex-plugin/plugin.json provides Codex plugin metadata, and kgx install codex writes a managed KG Workflow section into AGENTS.md.

The CLI is the stable entry point. The project installers make Claude Code and Codex aware of the workflow inside each target repository.

Daily Workflow

Before changing a function, class, method, or exported symbol:

kgx impact SomeFunction

After making code changes and before handoff or commit:

kgx detect-changes

When indexes feel stale:

kgx update

To inspect current index status:

kgx status

Commands

kgx install-bin [dir]       # symlink kgx into a bin directory, default ~/.local/bin
kgx install-deps [options]  # install graphifyy and gitnexus prerequisites
kgx doctor                  # check graphify, gitnexus, node, and repo state
kgx install claude          # install Claude commands, hooks, and skill
kgx install codex           # append/update Codex AGENTS.md workflow instructions
kgx init                    # build Graphify graph and GitNexus index
kgx update                  # refresh both indexes with a trailing debounce lock
kgx impact <symbol>         # Graphify context + GitNexus impact/context
kgx detect-changes          # map git diff to indexed symbols/processes
kgx status                  # show index freshness summary
kgx verify-hooks            # smoke-test installed Claude hook wiring

How It Works

kgx init builds two local indexes inside the target project:

• graphify-out/ stores the Graphify knowledge graph and report.
• .gitnexus/ stores the GitNexus code index.

kgx install claude installs lightweight hook wrappers into .claude/hooks/. After file writes, the post-write hook queues kgx update. The update command uses:

• .kg-workflow/update.lock to avoid concurrent index writes.
• .kg-workflow/update.pending to run one trailing refresh if more files changed while an update was already running.

kgx install codex writes a managed KG Workflow section into AGENTS.md, so Codex knows to use Graphify and GitNexus during project work.

Troubleshooting

Plain kgx does not work:

~/tools/kg-workflow-plugin/scripts/kgx install-bin
export PATH="$HOME/.local/bin:$PATH"
kgx doctor

Graphify or GitNexus is missing:

kgx install-deps

Use a custom Python or npm:

kgx install-deps --python-cmd /path/to/python3
kgx install-deps --npm-cmd /path/to/npm

Claude hooks were installed but do not seem active:

kgx verify-hooks

GitNexus query or WAL errors:

gitnexus clean
gitnexus analyze --skills

Repository Layout

kg-workflow-plugin/
  .codex-plugin/plugin.json
  package.json
  skills/kg-workflow/SKILL.md
  scripts/kgx
  hooks/kg-session-start.sh
  hooks/kg-post-write.sh
  templates/claude/commands/
  templates/claude/hooks/
  templates/claude/settings.fragment.json
  templates/codex/AGENTS.fragment.md