CONTRIBUTING.md

Contributing

Thanks for wanting to help. Issues, PRs, and ideas are all welcome.

Quick start

pnpm install
pnpm tauri dev

Prereqs: Rust (stable), Node 20+, pnpm, plus your platform's Tauri prerequisites.

Before opening a PR

Run these and make sure they pass:

pnpm exec tsc --noEmit          # frontend types
cd src-tauri && cargo clippy    # Rust lint
cd src-tauri && cargo fmt       # Rust format

Build a release bundle at least once if you touched anything in src-tauri/:

pnpm tauri build

Branches

Branch off main. Use these prefixes (kebab-case):

Prefix	Use for
feat/	New feature
fix/	Bug fix
chore/	Refactor, tooling, config, dependencies
docs/	Docs-only changes
perf/	Performance work

Examples: feat/split-panes, fix/explorer-focus, chore/windows-bundle-config.

Don't open PRs from your fork's main branch — it makes future syncs painful for you. Always work on a feature branch.

Issues first for non-trivial work

For anything beyond a typo, a small bug fix, or a clear good-first-issue — open an issue first and wait for a maintainer to ack the approach. A 10-minute conversation saves a 500-line PR that doesn't fit the roadmap.

If an issue already exists for what you want to do, comment "I'll take this" before starting so we don't duplicate work.

What we want

• Bug fixes — always.
• Features — open an issue first if it's non-trivial. We'd rather discuss the approach than reject a finished PR.
• Docs / typos / small UX fixes — just send the PR.
• New AI providers — see src/modules/ai/providers/. Keep BYOK; no hardcoded keys.
• Themes / icon packs — yes, but keep the bundle size in check.

What we don't want

• Telemetry, analytics, or anything that phones home.
• Hardcoded API keys or accounts. Terax stays BYOK.
• Large dependencies for small wins. The bundle is ~7 MB and we want it to stay light.
• Sweeping refactors with no functional change.

Code style

• Follow the existing patterns. Read adjacent files before adding new ones.
• TypeScript: no any unless you really mean it.
• Rust: cargo fmt + clippy clean.
• Few comments. Code should explain itself; comments are for the why, not the what.
• No emoji in code or commit messages.

Commits & PRs

We squash-merge every PR — the PR title becomes the squash commit, so it should follow Conventional Commits:

feat(terminal): add split panes
fix(explorer): prevent input from disappearing on create
chore(deps): bump tauri to 2.x
docs(readme): clarify Linux install on Arch

Types: feat, fix, chore, docs, perf, refactor, test, build, ci. Common scopes: terminal, editor, explorer, pty, ai, settings, tabs, shortcuts, agents, ui.

Within a PR, individual commit messages can be whatever — they get squashed.

One logical change per PR. A PR that adds a feature, fixes an unrelated bug, and reformats .gitignore is three PRs. Split them.

Open a draft PR early if you want feedback mid-flight; mark "Ready for review" when done. Fill out the PR template — what changed, why, how you tested. Include screenshots / GIFs for any UI change.

What gets merged faster

• Clear problem statement
• Small, focused diff
• Follows existing patterns (read 2-3 nearby files before writing yours)
• pnpm exec tsc --noEmit clean
• Manual testing notes ("I tested by doing X, Y, Z")

What gets bounced back

• Mixed-concern PRs ("split this please")
• Large architectural PRs without prior discussion
• New dependencies without justification
• Breaking changes without migration notes
• Incidental reformatting unrelated to the change (adds noise to review)
• AI-generated code that obviously wasn't read by the author

Project layout

src-tauri/        Rust backend — PTY, FS, shell, plugins
src/
  modules/
    terminal/     xterm.js sessions + OSC handlers
    editor/       CodeMirror stack
    explorer/     File tree
    tabs/         Tab model
    ai/           Agents, sessions, tools, mini-window
    header/       Top bar + search
    statusbar/    Bottom bar
    shortcuts/    Keymap
  components/     shadcn/ui + AI Elements

Security issues

Don't file them as issues — see SECURITY.md.

License

By contributing you agree your work is licensed under Apache-2.0.