# How to Contribute to the LoopX Open-Source Project

> Learn how to contribute to the LoopX open-source project. Follow our guide to select tasks, set up your environment, and submit your first pull request to the huangruiteng/loopx repository.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-15

---

**To contribute to LoopX, select a task from the public [`CONTRIBUTOR_TASKS.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) board, set up your environment using [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh), create a clean worktree on a `codex/<task-id>` branch, and submit a focused pull request that excludes private runtime state.**

LoopX is an open-source framework that coordinates autonomous agents, schedulers, and host adapters. The project welcomes contributions but enforces strict boundaries between public code and private runtime state to protect sensitive operational data. Understanding the repository structure and workflow defined in [`CONTRIBUTING.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md) ensures your changes are accepted quickly.

## Finding Contribution Opportunities

Start your contribution journey by reviewing the **contributor task board**. The repository maintains a curated list of public, claimable work items at [`CONTRIBUTOR_TASKS.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md)【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTOR_TASKS.md】.

If no existing task matches your skills, open a new GitHub issue using the **contributor task template** referenced in [`CONTRIBUTING.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md). Your issue must describe:

- The specific problem or enhancement
- The intended scope of changes
- The files you plan to modify (e.g., [`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py), [`loopx/visible_multi_agent_launcher.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/visible_multi_agent_launcher.py))
- The validation command you will use to test the change

Wait for maintainer feedback before beginning any large or behavior-changing work to ensure alignment with project goals.

## Respecting Public-Private Boundaries

LoopX stores live agent state in directories that must never be committed. According to the source code in [`CONTRIBUTING.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md), you must never publish:

- Private benchmark traces or verifier output
- Raw session logs or credentials
- Internal document links or absolute local paths

Forbidden paths include `.loopx/`, `.codex/goals/`, and [`ACTIVE_GOAL_STATE.md`](https://github.com/huangruiteng/loopx/blob/main/ACTIVE_GOAL_STATE.md)【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTING.md】.

Safe contribution surfaces include documentation, examples, smoke tests, CLI diagnostics, schema files, UI code, and sanitized fixtures.

Before submitting, run the built-in scan tool to verify no private artifacts are included:

```bash
loopx check \
  --scan-path README.md \
  --scan-path CONTRIBUTING.md \
  --scan-path CONTRIBUTOR_TASKS.md \
  --scan-path docs/ \
  --scan-path examples/

```

## Setting Up Your Development Environment

The repository includes an automation script that installs the package in editable mode and verifies your checkout. Run these commands to initialize your local environment:

```bash
git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh
export PATH="$HOME/.local/bin:$PATH"
loopx doctor          # sanity-check the environment

loopx demo            # run a quick demonstration

```

For comprehensive validation before submitting, install test dependencies and run the full suite:

```bash
python -m pip install -e ".[test]"
python -m ruff check tests loopx/...
python -m mypy
python -m pytest -q
loopx canary premerge --from-git-diff

```

## Making Focused Changes

Once you have selected a task, follow the repository's PR hygiene policy from [`AGENTS.md`](https://github.com/huangruiteng/loopx/blob/main/AGENTS.md) to ensure clean history.

### 1. Claim the Issue

Comment on the GitHub issue announcing you are beginning the task.

### 2. Create a Clean Worktree

Create a dedicated branch named `codex/<task-id>` using Git worktrees:

```bash
git worktree add -b codex/12345 /tmp/codex-12345 main

```

### 3. Implement in Small Increments

Typical source locations for core contributions include:

- **[`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py)** – Core bridge between LoopX runtime and external workers
- **[`loopx/visible_multi_agent_launcher.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/visible_multi_agent_launcher.py)** – Launcher for multi-agent simulations
- **[`loopx/upgrade.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/upgrade.py)** – Upgrade-path logic for runtime versions
- **[`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py)** – Status-server implementation
- **`examples/*.py`** – Smoke-test and usage templates (safe to extend)

Each file is accessible directly via the GitHub UI. For example, [`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py) is available at `https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py`.

### 4. Add Tests

Extend existing smoke tests or create new ones. Use [`examples/worker-bridge-install-contract-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/worker-bridge-install-contract-smoke.py) as a template for proper test structure. Never embed raw prompts, credentials, or private session data in test fixtures.

## Submitting Your Pull Request

Before opening a PR, verify the [`CONTRIBUTING.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md) checklist:

1. **Link the related issue** or task ID in the description
2. **Summarize the behavior change** and validation steps
3. **Keep the PR focused** – avoid unrelated formatting or refactors
4. **Verify exclusion of private files** using `git diff --check` and `loopx check`

Maintainers may request a smaller PR if the change mixes unrelated concerns. A complete workflow from clone to submission looks like:

```bash

# Clone and install

git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh

# Pick a task from CONTRIBUTOR_TASKS.md, then create worktree

git worktree add -b codex/12345 /tmp/codex-12345 main
cd /tmp/codex-12345

# Make focused edits (example: improving worker bridge documentation)

sed -i 's/old text/new text/' loopx/worker_bridge.py

# Validate changes

loopx check --scan-path loopx/
ruff check loopx/
pytest -q

# Commit and push

git add loopx/worker_bridge.py
git commit -m "docs: clarify worker bridge contract (ref #12345)"
git push -u origin codex/12345

# Open PR on GitHub linking the original issue

```

## Summary

- **Find work** in [`CONTRIBUTOR_TASKS.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) or propose new issues using the contributor task template.
- **Protect private data** by never committing `.loopx/`, `.codex/goals/`, or [`ACTIVE_GOAL_STATE.md`](https://github.com/huangruiteng/loopx/blob/main/ACTIVE_GOAL_STATE.md); always run `loopx check` before submitting.
- **Set up locally** using [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) and verify with `loopx doctor` and `loopx demo`.
- **Use clean worktrees** on branches named `codex/<task-id>` as required by [`AGENTS.md`](https://github.com/huangruiteng/loopx/blob/main/AGENTS.md).
- **Focus your PRs** on single concerns, link related issues, and run `ruff`, `mypy`, and `pytest` before requesting review.

## Frequently Asked Questions

### How do I know if a task is available for contribution?

Check the [`CONTRIBUTOR_TASKS.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) file in the repository root for a curated list of public, claimable work items. If you want to work on something not listed there, open a new issue using the contributor task template and wait for maintainer approval before starting large changes.

### What files should I never modify or commit when contributing to LoopX?

Never commit files containing private runtime state, including the `.loopx/` directory, `.codex/goals/` folder, or [`ACTIVE_GOAL_STATE.md`](https://github.com/huangruiteng/loopx/blob/main/ACTIVE_GOAL_STATE.md). Also avoid including benchmark traces, verifier output, session logs, credentials, or absolute local paths in your commits.

### What branch naming convention does LoopX require?

The project requires branches named `codex/<task-id>` for all contributions. Create these using Git worktrees (`git worktree add -b codex/<task-id>`) to maintain a clean development environment as specified in [`AGENTS.md`](https://github.com/huangruiteng/loopx/blob/main/AGENTS.md).

### How do I validate my changes before submitting a pull request?

Run the comprehensive validation pipeline: `ruff check` for linting, `mypy` for type checking, `pytest -q` for tests, and `loopx canary premerge --from-git-diff` for pre-merge checks. Always run `loopx check --scan-path` on your modified files to ensure no private data is included.