Skip to main content
This guide covers the process for contributing to Ghostty. Whether you want to report a bug, request a feature, or submit code, please read this document carefully.
Ghostty is a personal project maintained in free time by its contributors. Please take a few minutes to read this guide to ensure your contributions can be reviewed and accepted efficiently. Thank you!

​
The Critical Rule

You must understand your code. If you can’t explain what your changes do and how they interact with the greater system without the aid of AI tools, do not contribute to this project.
Using AI to write code is acceptable, but you must:
  • Fully understand all code you submit
  • Be able to explain design decisions
  • Answer questions about your implementation
  • Have interrogated the AI to grasp all edge cases and effects
See the full AI Usage Policy for details.

​
First-Time Contributors: Vouch System

Ghostty uses a vouch system for first-time contributors to maintain code quality:
1

Open a Vouch Request

Open a discussion in the “Vouch Request” category following the template.
2

Describe your contribution

Keep it concise. Explain:
  • What you want to change
  • Why it’s valuable
  • Your approach (if applicable)
Write in your own voice - don’t have AI write this.
3

Wait for approval

A maintainer will comment !vouch if approved. Once vouched, you can submit pull requests.
Unvouched contributors: Any pull requests you open will be automatically closed. This system exists because AI has made it trivial to generate plausible-looking but low-quality contributions.

​
Denouncement System

If you repeatedly break the rules or submit low-quality work, you will be denounced:
  • Your username will be added to a public list of bad actors
  • All future interactions will be automatically closed
  • Other projects may use this list to block you automatically
We love helping junior developers learn and grow! If you want to learn, don’t rely on AI - ask for help and guidance instead. The denouncement system is for bad actors, not learners.

​
Quick Guide for Contributors

​
I’d like to contribute code

1

Find an actionable issue

Browse the issue tracker. All issues are actionable - every issue is ready to be worked on.Look for issues tagged “contributor friendly” if you’re new.
2

Comment on the issue

Let others know you’re working on it. Ask questions if you need guidance.
3

Read the development guide

See HACKING.md for technical details on building and testing.
4

Submit a pull request

Follow the Pull Request Guidelines below.

​
I’d like to translate Ghostty

Translations are welcome! See the Translator’s Guide. Translations usually don’t need issue triage and can be submitted directly as pull requests. Make sure to follow the Style Guide.

​
I have a bug to report

1

Search existing issues

Search both open and closed issues and discussions - your bug might already be fixed!
2

Open an Issue Triage discussion

If not found, open an “Issue Triage” discussion and fill in the template completely.
Do NOT file bug reports as Q&A or Feature Requests. Use “Issue Triage” for bugs - it collects vital system information.
3

Wait for triage

Maintainers will investigate and move it to the issue tracker if actionable.
If there’s an existing open issue that matches your problem, don’t comment unless you have valuable insight. Use the upvote button or emoji reactions instead to avoid spamming all participants.

​
I have a feature request

1

Search existing discussions and issues

Your feature may have already been requested or implemented.
2

Open a Feature Request discussion

If not found, open a discussion in the “Feature Requests, Ideas” category.
3

Wait for feedback

Maintainers will discuss the feature. If accepted and well-scoped, it will be moved to the issue tracker.

​
I have a question

For general questions:
If your question is about a missing feature, use “Feature Requests”. If Ghostty is behaving unexpectedly, use “Issue Triage”.

​
Important Patterns

​
Issues are Actionable

The Ghostty issue tracker is for actionable items only.
  • Discussions are for bug reports, feature requests, and questions
  • Issues are for well-understood, actionable work
  • Once a discussion reaches a clear action item, it’s moved to the issue tracker
  • This makes it easy to find work that’s ready to start

​
Pull Requests Implement an Issue

Pull requests should be associated with a previously accepted issue.
If you open a pull request for something that wasn’t previously discussed, it may be closed or remain stale indefinitely.
Issues tagged with “feature” represent accepted, well-scoped feature requests. If you implement an issue as described, your PR will likely be accepted.
Pull requests are NOT a place to discuss feature design. Use discussions and link to your branch instead.

​
AI Usage Policy

Ghostty has strict rules for AI usage. Please read the full AI Usage Policy.
All AI usage must be disclosed. State:
  • The tool you used (e.g., Claude Code, Cursor, Amp, GitHub Copilot)
  • The extent of AI assistance
  • What you understand vs what was AI-generated
Key rules:
  • You must fully understand all code you submit
  • No AI-generated media (art, images, videos, audio)
  • Issues and discussions can use AI but must be human-reviewed and edited
  • Bad AI drivers will be denounced
The project welcomes AI as a tool, but holds high standards for contributors who use it. Most AI usage issues stem from unqualified people using AI, not from AI itself.

​
AI Assistance for Development

If you’re using AI to help develop Ghostty:
  • Ghostty provides an AGENTS.md file for AI agents
  • Commands in .agents/commands have vetted prompts for common tasks
  • Example: /gh-issue <number/url> for diagnosing GitHub issues (requires gh CLI)

​
Pull Request Guidelines

1

Link to the issue

Reference the issue your PR implements:
Fixes #1234
2

Write clear commit messages

Focus on the “why” rather than the “what”:
Add support for custom keybindings

Implements #1234. Users can now define custom keybindings
in their config file using the keybind option.
3

Test your changes

Run tests before submitting:
zig build test
4

Format your code

# Zig code
zig fmt .

# Other files
prettier --write .
5

Disclose AI usage (if applicable)

In your PR description, disclose any AI assistance:
AI Disclosure: Used GitHub Copilot for boilerplate code.
All logic was written and verified by me.

​
Development Workflow

For technical details on building, testing, and developing Ghostty: Read HACKING.md - includes:
  • Building from source
  • Development dependencies
  • Running tests
  • Memory leak checking
  • Logging and debugging
  • Platform-specific requirements
Key commands: 
# Build debug version
zig build

# Run Ghostty
zig build run

# Run tests
zig build test

# Run specific tests
zig build test -Dtest-filter=terminal

# Check for memory leaks (Linux)
zig build run-valgrind

# Format code
zig fmt .
prettier --write .

​
Code Standards

​
Zig Code

  • Follow Zig style guidelines
  • Run zig fmt . before committing
  • Write tests for new functionality
  • Document public APIs

​
Documentation and Resources

  • Format with Prettier: prettier --write .
  • Match the Prettier version in nix/devShell.nix
  • Use clear, concise language

​
Commit Messages

  • Summarize the change (add, update, fix, refactor, etc.)
  • Focus on “why” not “what”
  • Reference issue numbers
  • Keep first line under 72 characters
Example: 
Add support for custom color schemes

Fixes #1234. Users can now define custom color schemes in separate
files and reference them from the main config. This makes it easier
to switch between themes.

​
Contributing Documentation

Documentation contributions are welcome:
  • Fix typos or unclear explanations
  • Add examples
  • Improve configuration documentation
  • Write tutorials or guides
Documentation files are in various locations:
  • Main docs: Check the Ghostty website repository
  • Development docs: HACKING.md, CONTRIBUTING.md
  • Translation docs: po/README_TRANSLATORS.md, po/README_CONTRIBUTORS.md

​
Getting Help

If you need help contributing:
Maintainers and community members are happy to help, especially if you’re learning. Don’t be afraid to ask questions!

​
Resources

​
Thank You

Thank you for contributing to Ghostty! Your contributions help make Ghostty better for everyone.
Remember: quality over quantity. A single well-thought-out contribution is worth more than many rushed ones.