> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

# Contribute to Warp's open-source terminal

> Learn Warp's issue-first contribution model, the Oz triage agent, readiness labels, and the PR workflow for bugs and feature requests.

Warp's client codebase is fully open source and lives in the [warpdotdev/warp](https://github.com/warpdotdev/warp) repository. Contributions from the community are welcome — but Warp's model works a bit differently from a typical open-source project. The key difference is that **issues are the starting point for everything**: discussion, scoping, and design all happen on the issue before any PR is opened. An automated agent named Oz handles triage and the initial PR review, so the flow is faster and more structured than most projects.

## The contribution model at a glance

<CardGroup cols={2}>
  <Card title="Bug fixes" icon="bug">
    All confirmed bugs are implicitly `ready-to-implement`. Pick up any triaged
    bug and open a code PR — no label or spec is required.
  </Card>

  <Card title="Feature requests" icon="sparkles">
    Features must go through the spec flow first. A maintainer applies
    `ready-to-spec`, you write a product + tech spec, then implement once
    specs are approved.
  </Card>

  <Card title="Oz agent" icon="robot">
    Oz automatically triages incoming issues and is auto-assigned as the first
    reviewer on every PR. After Oz approves, it requests a human SME review.
  </Card>

  <Card title="Spec PRs" icon="file-text">
    Larger features require a `product.md` and `tech.md` under `specs/GH<issue>/`
    before any code is written. The spec PR is the home for design discussion.
  </Card>
</CardGroup>

## Readiness labels

The Warp team applies one of the following labels when an issue is ready for contribution. You do not need to wait for a label to file an issue — labels are applied after triage.

| Label                | Meaning                                                                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ready-to-spec`      | The problem is understood; the design is open. Open a spec PR with `product.md` and `tech.md` under `specs/GH<issue-number>/`. Reserved for feature requests. |
| `ready-to-implement` | The design is settled. Open a code PR. All triaged bugs carry this status implicitly.                                                                         |
| `needs-mocks`        | Design mocks are required before implementation. Wait for the Warp team to land them.                                                                         |

Anyone can pick up a ready issue — readiness labels are not assignments. If an issue has been sitting un-triaged or you want readiness re-evaluated, mention **@oss-maintainers** in a comment.

## The Oz agent

[Oz](https://oz.warp.dev) is Warp's agentic system that automates parts of triage, spec writing, implementation, and review. When you open a PR, Oz is automatically assigned and produces an initial review. Once Oz approves, it automatically requests a follow-up review from the appropriate Warp team subject-matter expert — you do not need to assign human reviewers yourself.

After you address Oz's feedback, comment `/oz-review` on the PR to request a re-review. You can do this up to **three times** per PR. If you need more reviews or something is stuck, mention **@oss-maintainers** on the PR to escalate.

## Contribution flow

```
File an issue
     │
     ▼
Warp team triages (Oz + maintainers)
     │
     ├── ready-to-spec (feature requests)
     │        │
     │        ▼
     │   Open spec PR (product.md + tech.md under specs/)
     │        │
     │        ▼
     │   Specs approved
     │        │
     ├── needs-mocks ──► Design mocks produced
     │                        │
     └── ready-to-implement ◄─┘
              │
              ▼
         Open code PR
              │
              ▼
    Oz review → SME review → CI → merge
```

Steps you own are filing the issue, writing the spec PR, and opening the code PR. The Warp team and Oz handle triage, mock production, and review.

## Filing a good issue

Search [existing issues](https://github.com/warpdotdev/warp/issues) before filing to avoid duplicates. Use the issue templates on GitHub, or use the `/feedback` command inside Warp to open a pre-populated issue with logs and environment details attached.

### Bug reports

A good bug report includes:

<Steps>
  <Step title="Clear title and summary">
    Write a one-sentence title and a one-paragraph summary of the problem.
  </Step>

  <Step title="Steps to reproduce">
    Provide numbered steps with a minimal example wherever possible.
  </Step>

  <Step title="Expected vs. actual behavior">
    Describe what you expected to happen and what actually happened.
  </Step>

  <Step title="Environment details">
    Include your Warp version and OS (found in **Settings → About**).
  </Step>

  <Step title="Supporting artifacts">
    Attach logs, screenshots, or screen recordings when relevant.
  </Step>
</Steps>

### Feature requests

A good feature request focuses on the user-facing problem before proposing a solution:

* The user need or pain point, and who experiences it.
* The current behavior and why it falls short.
* A sketch of the desired behavior or workflow (a mock is helpful but not required).
* Any constraints: compatibility, related features, prior art.

Feature requests go through the spec flow. A maintainer applies `ready-to-spec` when the problem is understood and the design is open. From there, the next step is a spec PR — not a code PR.

## The PR workflow

For issues labeled `ready-to-implement` (including all triaged bugs):

<Steps>
  <Step title="Branch from master">
    Prefix your branch name with your handle, e.g. `alice/fix-parser`.
  </Step>

  <Step title="Implement and test">
    Add a regression test for bug fixes. Add unit tests for algorithmic logic.
    Add integration tests under `crates/integration/` for user-facing flows.
  </Step>

  <Step title="Run presubmit">
    Run `./script/presubmit` and fix all failures before pushing. This runs
    `cargo fmt`, `cargo clippy`, and the test suite.
  </Step>

  <Step title="Open the PR">
    Use the pull request template and add a changelog entry using the appropriate
    prefix: `CHANGELOG-NEW-FEATURE`, `CHANGELOG-IMPROVEMENT`, or
    `CHANGELOG-BUG-FIX`. Omit for docs-only or refactoring changes.
  </Step>

  <Step title="Respond to Oz review">
    Address Oz's feedback and comment `/oz-review` to request a re-review.
    After Oz approves, a Warp SME will be automatically assigned.
  </Step>
</Steps>

<Warning>
  Do not open a code PR for a feature request that does not yet have a
  `ready-to-implement` label. PRs opened against un-labeled feature requests
  will not be reviewed until the spec flow is complete.
</Warning>

## Using a coding agent

You can use any coding agent to implement a contribution — Warp's built-in agent, Claude Code, Codex, Gemini CLI, or others. The repository ships agent-readable context under `.agents/skills/` and `specs/`, and the `WARP.md` file provides an engineering guide any harness can pick up.

If you want an Oz cloud agent to implement a ready issue for you, mention **@oss-maintainers** on the issue. Approved requests run on complimentary Oz credits at no cost to you.

## Becoming a collaborator

Contributors with several merged PRs may be invited to become collaborators, which grants:

* The ability to assign Oz to issues by mentioning `@oz` in any issue with a readiness label.
* Complimentary Oz credits for contributions to this repository.
* Permission to apply and manage issue labels.

## Security issues

Do not open public GitHub issues for security vulnerabilities. Follow the private disclosure process described in `SECURITY.md`.