# How to Contribute to the Pentagi Project: A Complete Developer Guide

> Learn how to contribute to the Pentagi project. Fork the vxcontrol/pentagi repo, set up locally, run tests, and submit a pull request to join the development.

- Repository: [VXControl/pentagi](https://github.com/vxcontrol/pentagi)
- Tags: how-to-guide
- Published: 2026-03-21

---

**To contribute to the Pentagi project, fork the vxcontrol/pentagi repository, configure the Go backend and React frontend locally, run the full test suite, and submit a pull request that passes all CI checks including `go test`, `npm test`, and linting.**

Pentagi is a full-stack autonomous penetration-testing platform combining a Go-based backend with a React and TypeScript frontend. This guide walks you through the exact steps to contribute to the Pentagi project, from cloning the monorepo to submitting production-ready code that integrates with the GraphQL API and observability stack.

## Setting Up the Pentagi Development Environment

Before writing code, you must configure the three primary components: the Go backend, the React frontend, and optionally the full observability stack.

### Cloning the Repository

Start by forking and cloning the repository:

```bash
git clone https://github.com/vxcontrol/pentagi.git
cd pentagi

```

The codebase follows a monorepo structure with clear separation between backend and frontend concerns.

### Configuring the Go Backend

Navigate to the backend directory and install dependencies:

```bash
cd backend && go mod download

```

Install the required code generation tools once:

```bash
go install github.com/swaggo/swag/cmd/swag@v1.8.7
go install github.com/99designs/gqlgen@latest

```

The **Swagger documentation** is generated from [`backend/pkg/server/router.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/server/router.go) using `swag init`, while the **GraphQL resolver generator** reads configuration from [`backend/pkg/graph/gqlgen.yml`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/graph/gqlgen.yml) and the schema from `backend/pkg/graph/schema.graphqls`.

### Configuring the React Frontend

Install exact dependency versions and start the development server:

```bash
cd ../frontend
npm ci
npm run dev

```

The UI entry point is [`frontend/src/app.tsx`](https://github.com/vxcontrol/pentagi/blob/main/frontend/src/app.tsx), which configures the router and application context. The project uses Vite for hot-module reloading (configured in [`frontend/vite.config.ts`](https://github.com/vxcontrol/pentagi/blob/main/frontend/vite.config.ts)), serving the interface on `http://localhost:8000`.

### Running the Full Stack with Docker

For integration testing with Grafana, Loki, Jaeger, and Langfuse, copy the environment file and start Docker Compose:

```bash
cp .env.example .env
docker compose up -d

```

This command launches the complete stack defined in [`docker-compose.yml`](https://github.com/vxcontrol/pentagi/blob/main/docker-compose.yml), including the backend service, databases, and observability tools.

## Running Tests Before Contributing

All contributions must pass the existing test suites for both backend and frontend components.

### Backend Go Tests

Execute the full Go test suite from the `backend` directory:

```bash
cd backend
go test -v ./...

```

Key test packages you should know:
- `backend/pkg/tools/*_test.go` – search-tool and security-tool integrations
- `backend/pkg/controller/*_test.go` – REST and GraphQL request handlers
- `backend/pkg/csum/*_test.go` – LLM chain-summary logic for token budgeting

### Frontend TypeScript Tests

Run Vitest unit tests and generate coverage reports:

```bash
cd ../frontend
npm run test
npm run test:coverage

```

Test failures block merging, so verify all checks pass locally before opening a pull request.

## Common Contribution Scenarios

Depending on your expertise, you might add penetration-testing tools, extend APIs, or improve the user interface.

### Adding a New Penetration Testing Tool

1. **Implement the tool** in `backend/pkg/tools/`. Use the existing executor pattern from [`backend/pkg/tools/executor.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/tools/executor.go):

```go
package tools

import "context"

// MyTool executes the hypothetical mytool binary in a sandboxed container.
func MyTool(ctx context.Context, args []string) (string, error) {
    return ExecuteTool(ctx, "mytool", args)
}

```

Reference existing implementations like [`backend/pkg/tools/duckduckgo.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/tools/duckduckgo.go) for the complete pattern.

2. **Register the tool** in [`backend/pkg/tools/tools.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/tools/tools.go):

```go
var Registry = map[string]Tool{
    "duckduckgo": Duckduckgo,
    "mytool":     MyTool,
}

```

3. **Add API endpoints** in [`backend/pkg/controller/tools.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/controller/tools.go) or create a dedicated controller following the structure of [`backend/pkg/controller/flow.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/controller/flow.go).

4. **Write tests** in [`backend/pkg/tools/mytool_test.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/tools/mytool_test.go) using the mock executor from [`backend/cmd/ftester/mocks/tools.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/cmd/ftester/mocks/tools.go).

5. **Regenerate Swagger** if you added REST routes:

```bash
swag init -g ../../pkg/server/router.go -o pkg/server/docs/

```

### Extending the GraphQL Schema

1. Edit `backend/pkg/graph/schema.graphqls` to add types or queries:

```graphql
type ToolResult {
    output: String!
    error: String
}

extend type Query {
    runTool(name: String!, args: [String!]): ToolResult!
}

```

2. Generate resolver stubs:

```bash
go run github.com/99designs/gqlgen --config ./gqlgen/gqlgen.yml

```

Implement the logic in [`backend/pkg/graph/resolver.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/graph/resolver.go) and the generated [`backend/pkg/graph/generated.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/graph/generated.go).

3. Update TypeScript typings on the frontend:

```bash
npm run graphql:generate

```

This pulls the schema from the backend and creates type definitions under `frontend/src/graphql/`.

### Fixing Frontend UI Issues

1. Locate components in `frontend/src/components/`. For example, modify [`frontend/src/components/ui/Button.tsx`](https://github.com/vxcontrol/pentagi/blob/main/frontend/src/components/ui/Button.tsx) to fix tooltip behavior.

2. Verify your fix with `npm run dev`, then add a Vitest test in [`frontend/src/components/ui/__tests__/Button.test.tsx`](https://github.com/vxcontrol/pentagi/blob/main/frontend/src/components/ui/__tests__/Button.test.tsx).

3. Ensure your changes align with the existing routing configuration in [`frontend/src/app.tsx`](https://github.com/vxcontrol/pentagi/blob/main/frontend/src/app.tsx) and page components in `frontend/src/pages/`.

## Pull Request Requirements

Before submitting your contribution, verify every item in this checklist:

- **Fork and branch**: Create a feature branch (`git checkout -b feat/your-feature`) rather than committing to master.
- **Code style**: Follow `golint` for Go and `eslint`/`prettier` for TypeScript.
- **Documentation**: Update README, CONTRIBUTING, or inline comments to reflect your changes.
- **Test coverage**: Add unit or integration tests covering new code paths in `backend/pkg/tools/*_test.go` or `frontend/src/components/__tests__/`.
- **CI compliance**: Ensure `go test ./...`, `npm test`, and `golangci-lint` pass locally.
- **Changelog**: Include an entry in [`CHANGELOG.md`](https://github.com/vxcontrol/pentagi/blob/main/CHANGELOG.md) if the project maintains one.
- **Description**: Write a clear PR description explaining motivation, implementation details, and testing steps.

The repository uses GitHub Actions defined in `.github/workflows/` to automatically enforce these requirements on every pull request.

## Summary

- **Pentagi** is a Go and React monorepo requiring both backend and frontend setup for full-stack contributions.
- Key architectural files include [`backend/pkg/server/router.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/server/router.go) for routing, `backend/pkg/graph/schema.graphqls` for API definitions, and [`frontend/src/app.tsx`](https://github.com/vxcontrol/pentagi/blob/main/frontend/src/app.tsx) for the UI entry point.
- Use [`backend/pkg/tools/executor.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/tools/executor.go) when adding new security tools, and register them in [`backend/pkg/tools/tools.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/tools/tools.go).
- Always run `go test -v ./...` and `npm run test` before submitting to ensure CI checks pass.
- Follow the pull request checklist including code style compliance, documentation updates, and test coverage.

## Frequently Asked Questions

### Do I need to set up the full Docker stack to contribute to Pentagi?

No, you can contribute to the Pentagi project using only the Go backend and React frontend running locally. The full observability stack (Grafana, Loki, Jaeger, Langfuse) is optional and only required for testing telemetry features or integration scenarios involving [`backend/pkg/observability/otelclient.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/observability/otelclient.go).

### How do I add a new API endpoint for a custom penetration testing tool?

Add your tool implementation in `backend/pkg/tools/`, register it in [`backend/pkg/tools/tools.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/tools/tools.go), and create handlers in `backend/pkg/controller/` following the pattern in [`backend/pkg/controller/flow.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/controller/flow.go). If exposing via REST, regenerate Swagger documentation using `swag init` with [`backend/pkg/server/router.go`](https://github.com/vxcontrol/pentagi/blob/main/backend/pkg/server/router.go) as the general API file.

### What testing framework does Pentagi use for the frontend?

The Pentagi frontend uses **Vitest** for unit testing. Run tests with `npm run test` and generate coverage reports with `npm run test:coverage`. Place new tests adjacent to components, such as [`frontend/src/components/ui/__tests__/Button.test.tsx`](https://github.com/vxcontrol/pentagi/blob/main/frontend/src/components/ui/__tests__/Button.test.tsx), and ensure they pass before submitting your pull request.

### Can I extend the GraphQL schema without breaking the frontend?

Yes, after modifying `backend/pkg/graph/schema.graphqls` and running the `gqlgen` generator, execute `npm run graphql:generate` in the frontend directory. This command synchronizes the TypeScript type definitions in `frontend/src/graphql/` with your backend changes, preventing type mismatches.