Skip to main content
Warp’s client codebase is fully open source and lives in the 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

Bug fixes

All confirmed bugs are implicitly ready-to-implement. Pick up any triaged bug and open a code PR — no label or spec is required.

Feature requests

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.

Oz agent

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.

Spec PRs

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.

​
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.
LabelMeaning
ready-to-specThe 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-implementThe design is settled. Open a code PR. All triaged bugs carry this status implicitly.
needs-mocksDesign 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 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 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:
1

Clear title and summary

Write a one-sentence title and a one-paragraph summary of the problem.
2

Steps to reproduce

Provide numbered steps with a minimal example wherever possible.
3

Expected vs. actual behavior

Describe what you expected to happen and what actually happened.
4

Environment details

Include your Warp version and OS (found in Settings → About).
5

Supporting artifacts

Attach logs, screenshots, or screen recordings when relevant.

​
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):
1

Branch from master

Prefix your branch name with your handle, e.g. alice/fix-parser.
2

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.
3

Run presubmit

Run ./script/presubmit and fix all failures before pushing. This runs cargo fmt, cargo clippy, and the test suite.
4

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

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.
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.

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us