How to Contribute to the Graph Module Development in Hivemind

You can contribute to Hivemind's graph module by modifying command logic in src/graph/graph-command.ts, extending lifecycle hooks in src/hooks/, and validating changes with tests in tests/shared/graph/ following the repository's seven-step workflow.

The graph module in activeloopai/hivemind enables the creation, manipulation, and execution of data-flow graphs through a layered architecture of CLI commands and asynchronous hooks. Understanding the separation between the command parsing layer, implementation logic, and runtime hooks is essential for anyone looking to contribute to the graph module development effectively.

Understanding the Graph Module Architecture

The graph module follows a strict separation of concerns across four distinct layers. Each layer has specific responsibilities and well-defined entry points for contribution.

Command Layer

The CLI entry point resides in src/commands/graph.ts. This file parses user arguments and forwards them to the internal command implementation. When adding new CLI flags or changing how commands are invoked, this is your starting point.

Command Implementation

All graph-related business logic lives in src/graph/graph-command.ts. This file wires together sub-commands such as add, remove, and list, delegating to appropriate services. Most feature contributions require modifications to this core implementation file.

Hooks

Runtime behavior is managed through two specialized hook files:

• src/hooks/graph-pull-worker.ts handles pulling data from running graph workers
• src/hooks/graph-on-stop.ts executes when a graph stops, managing cleanup and graceful shutdown

These hooks are registered with Hivemind's hook system and provide the asynchronous execution model for graph lifecycle events.

Test Suite

The test suite in tests/shared/graph/ validates both the command-line interface and hook behavior. This directory includes graph-command.test.ts for command logic and graph-on-stop-main.test.ts for hook validation.

Step-by-Step Contribution Workflow

Follow this seven-step process when contributing to the graph module:

1. Clone the repository: git clone https://github.com/activeloopai/hivemind.git
2. Create a feature branch: git checkout -b feature/your-graph-change
3. Modify source code: Edit files under src/graph/ or the related hook files
4. Write tests: Add new tests in tests/shared/graph/ or extend existing ones
5. Run the test suite: Execute npm test to verify all tests pass
6. Update documentation: Amend the README or add Markdown files under docs/ describing API changes
7. Submit a PR: Push your branch and open a Pull Request on GitHub

Common Contribution Scenarios

Adding a New Graph Command

Extend src/graph/graph-command.ts with a new method, register it in the CLI command map in src/commands/graph.ts, and add corresponding tests in graph-command.test.ts. This ensures your command integrates with the existing CLI structure.

Improving Hook Behavior

Modify src/hooks/graph-pull-worker.ts or src/hooks/graph-on-stop.ts to handle new edge cases such as graceful shutdown or resource cleanup. Update the related tests in graph-on-stop-main.test.ts to verify the new behavior.

Refactoring Shared Logic

If you identify duplicated logic between the command layer and hooks, extract it into a shared utility under src/utils/ and adjust imports accordingly. This maintains the separation of concerns while reducing code duplication.

Implementation Examples

Running Existing Graph Commands

Use the CLI to interact with graphs during development:

# List all available graphs

hivemind graph list

# Pull data from a running graph worker

hivemind graph pull --graph-id my_graph

Adding a Custom Graph Command

Extend the command implementation with new functionality:

// src/graph/graph-command.ts
export async function myCustomCommand(args: string[]) {
  // Your implementation here
  console.log('Running my custom command with args:', args);
}

// Register the command in the CLI map
commandMap.set('mycmd', myCustomCommand);

Extending a Hook

Modify runtime behavior by extending the stop hook:

// src/hooks/graph-on-stop.ts
export async function onGraphStop(graphId: string) {
  // Existing shutdown logic …
  console.log(`Graph ${graphId} stopped`);
  // New cleanup step
  await cleanupResources(graphId);
}

Key Files Reference

File	Role
src/graph/graph-command.ts	Core implementation of all graph CLI commands
src/commands/graph.ts	CLI entry point that parses arguments
src/hooks/graph-pull-worker.ts	Hook for pulling data from running workers
src/hooks/graph-on-stop.ts	Hook for graph shutdown and cleanup
tests/shared/graph/graph-command.test.ts	Test suite for command implementation
tests/shared/graph/graph-on-stop-main.test.ts	Tests for on-stop hook behavior

Summary

• The graph module uses a four-layer architecture: CLI commands, implementation logic, runtime hooks, and comprehensive tests
• Key files for contribution are src/graph/graph-command.ts for commands and src/hooks/graph-*.ts for runtime behavior
• Always add tests in tests/shared/graph/ when modifying functionality to ensure future stability
• Follow the seven-step workflow: branch, code, test, document, and submit PR
• Hook modifications require updates to both the implementation file and its corresponding test file

Frequently Asked Questions

How do I test my changes to the graph module locally?

Run the test suite using npm test after making changes. This executes all tests in tests/shared/graph/, including graph-command.test.ts and graph-on-stop-main.test.ts. Ensure your new tests pass alongside existing ones before submitting a pull request.

Where should I place utility functions shared between graph commands and hooks?

Extract shared logic into a new file under src/utils/ and import it into both src/graph/graph-command.ts and the relevant hook files in src/hooks/. This prevents code duplication while maintaining the separation of concerns between the command layer and runtime hooks.

What is the difference between the command layer and hook layer in the graph module?

The command layer in src/commands/graph.ts handles CLI argument parsing and user-facing entry points. The hook layer in src/hooks/ contains asynchronous functions that execute during graph lifecycle events such as startup, data pulling, and shutdown. Commands are user-initiated, while hooks are system-initiated.

How do I add a new sub-command like hivemind graph status?

Add the implementation function to src/graph/graph-command.ts, then register it in the command map within src/commands/graph.ts. Finally, create a test in tests/shared/graph/graph-command.test.ts that validates the new command's behavior and edge cases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}