Note: CLAUDE.md is the canonical development reference. It is kept up-to-date by AI-assisted tooling and covers build commands, architecture, debugging workflows, and common gotchas in more detail than this file. When the two documents disagree, CLAUDE.md takes precedence.
Guidelines for contributing to par-term, a cross-platform GPU-accelerated terminal emulator built in Rust.
- Overview
- Development Setup
- Build Commands
- Running the Application
- Testing
- Code Quality
- Debug Logging
- Architecture Overview
- Code Style
- macOS-Specific Notes
- Linux-Specific Notes
- Windows-Specific Notes
- Configuration
- Common Development Workflows
- Sub-Crate Architecture
- PR Guidelines
- Commit Message Format
- Related Documentation
par-term is a cross-platform GPU-accelerated terminal emulator frontend written in Rust (Edition 2024). It uses the par-term-emu-core-rust library for VT sequence processing, PTY management, and inline graphics protocols (Sixel, iTerm2, Kitty). The frontend provides GPU-accelerated rendering via wgpu with custom WGSL shaders, including support for Ghostty/Shadertoy-compatible GLSL post-processing shaders.
Language: Rust (Edition 2024) License: MIT Platforms: macOS (Metal), Linux (Vulkan), Windows (DirectX 12)
- Rust stable toolchain — install via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
- Make for build orchestration (available by default on macOS and most Linux distributions)
- Git
No additional system libraries are required. The Metal GPU backend is used automatically.
Install the required GTK3, X11/Wayland, ALSA, and SSL development libraries before building. The package list below mirrors the Linux Dependencies section of the README; both must stay in sync.
Ubuntu/Debian:
sudo apt install libgtk-3-dev libxkbcommon-dev libwayland-dev \
libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev \
libasound2-dev libssl-dev pkg-configFedora/RHEL:
sudo dnf install gtk3-devel libxkbcommon-devel wayland-devel libxcb-devel \
alsa-lib-devel openssl-devel pkg-configArch Linux:
sudo pacman -S gtk3 libxkbcommon wayland libxcb alsa-lib pkg-configNo additional steps are required beyond a working Rust stable toolchain. The DirectX 12 backend is used automatically.
git clone https://github.com/paulrobello/par-term.git
cd par-term
make buildThe first build downloads and compiles all dependencies, which takes several minutes. Subsequent incremental builds complete in roughly 1–2 seconds with make build.
Use
make buildfor all day-to-day development. Thedev-releaseCargo profile (opt-level 2, no LTO, 16 codegen-units, incremental) delivers approximately 90–95% of full-release performance with ~1–2s incremental rebuilds. Only switch tomake build-fullwhen preparing distribution binaries.
| Command | Cargo Profile | Compile Time | Description |
|---|---|---|---|
make build |
dev-release |
~1-2s (incremental) | Optimized, incremental. Preferred for development. |
make build-full |
release |
~3 min | Full LTO, single codegen unit. Use for distribution. |
make build-debug |
debug |
Fast | Unoptimized, includes debug symbols. Use when stepping through code with a debugger. |
make release |
release |
~3 min | Alias for make build-full. |
Output binary locations:
| Profile | Binary |
|---|---|
dev-release |
target/dev-release/par-term |
release |
target/release/par-term |
debug |
target/debug/par-term |
make run # Run in dev-release mode (preferred)
make run-release # Run in full release modeWarning: When stopping a running debug instance, never use
killall par-term. This kills all par-term processes on the system, including the terminal session you are working in. Usepkill -f "target/debug/par-term"or kill by specific PID instead.
When testing your code changes, always run from the build output (make run, cargo run) rather than from an installed .app bundle. An installed bundle will not contain your local changes.
make test # Run all workspace tests
make test-one TEST=test_name # Run a specific test by name
make test-verbose # Run tests with captured output printed to the terminal
cargo test -- --include-ignored # Run all tests, including PTY-dependent onesSome tests require an active PTY session and are marked #[ignore]. The default make test run skips them. To include them explicitly:
cargo test -- --include-ignoredIntegration tests live in the tests/ directory and cover configuration loading, terminal state, and input handling. They use the tempfile crate for isolated temporary files and do not modify real user configuration.
make test-fonts # Comprehensive text shaping and font rendering test suite
make benchmark-shaping # Text shaping performance benchmarks
make test-text-shaping # Run font tests and benchmarks together
make test-graphics # Graphics protocol tests with DEBUG_LEVEL=4 logging
make test-animations # Kitty animation protocol testsRun the full quality suite before every commit:
make checkall # Format, lint, and test — required before committingIndividual targets:
| Command | Tool | Description |
|---|---|---|
make fmt |
cargo fmt |
Format all code with rustfmt |
make fmt-check |
cargo fmt -- --check |
Check formatting without modifying files |
make lint |
cargo clippy -- -D warnings |
Lint with warnings treated as errors |
make lint-all |
cargo clippy --all-targets -- -D warnings |
Lint all targets (bins, tests, examples, benches) |
make check |
cargo check |
Type-check without producing a binary |
make checkall |
fmt-check + lint + typecheck + test | The fast local gate (make check-all is a deprecated alias) |
make pre-commit # fmt-check + lint + test — run this locally before pushing
make ci # fmt-check + lint-all + check-nomux + test + line-count, budget, and terminology gates
make checkall-ci # ci + cargo-deny — the CI-parity gate to pass before pushing
make all # fmt + lint + test + buildmake coverage # Test coverage report via cargo-tarpaulin (must be installed separately)
make audit # Dependency security audit via cargo-audit (must be installed separately)
make profile # CPU profiling with cargo-flamegraph (must be installed separately)
make doc-open # Generate and open rustdoc documentation in a browserpar-term uses a custom debug macro system that writes to par_term_debug.log in the system temp directory ($TMPDIR on macOS, /tmp on Linux, %TEMP% on Windows). The standard log crate macros (log::info!(), log::warn!(), etc.) write to stdout and will not appear in the debug log file.
In one terminal, start par-term with debug logging enabled:
make run-debug # DEBUG_LEVEL=3 — standard debug output → $TMPDIR/par_term_debug.log
make run-trace # DEBUG_LEVEL=4 — most verbose, includes trace eventsIn a second terminal, monitor the log in real time:
make tail-log # Stream all log entries
make watch-graphics # Stream only graphics-related log entriesAlways use these project-specific macros when adding log output to source code:
crate::debug_error!("CATEGORY", "message {}", var); // DEBUG_LEVEL ≥ 1 — errors
crate::debug_info!("CATEGORY", "message {}", var); // DEBUG_LEVEL ≥ 2 — informational
crate::debug_log!("CATEGORY", "message"); // DEBUG_LEVEL ≥ 3 — standard debug
crate::debug_trace!("CATEGORY", "message"); // DEBUG_LEVEL = 4 — trace/verboseCommon log categories: TAB, TAB_BAR, TAB_ACTION, MOUSE, RENDER, SHADER, TERMINAL, APP
For the full logging documentation, see docs/LOGGING.md.
When debugging the Assistant Panel (Claude/Ollama ACP integration):
make acp-harness ARGS="--list-agents" # Verify agent discovery and config loading
make acp-smoke # Run the reproducible shader prompt smoke testSee docs/ACP_HARNESS.md for full usage details and transcript capture.
For a detailed description of the codebase structure, data flow, threading model, and GPU rendering pipeline, see docs/architecture/ARCHITECTURE.md.
Key layers:
App (src/app/)
└── Terminal (par-term-terminal/src/)
└── Renderer (par-term-render/src/)
└── GPU Shaders (par-term-render/src/shaders/)
Data flow:
Window Events → Input Handler → PTY → VT Parser → Styled Segments
→ GPU Renderer (three passes: cells → graphics → egui overlay)
Key implementation patterns:
- Tokio runtime for async PTY I/O; sync wrappers bridge to the winit event loop
- Glyph atlas with instanced rendering for efficient text output
- RGBA texture caching for inline graphics (Sixel, iTerm2, Kitty)
- Scrollback buffer with viewport offset rendering
- Target: Keep all source files under 500 lines.
- Refactor threshold: Any file exceeding 800 lines must be split into sub-modules.
- Follow the existing patterns:
src/app/,par-term-terminal/src/,par-term-render/src/. - Centralize constants; avoid magic numbers scattered across files.
- Prefer composition over duplication; create helper traits for shared functionality.
Use /// doc comments for all public API items (structs, enums, traits, public functions and methods). Use // inline comments for implementation notes and non-obvious logic. Focus comments on why rather than what — the code already shows what is happening.
/// Renders all visible cells for the current viewport into the GPU instance buffer.
///
/// Must be called once per frame before `submit_render_pass`.
pub fn upload_cells(&mut self, cells: &[StyledCell]) { ... }
// Skip zero-width cells — they have no visual representation and will corrupt
// the atlas packing algorithm if submitted.
if cell.width == 0 {
continue;
}- Use
try_lock()from synchronous contexts when accessingtab.terminal(tokio::sync::Mutex). - For user-initiated operations (e.g., start/stop coprocess), use
blocking_lock()instead. - Never call
process::exit()directly — use the graceful shutdown path.
- GPU backend: Metal
- Platform-specific code:
src/macos_metal.rs - App bundle commands:
make bundle # Create par-term.app in target/release/bundle/ make bundle-install # Install .app to /Applications, binary to ~/.cargo/bin, and ACP bridge make run-bundle # Build and launch the .app (shows the correct dock icon)
- When testing code changes, always run from the build output (
make run) rather than the installed.appbundle. The bundle will not reflect your local changes.
- GPU backend: Vulkan
- Both X11 and Wayland display servers are supported.
- Install the required system libraries listed in Platform-Specific Requirements before your first build.
- GPU backend: DirectX 12
- No additional system libraries are required beyond the Rust stable toolchain.
The configuration file uses the XDG base directory convention:
- Linux / macOS:
~/.config/par-term/config.yaml - Windows:
%APPDATA%\par-term\config.yaml
See par-term-config/src/config/config_struct/mod.rs for all available settings and their defaults. For a human-readable reference, see docs/CONFIG_REFERENCE.md.
To generate an example configuration file:
make config-example # Writes config.yaml.example to the project root- Add the field to the sub-config for its area,
par-term-config/src/config/config_struct/<area>_config.rs, not to the rootConfiginconfig_struct/mod.rs, with a serde default attribute:#[serde(default = "default_my_option")] pub my_option: MyType,
- Implement the
default_my_optionfunction and use the same expression in that sub-config'sDefaultimpl. - Use the config value in the relevant component.
- Required: Add UI controls in the appropriate settings tab (
par-term-settings-ui/src/<name>_tab/). Setsettings.has_changes = trueand*changes_this_frame = truewhen the value changes. - Settings search finds the new control by its label and tooltip automatically, as long as it is drawn inside a
collapsing_section/keyword_section. Add.search_tag(&["my_option"])to its response so the YAML key is searchable too.
- Add key handling in
src/app/input_events/(a directory with 6+ files; the main dispatch logic is inkeybinding_actions.rs). - If the shortcut generates a terminal sequence, add sequence generation in
par-term-input/src/key_encoding.rs;InputHandleris defined inpar-term-input/src/lib.rs.
For snippet or action keybindings, see docs/features/SNIPPETS.md. Key points:
- Snippets use
snippet:<id>, actions useaction:<id>as keybinding action names. - Bindings are auto-generated during config load via
generate_snippet_action_keybindings(). execute_keybinding_action()insrc/app/input_events/keybinding_actions.rshandles execution.
par-term is organized as a Cargo workspace with 13 sub-crates plus the root application crate. The dependency graph is a strict layered DAG.
| Layer | Crates | Notes |
|---|---|---|
| Layer 0 | par-term-acp, par-term-ssh, par-term-mcp |
No internal deps; bump in any order |
| Layer 1 | par-term-config |
Foundation; a pure-data crate with no workspace dependencies. It does not depend on par-term-emu-core-rust — the Unicode types it needs are defined locally in src/types/. |
| Layer 2 | par-term-fonts, par-term-input, par-term-keybindings, par-term-scripting, par-term-settings-ui, par-term-terminal, par-term-tmux, par-term-update |
All depend on par-term-config |
| Layer 3 | par-term-render |
Depends on par-term-config and par-term-fonts |
| Layer 4 | par-term (root) |
Depends on all of the above |
When bumping sub-crate versions for crates.io publishing, follow dependency order. Update both the crate's own version field and any version = "..." in dependents' Cargo.toml references.
- Bump
par-term-configversion and update references in all Layer 2/3 crates - Bump Layer 0 crate versions
- Bump Layer 2 crate versions
- Bump
par-term-renderversion and update itspar-term-fontsreference - Update all version references in root
Cargo.toml - Run
cargo checkto verify
- Fork the repository and create a feature branch from
main. - Make atomic commits — one logical change per commit.
- Run
make checkalland confirm it passes without errors before pushing. - Open a pull request against
main. - Describe your changes clearly in the PR body. The PR title and description become the squash commit message on main.
- PRs are merged via squash merge to keep the main branch history linear. Feature branches are deleted after merge.
Each commit should:
- Compile and pass all tests on its own
- Have a single, clear purpose that can be stated in one sentence
- Not mix refactoring with behavior changes
make checkallpasses without errors or warnings- New behavior is covered by tests where practical
- Public API additions carry
///doc comments - Settings additions update both the settings tab and the search keywords
<type>(<scope>): <subject>
[optional body — 72-character wrapped lines explaining what and why]
[optional footer — e.g., Closes #123]
| Type | When to use |
|---|---|
feat |
A new feature |
fix |
A bug fix |
perf |
A performance improvement |
refactor |
Code restructuring with no behavior change |
test |
Adding or correcting tests |
docs |
Documentation only |
style |
Formatting or whitespace, no logic change |
chore |
Build system, dependency updates, tooling |
- Subject line: maximum 50 characters, imperative mood ("add", "fix", "remove"), no trailing period.
- Body: wrap at 72 characters; explain why, not what.
- Footer: reference issues with
Closes #123orFixes #456.
feat(tab-bar): add drag-and-drop reordering for tabs
Users can now drag tabs to reorder them within the tab bar.
Reorder state is persisted to the session arrangement file
so it survives restarts.
Closes #247
fix(renderer): clamp scrollback offset to valid range
A race between the PTY reader and the render thread could
produce a viewport offset larger than the scrollback buffer,
causing an out-of-bounds read in the cell upload path.
perf(render): pre-allocate GPU instance buffers
Avoids per-frame Vec reallocation for the cell and graphics
instance arrays by reserving capacity at startup based on
the initial terminal dimensions.
When cutting a release, verify documentation stays internally consistent. GitHub strips punctuation and lowercases heading text to form anchors, so a heading rename silently breaks TOC links.
- Release notes — replace the contents of the README's
## What's Newsection with the new release's highlights; do not append a second section. The heading is deliberately version-free so its#whats-newanchor never goes stale, and every earlier release already lives inCHANGELOG.md. Put the version in the###subheading beneath it. - TOC anchors — after editing any heading in
README.md, confirm every[link](#anchor)in the Table of Contents still resolves to a heading.make doc-checkcatches this automatically. - Version sync —
Cargo.toml(version) and the top ofCHANGELOG.mdmust agree before tagging.CLAUDE.mddeliberately carries no version line: it had no consumer, silently fell two releases behind, and duplicating a version outside manifests and changelogs is whatdocs/DOCUMENTATION_STYLE_GUIDE.mdadvises against. Do not reintroduce one. - Tag the release —
git tag v<X.Y.Z> <release-commit> && git push origin v<X.Y.Z>. Homebrew SHA, the self-update checker, andgit describeall require the tag to be pushed.
- docs/architecture/ARCHITECTURE.md — Full architecture, data flow, and threading model
- docs/LOGGING.md — Custom debug macro system and log levels
- docs/features/CUSTOM_SHADERS.md — Background and cursor shader development
- docs/CONFIG_REFERENCE.md — All configuration options
- docs/guides/KEYBOARD_SHORTCUTS.md — Default keybinding reference
- docs/features/SNIPPETS.md — Snippet and action keybinding system
- docs/ACP_HARNESS.md — ACP agent debugging harness
- docs/guides/TROUBLESHOOTING.md — Common issues and solutions
- docs/DOCUMENTATION_STYLE_GUIDE.md — Documentation conventions for this project
- CLAUDE.md — Full AI assistant development context and workflow reference