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

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:

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:

cd backend && go mod download

Install the required code generation tools once:

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 using swag init, while the GraphQL resolver generator reads configuration from 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:

cd ../frontend
npm ci
npm run dev

The UI entry point is 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), 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:

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

This command launches the complete stack defined in 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:

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:

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:

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 for the complete pattern.

2. Register the tool in backend/pkg/tools/tools.go:

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

3. Add API endpoints in backend/pkg/controller/tools.go or create a dedicated controller following the structure of backend/pkg/controller/flow.go.

4. Write tests in backend/pkg/tools/mytool_test.go using the mock executor from backend/cmd/ftester/mocks/tools.go.

5. Regenerate Swagger if you added REST routes:

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:

type ToolResult {
    output: String!
    error: String
}

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

2. Generate resolver stubs:

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

Implement the logic in backend/pkg/graph/resolver.go and the generated backend/pkg/graph/generated.go.

3. Update TypeScript typings on the frontend:

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 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.

3. Ensure your changes align with the existing routing configuration in 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 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 for routing, backend/pkg/graph/schema.graphqls for API definitions, and frontend/src/app.tsx for the UI entry point.
• Use backend/pkg/tools/executor.go when adding new security tools, and register them in 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.

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, and create handlers in backend/pkg/controller/ following the pattern in backend/pkg/controller/flow.go. If exposing via REST, regenerate Swagger documentation using swag init with 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, 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.

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