# How to Contribute to LoopX: A Complete Guide for Open-Source Contributors

> Learn how to contribute to LoopX with this guide. Follow our steps to set up your environment, make changes, and submit a pull request to the LoopX repository.

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

---

**To contribute to LoopX, select a task from the [`CONTRIBUTOR_TASKS.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) board, respect public-private code boundaries, set up your environment with [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh), make focused changes on a `codex/` branch, and submit a PR that passes `loopx check` and the maintainer checklist.**

LoopX is an open-source framework that coordinates autonomous agents, schedulers, and host adapters. Learning how to contribute to LoopX requires understanding its unique architecture—particularly the strict separation between public code and private runtime state. This guide walks you through the complete contribution workflow as implemented in `huangruiteng/loopx`.

## Finding a Task to Work On

The recommended entry point 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 matched to various skill levels.

If no suitable task exists, 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 include:

- Problem description and intended scope
- Files you will modify
- Command you will use to validate the change

Wait for maintainer feedback before starting large or behavior-changing work.

## Respecting Public-Private Boundaries

LoopX enforces strict boundaries to prevent accidental exposure of sensitive runtime data. Files in `.loopx/`, `.codex/goals/`, and [`ACTIVE_GOAL_STATE.md`](https://github.com/huangruiteng/loopx/blob/main/ACTIVE_GOAL_STATE.md) must never be committed.

According to [`CONTRIBUTING.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md), you must not publish:

- Private benchmark traces
- Verifier output
- Raw session logs
- Credentials
- Internal document links
- Absolute local paths

**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:

```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 [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) to automate environment setup:

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

```

Verify your installation:

```bash
loopx doctor      # sanity-check the environment

loopx demo        # run a quick demonstration

```

For comprehensive validation, 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 a Focused Change

Follow this workflow when contributing to LoopX:

1. **Comment on the issue** to announce you are beginning work
2. **Create a clean worktree** on a dedicated `codex/<task-id>` branch as required by [`AGENTS.md`](https://github.com/huangruiteng/loopx/blob/main/AGENTS.md)
3. **Implement in small increments**

Key source locations for core contributions:

| File | Purpose |
|------|---------|
| [`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 or update tests** using existing smoke tests as templates. Never embed raw prompts, credentials, or private session data in fixtures.

## Submitting a Pull Request

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

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

Maintainers may request a smaller PR if concerns are mixed.

### Complete Contribution Example

```bash

# 1️⃣ Clone and install

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

# 2️⃣ Pick a task from CONTRIBUTOR_TASKS.md, then comment on the issue

# 3️⃣ Create a clean worktree for the change

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

# 4️⃣ Make a small edit (e.g., improve a docstring)

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

# 5️⃣ Run local checks

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

# 6️⃣ 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

# 7️⃣ Open a PR on GitHub linking the issue

```

## Summary

- **Find work** in [`CONTRIBUTOR_TASKS.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) or propose via issue template
- **Respect boundaries**—never commit `.loopx/`, credentials, or session logs; use `loopx check` for verification
- **Set up locally** with [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) and validate with `loopx doctor`
- **Work cleanly** on `codex/` branches with focused, test-backed changes
- **Submit properly** with linked issues, clear summaries, and passing checks

## Frequently Asked Questions

### What files are considered private and cannot be committed?

Private files include everything under `.loopx/`, `.codex/goals/`, and [`ACTIVE_GOAL_STATE.md`](https://github.com/huangruiteng/loopx/blob/main/ACTIVE_GOAL_STATE.md), plus any benchmark traces, verifier output, raw session logs, credentials, internal document links, or absolute local paths. The `loopx check` command scans for these automatically.

### How do I validate my changes before submitting a PR?

Run `loopx doctor` for environment health, `loopx check` to detect private artifacts, `ruff check` for linting, `mypy` for type checking, and `pytest -q` for tests. The `loopx canary premerge --from-git-diff` command provides final pre-submission validation.

### Can I contribute if no tasks match my skills on the public board?

Yes. Open a new issue using the contributor task template from [`CONTRIBUTING.md`](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md), describing your proposed change, target files, and validation approach. Wait for maintainer approval before starting substantial work.

### What branch naming convention does LoopX require?

LoopX requires `codex/<task-id>` branches created via `git worktree add` as documented in [`AGENTS.md`](https://github.com/huangruiteng/loopx/blob/main/AGENTS.md). This maintains PR hygiene and separates active worktrees from your main checkout.