# How to Contribute to the Terax AI Project: A Complete Developer's Guide

> Learn how to contribute to the Terax AI project. Follow our guide for discussing changes, implementing features, running checks, and submitting PRs to the crynta/terax-ai repository.

- Repository: [Crynta/terax-ai](https://github.com/crynta/terax-ai)
- Tags: how-to-guide
- Published: 2026-07-06

---

**To contribute to the Terax AI project, read the architecture documentation ([`TERAX.md`](https://github.com/crynta/terax-ai/blob/main/TERAX.md) and [`CONTRIBUTING.md`](https://github.com/crynta/terax-ai/blob/main/CONTRIBUTING.md)), discuss non-trivial changes via Discord or GitHub issues, implement your feature on a dedicated branch, run the full quality check suite (linting, type checking, and testing), and submit a PR following Conventional Commits.**

Terax AI is an open-source, AI-native terminal emulator built with a **Rust Tauri 2** backend and **React 19 + TypeScript** frontend. If you want to contribute to the Terax AI project, you must understand its strict two-process security model where the backend owns all OS access and the webview communicates exclusively through `invoke()` calls. This guide covers the repository structure, quality standards, and hands-on examples for submitting successful pull requests.

## Understanding the Terax AI Architecture

### The Two-Process Security Model

Terax AI enforces a strict **two-process model** that separates privileged operations from the UI. According to the source code in [`src-tauri/src/lib.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/lib.rs), all Tauri commands are registered here, forming the IPC bridge between the frontend and backend.

| Layer | Location | Responsibilities |
|------|----------|------------------|
| **Backend (Rust)** | `src-tauri/` | PTY handling (`pty::*`), filesystem API (`fs::*`), Git commands (`git::*`), workspace authorization (`workspace::*`), AI HTTP proxy with SSRF guard (`net::*`), and OS keychain secrets (`secrets::*`) |
| **Frontend (React/TS)** | `src/` | UI components (shadcn/ui), state management (hooks in `modules/*/lib`), AI subsystem (`modules/ai/*`), and theme engine (`modules/theme/*`) |

The backend maintains a **security deny-list** for file system operations (see [`src/modules/ai/lib/security.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/security.ts)) and never trusts the webview to bypass security controls.

### Module Layout

The frontend organizes code into feature-based modules under `src/modules/`:

```

src/
├─ modules/
│   ├─ terminal/       # xterm.js integration, OSC handling

│   ├─ editor/         # CodeMirror 6 stack

│   ├─ explorer/       # File tree UI

│   ├─ ai/             # Vercel AI SDK, provider config, tools

│   ├─ git-history/    # Commit graph UI

│   ├─ source-control/ # Git status / diff UI

│   └─ workspace/      # Workspace switching, WSL bridge

└─ components/ui/      # shadcn/ui primitives

```

Each module exports a **thin barrel** ([`index.ts`](https://github.com/crynta/terax-ai/blob/main/index.ts)) and keeps hooks under `lib/`. New features must be added inside the appropriate module folder, never at the top level, and must use the `@/` import alias.

## Contribution Prerequisites

Before writing code, you must align with the project's direction and quality expectations. The maintainer is a single person, so **roadmap alignment** is essential.

1. **Read [`TERAX.md`](https://github.com/crynta/terax-ai/blob/main/TERAX.md)** – The living architecture document defines the quality bar across correctness, performance, security, UX, and architecture.
2. **Read [`CONTRIBUTING.md`](https://github.com/crynta/terax-ai/blob/main/CONTRIBUTING.md)** – Contains branch naming conventions, PR etiquette, and process requirements.
3. **Read [`docs/contributing/testing.md`](https://github.com/crynta/terax-ai/blob/main/docs/contributing/testing.md)** – Specifies which changes require unit tests (any modification to *load-bearing* subsystems).
4. **Discuss large work** in the Discord channel or via a GitHub issue before opening a PR.

## The Contribution Workflow

Follow this exact sequence when you contribute to the Terax AI project:

1. **Create a feature branch** using the naming convention `feat/…` for features or `fix/…` for bug fixes.
2. **Keep the diff focused** – avoid unrelated changes in a single PR.
3. **Implement** your changes within the appropriate `src/modules/*` directory.
4. **Add tests** if touching core subsystems: terminal spawn, workspace auth, Git layer, filesystem mutation, IPC, or AI tools.
5. **Run the full test suite** locally before pushing:

```bash

# Frontend checks

pnpm lint
pnpm check-types
pnpm test

# Backend checks

cd src-tauri
cargo clippy --all-targets --locked -- -D warnings
cargo nextest run --locked

```

6. **Submit a PR** with a title following [Conventional Commits](https://www.conventionalcommits.org/) and fill out the complete PR template.

## Code Quality and Testing Standards

### Automated Quality Gates

Every PR is judged against five criteria: **correctness**, **performance**, **security**, **UX**, and **architecture**. The CI pipeline (defined in [`.github/workflows/ci.yml`](https://github.com/crynta/terax-ai/blob/main/.github/workflows/ci.yml)) enforces these commands:

- **`pnpm lint`** – ESLint + Prettier for code formatting
- **`pnpm check-types`** – TypeScript strict mode validation
- **`pnpm test`** – Jest + React Testing Library for frontend logic
- **`cargo clippy --all-targets --locked -- -D warnings`** – Rust linting
- **`cargo nextest run --locked`** – Rust test runner used in CI

### Testing Requirements for Core Subsystems

If your change modifies any *load-bearing* subsystem, you must add a unit test to lock the invariant. Core subsystems include terminal spawning, workspace authorization, Git operations, filesystem mutations, IPC handlers, and AI tools.

For example, when modifying workspace authorization logic in [`src-tauri/src/modules/workspace.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/workspace.rs), add tests following this pattern:

```rust
// src-tauri/src/modules/workspace/tests/auth_tests.rs
#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::tempdir;
    use std::fs;

    #[test]
    fn authorize_subdir_of_allowed_root() {
        // Arrange – a temporary dir inside an allowed workspace root
        let root = tempdir().unwrap();
        let sub = root.path().join("sub");
        fs::create_dir_all(&sub).unwrap();

        // Act – ask the backend to authorize the subdirectory
        let result = authorize_path(&sub);

        // Assert – should be allowed
        assert!(result.is_ok());
    }
}

```

## Practical Contribution Examples

### Adding a UI Feature

When adding components to the React frontend, use shadcn/ui primitives and keep components stateless. State belongs in hooks under the module's `lib/` directory.

```tsx
// src/app/header/HeaderButtons.tsx
import { Button } from '@/components/ui/button';
import { useAppContext } from '@/modules/header/lib/context';

export const HeaderButtons = () => {
  const { toggleSidebar } = useAppContext();

  return (
    <Button variant="ghost" onClick={toggleSidebar}>
      Toggle Sidebar
    </Button>
  );
};

```

**Key requirements:**
- Use the `@/` import alias for all imports
- Place hooks in `src/modules/[feature]/lib/`
- Use components from `src/components/ui/` for consistency

### Extending AI Providers

Terax AI uses a **BYOK** (Bring Your Own Key) AI stack via the Vercel AI SDK v6. Adding a new provider does not require backend changes because the `openai-compatible` adapter handles any OpenAI API-compatible endpoint.

Update [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts) to add the provider:

```typescript
// src/modules/ai/config.ts
export const PROVIDERS = [
  // existing entries …
  {
    id: 'groq',
    name: 'Groq',
    endpoint: 'https://api.groq.com/openai/v1',
    requiresKey: true,
  },
];

```

AI tools like `read_file`, `write_file`, and `run_command` are defined in [`src/modules/ai/lib/tools.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/tools.ts). Note that write-type tools must flag `needsApproval: true` to trigger the UI approval card.

### Working with the PTY Subsystem

For terminal-related contributions, the core logic resides in [`src-tauri/src/modules/pty/session.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/pty/session.rs). This handles PTY session management and is considered a critical security component, requiring comprehensive tests for any modifications.

## Summary

- **Read first**: Study [`TERAX.md`](https://github.com/crynta/terax-ai/blob/main/TERAX.md), [`CONTRIBUTING.md`](https://github.com/crynta/terax-ai/blob/main/CONTRIBUTING.md), and [`docs/contributing/testing.md`](https://github.com/crynta/terax-ai/blob/main/docs/contributing/testing.md) before coding.
- **Architecture matters**: Respect the two-process model; all privileged operations belong in the Rust backend at `src-tauri/`.
- **Quality is mandatory**: Run `pnpm lint`, `pnpm check-types`, `pnpm test`, and the full Rust cargo suite before submitting.
- **Test core changes**: Add unit tests when modifying workspace auth, filesystem, Git, terminal, IPC, or AI tool subsystems.
- **Follow conventions**: Use Conventional Commits, the `@/` import alias, and feature branches named `feat/` or `fix/`.

## Frequently Asked Questions

### Do I need to know Rust to contribute to the Terax AI project?

No, you can contribute to the React/TypeScript frontend without Rust knowledge for UI features, theme updates, or AI provider configurations. However, any changes to filesystem operations, terminal handling, or workspace security require modifications to the Rust backend in `src-tauri/`.

### How do I add support for a new AI model or provider?

Add the provider configuration to the `PROVIDERS` array in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts) using the existing `openai-compatible` adapter structure. You do not need to modify the Rust backend unless the provider requires a custom authentication flow that bypasses the standard HTTP proxy in [`src-tauri/src/modules/net.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/net.rs).

### What types of changes require me to write unit tests?

You must add tests if your PR touches any *load-bearing* subsystem: terminal spawn logic, workspace authorization ([`src-tauri/src/modules/workspace.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/workspace.rs)), Git layer, filesystem mutation, IPC command handlers, or AI tool definitions. Refer to [`docs/contributing/testing.md`](https://github.com/crynta/terax-ai/blob/main/docs/contributing/testing.md) for the complete list and testing patterns.

### How should I report a security vulnerability?

Do not open a public GitHub issue for security vulnerabilities. Instead, follow the security policy in the repository (typically found in [`SECURITY.md`](https://github.com/crynta/terax-ai/blob/main/SECURITY.md) or the main README) to contact the maintainer privately, given the project's strict security model around workspace authorization and filesystem access.