graph-auto

Codex workspace helper for keeping codegraph and graphify updated.

Quick Start

npm install -g codex-graph-auto
graph-auto setup

For source checkout installs:

./install.sh

install.sh installs the graph-auto wrapper into $(npm prefix -g)/bin when npm is available, falling back to ~/.local/bin. Set GRAPH_AUTO_BIN_DIR=/custom/bin to override the CLI path.

setup installs Codex hooks, enables the current workspace when appropriate, creates .graphifyignore, initializes missing graph outputs, and can install git post-commit / post-checkout hooks.

Trigger Model

• graph-auto setup / graph-auto init: initialize missing graph outputs.
• Codex PostToolUse: mark dirty after Codex edits.
• Optional Watchman trigger: mark dirty after non-Codex file changes.
• Git post-commit / post-checkout: run codegraph sync . and graphify . --update.

Codex SessionStart, Stop, and PreCompact do not run graph work.

Options

graph-auto setup --no-git-hooks
graph-auto setup --no-watch
graph-auto setup --no-subprojects
graph-auto setup --scan-root <dir>
graph-auto setup --no-tool-sync
graph-auto setup --update-tools
graph-auto setup --no-init
graph-auto setup --yes-init
graph-auto setup --all-subprojects
graph-auto init
graph-auto configure
graph-auto status
graph-auto git-hooks status
graph-auto watch status

Subprojects

setup detects child directories containing .git, opens a TUI multi-select, and runs setup in selected subprojects. Use --scan-root <dir> to choose a different scan root explicitly.

If the current directory is only a selection root, setup skips parent graph initialization and configures only selected subprojects.

For scripts or CI:

graph-auto setup --all-subprojects

To skip subproject detection:

graph-auto setup --no-subprojects

Subproject git hooks share one .git/graph-auto-workspaces registry, so one parent git hook can update every selected workspace.

Tools

CodeGraph and Graphify run independently. If only one is installed, graph-auto initializes and updates that tool while skipping the missing one.

setup syncs Graphify and CodeGraph Codex integrations. Use --update-tools to force package updates, or --no-tool-sync to skip integration sync.

If Graphify is missing, setup offers:

uv tool install "graphifyy[openai]"

If uv is missing, setup tells you to install uv first. If CodeGraph is missing, setup offers:

npm install -g @colbymchenry/codegraph

If npm is missing, setup asks you to install Node.js/npm first.

Init Safety

Large workspaces can make graphify expensive. setup / init skip graph initialization when the workspace exceeds initMaxFiles unless you confirm in the TUI or pass:

graph-auto setup --yes-init

To configure hooks and subprojects without initializing graph outputs:

graph-auto setup --no-init

Graphify API Setup

graph-auto setup starts the provider wizard when no graphify API key is saved. You can also run it directly:

graph-auto configure

Choose DeepSeek, OpenAI / OpenAI-compatible, Gemini, Anthropic, Kimi, or Custom OpenAI-compatible. For a local router, choose the custom OpenAI-compatible option and fill OPENAI_BASE_URL, OPENAI_API_KEY, and optional GRAPHIFY_MODEL.

graph-auto configure stores values in ~/.codex/graph-auto.env with 0600 permissions.