Tools Graph

Map your business tools, workflows, and AI opportunities in one knowledge graph.

Documentation · API Reference · Changelog

---

Tools Graph is a knowledge architecture for mapping the relationships between business tools, workflows, roles, and AI opportunities. Built for consultants and operations teams who need to understand how technology connects across an organisation.

---

Quick Start | Usage | Tech Stack | Troubleshooting | Known Issues | Roadmap | Contributing | License

---

Quick start

# Install
npm install @chaimpion/tools-graph

# Run the explorer
npx tools-graph explore ./your-tools.yaml

Requires Node.js 18+. For older versions, use the --legacy flag.

---

Usage

Define your tool landscape

# tools.yaml
tools:
  - name: Slack
    category: communication
    integrates_with: [Google Calendar, Notion]
    ai_opportunity: auto-summarise channels

  - name: HubSpot
    category: crm
    integrates_with: [Slack, Gmail]
    ai_opportunity: lead scoring automation

Generate the graph

npx tools-graph build ./tools.yaml --output graph.html

Query relationships

# Find all tools connected to Slack
npx tools-graph query "connected_to:Slack"

# Find AI opportunities by category
npx tools-graph query "ai_opportunity:*" --group-by category

---

Tech stack

Technology	Purpose
TypeScript	Type-safe graph operations
D3.js	Interactive graph visualisation
YAML	Human-readable tool definitions
SQLite	Local graph database (optional)

---

Troubleshooting

YAML parse error on Windows

Symptom: YAMLException: bad indentation on Windows machines.

Fix: Ensure your editor uses spaces, not tabs. Run npx tools-graph lint ./tools.yaml to validate.

Graph renders blank in Safari

Symptom: HTML output opens but shows an empty canvas.

Fix: Update to Safari 17+. The D3 force layout requires structuredClone support.

---

Known issues

• Graphs with 500+ nodes may be slow to render — #47
• Dark mode colours not yet optimised — workaround: use --theme light

---

Roadmap

• YAML tool definitions
• Interactive HTML graph output
• Query language for relationships
• AI opportunity scoring engine
• Figma plugin for visual editing
• Team collaboration (shared graphs)

---

Feedback

Found a bug? Have a feature request? Open an issue.

---

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

1. Fork the repo
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes
4. Open a Pull Request

---

License

MIT — see LICENSE for details.

---

Built by CHaiMPION