ToolGraph

ToolGraph is a local-first capability graph for AI agents. It discovers, audits, explains, and routes skills, tools, MCP servers, plugins, permissions, configs, and commands across a user's local agent environment.

The current implementation starts with Codex because this repository is being developed inside a Codex environment.

Planned Scope

ToolGraph's near-term roadmap is focused on six capabilities:

• Tool execution route planning.
• Capability Contract generation.
• Doctor checks for tool usability.
• Risk Score calculation.
• Capability Diff / Snapshot.
• Multi-Agent Adapter support.

Current Features

• Initializes a local SQLite graph database.
• Scans ~/.codex/config.toml.
• Scans Codex skills in ~/.codex/skills.
• Scans project-level AGENTS.md and project MCP config from .mcp.json.
• Scans Cursor project rules, Cursor project MCP config from .cursor/mcp.json, and Cursor user MCP config from ~/.cursor/mcp.json when those files exist.
• Scans Claude Code settings, CLAUDE.md memory files, slash commands, project MCP config, and user/project MCP entries from ~/.claude.json.
• Scans Claude Desktop MCP config from claude_desktop_config.json when present.
• Scans OpenClaw user config, configured agents, gateway, tool profile, plugins, channels, model providers, secret references, and workspace markdown documents from ~/.openclaw.
• Scans Hermes config, MCP servers, toolsets, browser/security/secrets config, auth metadata, .env variable names, SOUL.md, and SKILL.md skills from ~/.hermes.
• Models agent products with family, runtime, and surface metadata so Claude Code and Claude Desktop can share the claude family while remaining distinct runtime nodes.
• Records capability scope as user or project, and can query an effective project view where project capabilities override matching user capabilities.
• Scans cached Codex plugin manifests, plugin skills, linked MCP configs, and connector app configs.
• Associates configured Codex plugins with cached plugin manifests.
• Records agents, skills, plugins, MCP servers, commands, env vars, marketplaces, config files, permissions, secret references, connector tools, and graph edges.
• Extracts initial risk signals from plugin capabilities, remote MCP URLs, missing MCP commands, missing MCP token env vars, and sensitive MCP env var references.
• Calculates numeric risk scores with explainable reasons for discovered capabilities.
• Generates deterministic Capability Contracts from graph relationships, health checks, permissions, and risk scores.
• Builds deterministic tool execution route plans from recommendations, contracts, health status, and risk signals.
• Builds an agent-facing plan-task packet that combines recommendations, execution steps, contracts, health, risk, fallbacks, and next actions.
• Exports a self-contained local HTML graph visualization for inspecting nodes, relationships, filters, and local neighborhoods.
• Exports stable capability snapshots and diffs them across time or machines.
• Provides scan, inventory, list, doctor, risks, explain, edges, graph, visualize, contract, recommend, plan, plan-task, snapshot, diff, and serve --mcp commands.
• Exposes a small MCP server over stdio for capability inventory, health, risks, contracts, explain, recommendation, planning, and snapshot queries.

Install

npm install
npm run build

For local development:

npm run dev -- scan

After building:

node dist/bin/toolgraph.js scan
node dist/bin/toolgraph.js inventory
node dist/bin/toolgraph.js doctor

CLI

toolgraph scan
toolgraph inventory
toolgraph inventory --effective
toolgraph inventory --family claude
toolgraph inventory --runtime claude-code
toolgraph inventory --family hermes
toolgraph inventory --family openclaw
toolgraph list skills
toolgraph list skills --effective
toolgraph list mcp --source claude-desktop
toolgraph explain Codex
toolgraph edges
toolgraph edges github --runtime claude-code
toolgraph graph github
toolgraph visualize
toolgraph visualize --query control-in-app-browser
toolgraph visualize --family codex --output .toolgraph/codex.html
toolgraph risks
toolgraph contract github
toolgraph contract github --json
toolgraph recommend "browse localhost and inspect UI" --family claude
toolgraph plan "browse localhost and inspect UI" --runtime claude-code
toolgraph plan "browse localhost and inspect UI" --json
toolgraph plan-task "browse localhost and inspect UI"
toolgraph plan-task "browse localhost and inspect UI" --json
toolgraph snapshot --output .toolgraph/snapshot.json
toolgraph diff .toolgraph/snapshot-a.json .toolgraph/snapshot-b.json
toolgraph serve --mcp

toolgraph risks reports a 0-100 score and severity level for each risky capability, plus the health, permission, and metadata signals that contributed to the score.

toolgraph contract <id-or-name> reports a deterministic Capability Contract: status, summary, inputs, prerequisites, permissions, config sources, exposed capabilities, health checks, risk score, and guardrails.

toolgraph edges [id-or-name] inspects graph relationships. Without a query it prints all edges; with a query it prints relationships around the matching node. toolgraph graph <id-or-name> prints a node's local graph neighborhood: incoming edges, outgoing edges, identity metadata, and health checks.

toolgraph visualize writes a self-contained HTML graph to .toolgraph/toolgraph.html by default. Use --query <id-or-name> to export a local neighborhood, --type <type> to focus on a node type, and the same multi-agent filters as inventory to inspect one agent family, runtime, surface, source, or scope. The visualization defaults to an Overview mode focused on agents and directly usable capabilities, with Diagnostic, Risk, and Full modes available inside the HTML for deeper inspection.

Inventory, list, edges, visualize, recommend, plan, and plan-task support multi-agent filters:

toolgraph inventory --source claude-code
toolgraph inventory --family claude
toolgraph inventory --runtime claude-desktop
toolgraph inventory --surface cli
toolgraph list mcp --runtime claude-code
toolgraph edges --family claude
toolgraph recommend "review code" --runtime claude-code
toolgraph plan-task "review code" --source claude-code --json

The MCP tools expose the same agent-aware filter model for agent-facing use. For example, an agent can call toolgraph_plan_task or toolgraph_recommend with family: "codex" to restrict the route to Codex capabilities, or with runtime, surface, source, and scope for a more specific view.

toolgraph plan "<task>" builds an explainable execution route plan for a task. ToolGraph plans the route; it does not invoke the tools it recommends. The plan chooses a primary capability, includes prerequisites and permissions, attaches risk guardrails, keeps only strong fallback candidates, and shows the agent/runtime/surface path when a capability is available through an agent.

toolgraph plan-task "<task>" builds the agent-facing task packet: execution plan, recommendations, Capability Contracts, health checks, risk summary, fallbacks, and next actions.

toolgraph snapshot exports a stable JSON manifest of nodes, edges, config files, health checks, and risk scores. toolgraph diff compares two snapshots and reports added, removed, and changed capability graph entries.

By default ToolGraph stores local state at:

.toolgraph/toolgraph.sqlite

Use --db to choose another database path:

toolgraph --db ~/.toolgraph/toolgraph.sqlite scan

Use --codex-home to scan a different Codex home:

toolgraph --codex-home ~/.codex scan

Use --project-root to scan or query a different project context:

toolgraph --project-root /path/to/project scan
toolgraph --project-root /path/to/project inventory --effective

Use --cursor-home to scan a different Cursor home:

toolgraph --cursor-home ~/.cursor scan

Use --claude-home to scan a different Claude Code home:

toolgraph --claude-home ~/.claude scan

Use --claude-desktop-config to scan a different Claude Desktop config file:

toolgraph --claude-desktop-config "~/Library/Application Support/Claude/claude_desktop_config.json" scan

Use --openclaw-home to scan a different OpenClaw home:

toolgraph --openclaw-home ~/.openclaw scan

Use --hermes-home to scan a different Hermes home:

toolgraph --hermes-home ~/.hermes scan

Scope model:

• user: capabilities discovered from the user's agent environment, such as ~/.codex skills, plugins, and MCP servers, user-level Cursor MCP config, Claude Code user files, Claude Desktop config, OpenClaw user config, or Hermes user config.
• project: capabilities discovered from the current project, such as AGENTS.md, project MCP configs, Cursor project rules, Claude Code project memory, and Claude Code project settings.

Effective queries prefer project capabilities over matching user capabilities while keeping non-conflicting user capabilities available.

Development

npm run build
npm run typecheck
npm test
npm run smoke

The project currently uses Node's built-in node:sqlite module. On current Node 22 builds this prints an experimental warning, but does not require a native package install. If this becomes noisy or limiting, replace it with better-sqlite3.

Reference

The local codegraph/ directory is a reference snapshot of colbymchenry/codegraph. It is intentionally ignored by git and should not be treated as ToolGraph source code.

See docs/ROADMAP.md for the product roadmap, docs/ARCHITECTURE.md for module boundaries and feature placement, and docs/USAGE.md for practical CLI and MCP usage.