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

To contribute to the Terax AI project, read the architecture documentation (TERAX.md and 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, 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) 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) 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 – The living architecture document defines the quality bar across correctness, performance, security, UX, and architecture.
2. Read CONTRIBUTING.md – Contains branch naming conventions, PR etiquette, and process requirements.
3. Read 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:

# 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 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) 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, add tests following this pattern:

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

// 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 to add the provider:

// 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. 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. This handles PTY session management and is considered a critical security component, requiring comprehensive tests for any modifications.

Summary

• Read first: Study TERAX.md, CONTRIBUTING.md, and 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 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.

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), Git layer, filesystem mutation, IPC command handlers, or AI tool definitions. Refer to 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 or the main README) to contact the maintainer privately, given the project's strict security model around workspace authorization and filesystem access.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}