# How to Contribute to the Graph Module Development in Hivemind

> Contribute to Hivemind's graph module development by modifying command logic, extending hooks, and validating tests. Follow our seven-step workflow to make your impact.

- Repository: [Activeloop/hivemind](https://github.com/activeloopai/hivemind)
- Tags: how-to-guide
- Published: 2026-06-11

---

**You can contribute to Hivemind's graph module by modifying command logic in [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/src/hooks/graph-pull-worker.ts) handles pulling data from running graph workers
- [`src/hooks/graph-on-stop.ts`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/graph-command.test.ts) for command logic and [`graph-on-stop-main.test.ts`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts) with a new method, register it in the CLI command map in [`src/commands/graph.ts`](https://github.com/activeloopai/hivemind/blob/main/src/commands/graph.ts), and add corresponding tests in [`graph-command.test.ts`](https://github.com/activeloopai/hivemind/blob/main/graph-command.test.ts). This ensures your command integrates with the existing CLI structure.

### Improving Hook Behavior

Modify [`src/hooks/graph-pull-worker.ts`](https://github.com/activeloopai/hivemind/blob/main/src/hooks/graph-pull-worker.ts) or [`src/hooks/graph-on-stop.ts`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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:

```bash

# 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:

```typescript
// 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:

```typescript
// 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`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts) | Core implementation of all graph CLI commands |
| [`src/commands/graph.ts`](https://github.com/activeloopai/hivemind/blob/main/src/commands/graph.ts) | CLI entry point that parses arguments |
| [`src/hooks/graph-pull-worker.ts`](https://github.com/activeloopai/hivemind/blob/main/src/hooks/graph-pull-worker.ts) | Hook for pulling data from running workers |
| [`src/hooks/graph-on-stop.ts`](https://github.com/activeloopai/hivemind/blob/main/src/hooks/graph-on-stop.ts) | Hook for graph shutdown and cleanup |
| [`tests/shared/graph/graph-command.test.ts`](https://github.com/activeloopai/hivemind/blob/main/tests/shared/graph/graph-command.test.ts) | Test suite for command implementation |
| [`tests/shared/graph/graph-on-stop-main.test.ts`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/graph-command.test.ts) and [`graph-on-stop-main.test.ts`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts), then register it in the command map within [`src/commands/graph.ts`](https://github.com/activeloopai/hivemind/blob/main/src/commands/graph.ts). Finally, create a test in [`tests/shared/graph/graph-command.test.ts`](https://github.com/activeloopai/hivemind/blob/main/tests/shared/graph/graph-command.test.ts) that validates the new command's behavior and edge cases.