# How to Contribute to LoopX: From Setup to Your First Pull Request

> Contribute to LoopX by selecting a task, setting up your environment with install-local.sh, and submitting your first pull request. Learn LoopX contribution steps.

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

---

**To contribute to LoopX, select a task from the public contributor board in [`CONTRIBUTOR_TASKS.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md), configure your environment using [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh), and submit changes from a dedicated worktree branch following the strict public-private boundary rules enforced by the `loopx check` tool.**

LoopX is an open-source framework that coordinates autonomous agents, schedulers, and host adapters. Contributing to this repository requires understanding its unique architecture that separates public code from private runtime state. This guide walks you through the entire contribution workflow according to the standards defined in [`CONTRIBUTING.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md).

## Finding Contribution Tasks

The recommended entry point for new contributors is the **contributor task board** located at [`CONTRIBUTOR_TASKS.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) in the repository root. This curated list contains public, claimable work items organized by complexity and domain.

If the existing board does not match 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 problem, intended scope, specific files you plan to modify (such as [`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py) or [`loopx/visible_multi_agent_launcher.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/visible_multi_agent_launcher.py)), and the validation command you will use to verify the change. Wait for maintainer approval before beginning substantial work.

## Respecting Public-Private Boundaries

LoopX maintains strict boundaries between public source code and private runtime state. The contribution guidelines explicitly forbid committing:

- Private benchmark traces
- Verifier output and raw session logs
- Credentials and internal document links
- Absolute local paths
- Runtime state files in `.loopx/`, `.codex/goals/`, or [`ACTIVE_GOAL_STATE.md`](https://github.com/huangruiteng/loopx/blob/main/ACTIVE_GOAL_STATE.md)

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

Always run the built-in scan tool before committing to ensure 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 the following commands to bootstrap your 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 changes, install test dependencies and run the full quality 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

When you begin work on a task, follow this precise workflow:

1. **Comment on the issue** to announce you are claiming the task.
2. **Create a clean worktree** on a dedicated branch named `codex/<task-id>`, as required by the PR hygiene policy in [`AGENTS.md`](https://github.com/huangruiteng/loopx/blob/main/AGENTS.md).
3. **Implement in small increments.** Key files 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 examples (safe to extend)
4. **Add tests** using existing smoke tests like [`examples/worker-bridge-install-contract-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/worker-bridge-install-contract-smoke.py) as templates. Avoid embedding raw prompts or credentials in test fixtures.

Example workflow for creating a worktree:

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

# Make your changes here

```

## Submitting Your Pull Request

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

- Link the related issue or task ID in the description.
- Summarize the behavior change and validation steps.
- Keep the PR focused—avoid unrelated formatting or refactors.
- Verify no private/runtime files are included by running `git diff --check` and `loopx check`.

Maintainers may request that you split large PRs if changes mix unrelated concerns. The repository requires worktrees for isolation, ensuring your `codex/<task-id>` branch contains only the intended modifications.

## Summary

- **Find work** in [`CONTRIBUTOR_TASKS.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) or propose new tasks via GitHub issues with detailed scope descriptions.
- **Respect boundaries** 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.
- **Configure locally** using [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) and validate with `loopx doctor`, `ruff check`, `mypy`, and `pytest`.
- **Isolate changes** in dedicated worktrees on `codex/<task-id>` branches as mandated by [`AGENTS.md`](https://github.com/huangruiteng/loopx/blob/main/AGENTS.md).
- **Target safe surfaces** like [`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py), examples, and documentation while avoiding private runtime data.

## Frequently Asked Questions

### How do I choose my first task to contribute to LoopX?

Start by reading [`CONTRIBUTOR_TASKS.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) in the repository root, which contains a curated list of public tasks categorized by complexity. Select an item that matches your familiarity with the codebase—documentation fixes and example updates in `examples/` are ideal starting points. If no suitable task exists, create a new issue using the contributor task template and wait for maintainer feedback before coding.

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

Never commit runtime state directories including `.loopx/`, `.codex/goals/`, or the [`ACTIVE_GOAL_STATE.md`](https://github.com/huangruiteng/loopx/blob/main/ACTIVE_GOAL_STATE.md) file. Additionally, avoid including private benchmark traces, verifier output, raw session logs, credentials, internal document links, or absolute local paths. Use the `loopx check` command to scan your changes before submission to ensure compliance.

### Which source files are safe for first-time contributors to modify?

Safe targets include documentation, the `examples/` directory (particularly smoke tests like [`worker-bridge-install-contract-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/worker-bridge-install-contract-smoke.py)), CLI diagnostics, and UI code. Core implementation files such as [`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), [`loopx/upgrade.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/upgrade.py), and [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) are also open for contributions, provided you follow the worktree branching strategy and include appropriate tests.

### What is the required branch naming convention for LoopX contributions?

LoopX requires contributors to use the worktree-based workflow specified in [`AGENTS.md`](https://github.com/huangruiteng/loopx/blob/main/AGENTS.md). Create your branch using the format `codex/<task-id>` (for example, `codex/12345`) when running `git worktree add -b codex/12345`. This isolation ensures clean PRs that contain only the specific changes related to your claimed task.