Contributing

We welcome contributions from the community! This guide will help you get started with contributing to ContextFort.

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.

Getting Started

Fork the repository

Click the Fork button on the ContextFort GitHub repository to create your own copy.

Clone your fork

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

Set up your development environment

Follow the Building from Source guide to set up your local environment.

Create a feature branch

git checkout -b feature/my-new-feature

Use descriptive branch names:

feature/ for new features
fix/ for bug fixes
docs/ for documentation changes
refactor/ for code refactoring

Project Architecture

ContextFort consists of two main components:

Chrome Extension

Built with vanilla JavaScript and Webpack:

background.js - Service worker managing agent detection and rule enforcement
content.js - Content script injected into web pages
popup.js - Extension popup UI logic
manifest.json - Extension configuration and permissions

Dashboard

Built with Next.js 16, TypeScript, and Tailwind CSS v4:

App Router - Next.js file-based routing (src/app/)
React Components - Reusable UI components (src/components/)
Hooks - Custom React hooks (src/hooks/)
Utilities - Helper functions and config (src/lib/)

Development Workflow

Making Changes

Install dependencies

cd contextfort-dashboard
npm install

cd chrome-extension
npm install

Start development mode

cd contextfort-dashboard
npm run dev

cd chrome-extension
npm run watch

Make your changes

Edit the relevant files. The dashboard will hot-reload automatically. For extension changes, reload the extension in chrome://extensions/.

Test your changes

Test the extension with various agent scenarios
Verify dashboard functionality
Check browser console for errors
Test on different websites

Code Style Guidelines

Dashboard (TypeScript/React)

The dashboard uses Biome for linting and formatting. Husky pre-commit hooks run automatically to enforce code quality.

TypeScript: Prefer explicit types over any
Components: Use functional components with hooks
Styling: Use Tailwind CSS v4 utility classes
Accessibility: Include ARIA attributes and keyboard navigation
File naming: Use kebab-case for files, PascalCase for components

// Good
export function SessionCard({ session }: { session: Session }) {
  return (
    <div className="rounded-lg border p-4" role="article" aria-label="Session details">
      {/* Component content */}
    </div>
  );
}

// Avoid
export function SessionCard(props: any) {
  return <div className="card">{/* ... */}</div>;
}

Extension (JavaScript)

ES6+: Use modern JavaScript features
Comments: Document complex logic and agent detection rules
Error handling: Always handle promise rejections
Chrome APIs: Follow Chrome Extension best practices

// Good
try {
  const data = await chrome.storage.local.get('sessions');
  // Process data
} catch (error) {
  console.error('Failed to retrieve sessions:', error);
}

// Avoid
chrome.storage.local.get('sessions', (data) => {
  // No error handling
});

Commit Message Guidelines

Use Conventional Commits format:

# Format
<type>: <description>

# Types
feat:     # New feature
fix:      # Bug fix
docs:     # Documentation changes
style:    # Code style changes (formatting, semicolons, etc.)
refactor: # Code refactoring
test:     # Adding or updating tests
chore:    # Maintenance tasks

Examples

feat: add LinkedIn agent detection
fix: resolve session timestamp parsing issue
docs: update installation instructions
refactor: simplify rule matching logic

Testing Your Changes

Extension Testing

Build the extension

./build-all.sh

Load in Chrome

Load chrome-extension/dist/ as an unpacked extension in chrome://extensions/

Test scenarios

Visit websites with known AI agents (Claude, ChatGPT, etc.)
Verify agent detection and blocking
Check session recording
Test dashboard integration

Check console logs

Open DevTools and check for errors in:

Extension background service worker
Extension popup
Dashboard page
Content scripts on test pages

Dashboard Testing

Test all dashboard routes and navigation
Verify data displays correctly
Test responsive design (mobile, tablet, desktop)
Check dark/light theme support
Validate form inputs and error states

Submitting a Pull Request

Commit your changes

git add .
git commit -m "feat: add new feature"

Push to your fork

git push origin feature/my-new-feature

Create pull request

Go to the original repository and click New Pull Request

Fill out PR template

Provide a clear description:

What changes were made
Why the changes were necessary
How to test the changes
Screenshots (if UI changes)
Related issues (if applicable)

Wait for review

Maintainers will review your PR. Be responsive to feedback and make requested changes.

Pull Request Checklist

Before submitting, ensure:

Code follows the project’s style guidelines
All tests pass (if applicable)
No console errors or warnings
Documentation updated (if needed)
Commit messages follow conventional format
PR description is clear and complete
Screenshots included (for UI changes)
Branch is up to date with main

Where to Contribute

Extension Features

Agent Detection: Add support for new AI agents (chrome-extension/background.js)
Blocking Rules: Enhance rule matching logic
Session Recording: Improve screenshot capture and storage
Performance: Optimize detection algorithms

Dashboard Improvements

UI/UX: Enhance user interface and experience
New Pages: Add analytics, reports, or settings pages
Components: Create reusable UI components (src/components/)
Themes: Design new color schemes (src/styles/presets/)
Data Visualization: Add charts and graphs

Documentation

Guides: Write tutorials and how-to guides
API Docs: Document extension APIs and data structures
Examples: Add usage examples and code snippets
Translations: Help translate documentation

Reporting Issues

For security vulnerabilities, please follow the Security Policy instead of opening a public issue.

When reporting bugs:

Search existing issues to avoid duplicates
Provide details:
- Browser version
- Extension version
- Steps to reproduce
- Expected vs actual behavior
- Screenshots or logs
Use issue templates when available

Feature Requests

We welcome feature suggestions! When proposing features:

Explain the use case and benefits
Describe the expected behavior
Consider potential challenges
Be open to discussion and alternatives

Community & Support

GitHub Issues: Bug reports and feature requests
Discussions: General questions and ideas
Pull Requests: Code contributions

Recognition

All contributors will be:

Listed in project acknowledgments
Credited in release notes
Part of the ContextFort community

Thank you for contributing to ContextFort! Your efforts help make the web safer for everyone.

Resources

Development

Code of Conduct

Getting Started

Project Architecture

Chrome Extension

Dashboard

Development Workflow

Making Changes

Code Style Guidelines

Dashboard (TypeScript/React)

Extension (JavaScript)

Commit Message Guidelines

Examples

Testing Your Changes

Extension Testing

Dashboard Testing

Submitting a Pull Request

Pull Request Checklist

Where to Contribute

Extension Features

Dashboard Improvements

Documentation

Reporting Issues

Feature Requests

Community & Support

Recognition

Next Steps

Build from Source

Architecture

​Code of Conduct

​Getting Started

​Project Architecture

​Chrome Extension

​Dashboard

​Development Workflow

​Making Changes

​Code Style Guidelines

​Dashboard (TypeScript/React)

​Extension (JavaScript)

​Commit Message Guidelines

​Examples

​Testing Your Changes

​Extension Testing

​Dashboard Testing

​Submitting a Pull Request

​Pull Request Checklist

​Where to Contribute

​Extension Features

​Dashboard Improvements

​Documentation

​Reporting Issues

​Feature Requests

​Community & Support

​Recognition

​Next Steps

Build from Source

Architecture

Code of Conduct

Getting Started

Project Architecture

Chrome Extension

Dashboard

Development Workflow

Making Changes

Code Style Guidelines

Dashboard (TypeScript/React)

Extension (JavaScript)

Commit Message Guidelines

Examples

Testing Your Changes

Extension Testing

Dashboard Testing

Submitting a Pull Request

Pull Request Checklist

Where to Contribute

Extension Features

Dashboard Improvements

Documentation

Reporting Issues

Feature Requests

Community & Support

Recognition

Next Steps