Skip to main content
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

1

Fork the repository

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

Clone your fork

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

Set up your development environment

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

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

1

Install dependencies

cd contextfort-dashboard
npm install
2

Start development mode

cd contextfort-dashboard
npm run dev
3

Make your changes

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

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

1

Build the extension

./build-all.sh
2

Load in Chrome

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

Test scenarios

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

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

1

Commit your changes

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

Push to your fork

git push origin feature/my-new-feature
3

Create pull request

Go to the original repository and click New Pull Request
4

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)
5

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:
  1. Search existing issues to avoid duplicates
  2. Provide details:
    • Browser version
    • Extension version
    • Steps to reproduce
    • Expected vs actual behavior
    • Screenshots or logs
  3. 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.

​
Next Steps

Build from Source

Set up your development environment

Architecture

Learn about the system architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us