Contributing - PentAGI

Welcome Contributors

Thank you for your interest in contributing to PentAGI! This guide will help you get started with the development workflow, code standards, and contribution process.

Getting Started

Prerequisites

Before contributing, ensure you have:

Go 1.24.1+ for backend development
Node.js 23+ and npm for frontend development
Docker & Docker Compose for testing
Git for version control
IDE with Go and TypeScript support (VS Code recommended)

Fork and Clone

Fork the Repository

Click the “Fork” button on the PentAGI GitHub repository

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/pentagi.git
cd pentagi

Add Upstream Remote

git remote add upstream https://github.com/vxcontrol/pentagi.git
git fetch upstream

Create a Branch

git checkout -b feature/your-feature-name

Development Workflow

Setting Up Your Environment

# Navigate to backend directory
cd backend

# Install dependencies
go mod download

# Verify build
go build ./cmd/pentagi

# Run tests
go test ./...

Making Changes

Write Tests First - Follow TDD principles
Implement Your Feature - Keep changes focused
Run Tests - Ensure all tests pass
Update Documentation - Document new features
Commit Changes - Use conventional commits

Code Style Guidelines

Backend (Go)

PentAGI follows standard Go conventions and best practices.

Formatting

# Format code with gofmt
go fmt ./...

# Run linter
golangci-lint run ./...

# Check imports
goimports -w .

Naming Conventions

Packages: Short, lowercase, no underscores (provider, docker, config)
Files: Lowercase with underscores (provider_controller.go)
Types: PascalCase (ProviderController, AgentType)
Functions: PascalCase for exported, camelCase for private (NewProvider, initClient)
Variables: camelCase (providerConfig, maxRetries)
Constants: PascalCase or ALL_CAPS (DefaultTimeout, MAX_WORKERS)

Code Structure

// Good: Clear function signature with error handling
func NewProviderController(cfg *config.Config, queries *database.Queries) (*ProviderController, error) {
    if cfg == nil {
        return nil, errors.New("config cannot be nil")
    }
    
    pc := &ProviderController{
        config:  cfg,
        queries: queries,
    }
    
    return pc, nil
}

// Good: Context-aware functions
func (pc *ProviderController) ExecuteTask(ctx context.Context, taskID int64) error {
    // Check context before heavy operations
    select {
    case <-ctx.Done():
        return ctx.Err()
    default:
    }
    
    // Implementation
    return nil
}

// Good: Proper error wrapping
func (pc *ProviderController) LoadProvider(name string) error {
    provider, err := pc.loadFromDB(name)
    if err != nil {
        return fmt.Errorf("failed to load provider %s: %w", name, err)
    }
    return nil
}

Comments

// Package provider implements LLM provider management and interaction.
//
// It supports multiple provider types including OpenAI, Anthropic, Gemini,
// AWS Bedrock, Ollama, and custom providers.
package provider

// ProviderController manages LLM provider lifecycle and request routing.
// It handles provider initialization, model selection, and request execution
// with support for streaming, tool calling, and observability.
type ProviderController struct {
    config  *config.Config
    queries *database.Queries
}

// ExecuteTask executes a penetration testing task using the configured provider.
// It returns an error if the task execution fails or the context is cancelled.
func (pc *ProviderController) ExecuteTask(ctx context.Context, taskID int64) error {
    // Implementation
}

Frontend (TypeScript/React)

The frontend follows React and TypeScript best practices.

Formatting

# Check formatting
npm run prettier

# Fix formatting
npm run prettier:fix

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

Naming Conventions

Files: PascalCase for components (Terminal.tsx), camelCase for utilities (api.ts)
Components: PascalCase (TerminalView, AgentCard)
Functions: camelCase (handleSubmit, fetchFlows)
Variables: camelCase (isLoading, flowData)
Constants: UPPER_SNAKE_CASE (API_URL, MAX_RETRIES)
Types/Interfaces: PascalCase with descriptive names (FlowData, AgentProps)

Component Structure

// Good: Functional component with TypeScript
import React, { useState, useEffect } from 'react';
import { FlowData } from '@/types';

interface FlowCardProps {
  flow: FlowData;
  onSelect: (id: string) => void;
}

export const FlowCard: React.FC<FlowCardProps> = ({ flow, onSelect }) => {
  const [isExpanded, setIsExpanded] = useState(false);
  
  useEffect(() => {
    // Side effects
  }, [flow.id]);
  
  return (
    <div className="flow-card">
      {/* Component JSX */}
    </div>
  );
};

// Good: Custom hooks
export const useFlows = () => {
  const [flows, setFlows] = useState<FlowData[]>([]);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    // Fetch flows
  }, []);
  
  return { flows, loading };
};

GraphQL Integration

// Good: Using generated types and hooks
import { useGetFlowsQuery, Flow } from '@/graphql/generated';

export const FlowList = () => {
  const { data, loading, error } = useGetFlowsQuery({
    variables: { limit: 10 },
  });
  
  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;
  
  return (
    <div>
      {data?.flows.map((flow: Flow) => (
        <FlowCard key={flow.id} flow={flow} />
      ))}
    </div>
  );
};

Commit Message Convention

PentAGI uses Conventional Commits for clear and automated changelogs.

Format

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, no logic change)
refactor: Code refactoring
perf: Performance improvements
test: Adding or updating tests
chore: Maintenance tasks (dependencies, build, etc.)
ci: CI/CD changes

Examples

# Good commit messages
feat(providers): add support for DeepSeek API

fix(docker): resolve container permission issues

docs(readme): update installation instructions

refactor(agents): simplify agent initialization logic

test(etester): add tests for embedding search

chore(deps): update go dependencies to latest versions

Commit Best Practices

Atomic Commits

Each commit should represent a single logical change

Clear Messages

Write descriptive messages explaining what and why

Reference Issues

Include issue numbers when applicable (#123)

Sign Commits

Use GPG signatures for verified commits

Pull Request Process

Before Submitting

Update Your Branch

git fetch upstream
git rebase upstream/master

Run All Tests

# Backend tests
cd backend && go test ./...

# Frontend tests
cd frontend && npm test

# Integration tests
docker compose up -d
docker exec pentagi /opt/pentagi/bin/ctester -type openai

Check Code Quality

# Backend
golangci-lint run ./...
go fmt ./...

# Frontend
npm run lint:fix
npm run prettier:fix

Update Documentation

Document any new features, configuration options, or API changes

Creating a PR

Push Your Branch

git push origin feature/your-feature-name

Open Pull Request
- Go to your fork on GitHub
- Click “Compare & pull request”
- Fill in the PR template

PR Title Format

feat(scope): Brief description of changes

PR Description Template

## Description
Brief description of what this PR does.

## Motivation
Why is this change needed?

## Changes
- Added feature X
- Fixed bug Y
- Updated documentation Z

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing performed

## Screenshots (if applicable)

## Related Issues
Closes #123

## Checklist
- [ ] Code follows style guidelines
- [ ] Tests pass locally
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

PR Review Process

Automated Checks
- CI/CD pipeline runs tests
- Code coverage reports generated
- Linting and formatting checks
Code Review
- Maintainers review your code
- Address feedback and comments
- Push updates to your branch
Approval & Merge
- PR approved by maintainers
- Squash and merge to master
- Automatic deployment (if applicable)

Development Tips

Use Testing Tools

Leverage ctester, etester, and ftester for comprehensive testing

Check Examples

Review examples/ directory for configuration and usage patterns

Read Architecture

Understand the system design before making changes

Ask Questions

Join Discord/Telegram for discussions and support

Project Structure

pentagi/
├── backend/
│   ├── cmd/              # Command-line tools
│   │   ├── pentagi/      # Main application
│   │   ├── ctester/      # Compatibility tester
│   │   ├── etester/      # Embedding tester
│   │   ├── ftester/      # Function tester
│   │   └── installer/    # Interactive installer
│   ├── pkg/              # Shared packages
│   │   ├── config/       # Configuration management
│   │   ├── database/     # Database layer (SQLC)
│   │   ├── docker/       # Docker client
│   │   ├── graph/        # GraphQL resolvers
│   │   ├── providers/    # LLM provider implementations
│   │   ├── agents/       # Agent logic
│   │   └── observability/ # Telemetry and monitoring
│   ├── migrations/       # Database migrations
│   └── go.mod           # Go dependencies
├── frontend/
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── pages/        # Page components
│   │   ├── graphql/      # GraphQL queries
│   │   ├── hooks/        # Custom hooks
│   │   └── utils/        # Utility functions
│   ├── public/           # Static assets
│   └── package.json      # npm dependencies
├── examples/
│   ├── configs/          # Provider configurations
│   └── guides/           # Setup guides
├── observability/        # Grafana dashboards
├── Dockerfile            # Multi-stage build
├── docker-compose.yml    # Main stack
└── README.md            # Project documentation

Common Development Tasks

Adding a New LLM Provider

Create Provider Package

mkdir backend/pkg/providers/newprovider
touch backend/pkg/providers/newprovider/provider.go

Implement Provider Interface

Implement the Provider interface from backend/pkg/providers/provider

Add Configuration

Create YAML config in examples/configs/newprovider.provider.yml

Add Tests

touch backend/pkg/providers/newprovider/provider_test.go

Update ctester

Add provider type to ctester command-line options

Adding a Frontend Component

Create Component File

touch frontend/src/components/NewComponent.tsx

Implement Component

import React from 'react';

interface NewComponentProps {
  title: string;
}

export const NewComponent: React.FC<NewComponentProps> = ({ title }) => {
  return <div>{title}</div>;
};

Add Tests

touch frontend/src/components/NewComponent.test.tsx

Export Component

Add to frontend/src/components/index.ts

Database Schema Changes

Create Migration

cd backend/migrations
touch $(date +%Y%m%d%H%M%S)_add_new_table.sql

Write Migration

-- +goose Up
CREATE TABLE new_table (
    id BIGSERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- +goose Down
DROP TABLE new_table;

Update SQLC Queries

Add queries to backend/sqlc/queries.sql

Generate Code

cd backend
sqlc generate

Resources

GitHub Repository

Source code and issue tracker

Discord Community

Join discussions and get help

Telegram Group

Connect with other developers

Documentation

Complete documentation

Code of Conduct

PentAGI follows a code of conduct to ensure a welcoming environment:

Be Respectful: Treat all contributors with respect
Be Constructive: Provide helpful feedback in reviews
Be Patient: Help newcomers learn and grow
Be Professional: Keep discussions focused and appropriate
Be Ethical: Only use PentAGI for authorized security testing

License

By contributing to PentAGI, you agree that your contributions will be licensed under the MIT License.

Questions?

If you have questions about contributing:

Open a GitHub Discussion
Ask in Discord or Telegram
Email the maintainers

Thank you for contributing to PentAGI!

Get Started

Core Concepts

Configuration

Deployment

Features

Development

Documentation Index

​Welcome Contributors

​Getting Started

​Prerequisites

​Fork and Clone

​Development Workflow

​Setting Up Your Environment

​Making Changes

​Code Style Guidelines

​Backend (Go)

​Formatting

​Naming Conventions

​Code Structure

​Comments

​Frontend (TypeScript/React)

​Formatting

​Naming Conventions

​Component Structure

​GraphQL Integration

​Commit Message Convention

​Format

​Types

​Examples

​Commit Best Practices

Atomic Commits

Clear Messages

Reference Issues

Sign Commits

​Pull Request Process

​Before Submitting

​Creating a PR

​PR Review Process

​Development Tips

Use Testing Tools

Check Examples

Read Architecture

Ask Questions

​Project Structure

​Common Development Tasks

​Adding a New LLM Provider

​Adding a Frontend Component

​Database Schema Changes

​Resources

GitHub Repository

Discord Community

Telegram Group

Documentation

​Code of Conduct

​License

​Questions?

Build docs developers (and LLMs) love

Welcome Contributors

Getting Started

Prerequisites

Fork and Clone

Development Workflow

Setting Up Your Environment

Making Changes

Code Style Guidelines

Backend (Go)

Formatting

Naming Conventions

Code Structure

Comments

Frontend (TypeScript/React)

Formatting

Naming Conventions

Component Structure

GraphQL Integration

Commit Message Convention

Format

Types

Examples

Commit Best Practices

Pull Request Process

Before Submitting

Creating a PR

PR Review Process

Development Tips

Project Structure

Common Development Tasks

Adding a New LLM Provider

Adding a Frontend Component

Database Schema Changes

Resources

Code of Conduct

License

Questions?