Turtle

Terminal For All of Us

A Tauri-based terminal application with integrated AI agent capabilities. Turtle provides a modern, cross-platform desktop terminal with multi-tab support and an intelligent assistant powered by language models for enhanced productivity.

Overview

Turtle is a desktop application that combines a feature-rich terminal interface with an AI agent (AgentForTerminal) to help interpret instructions, execute commands, and debug code automatically. The application is built with:

• Frontend: React + TypeScript with Chakra UI for the user interface
• Backend: Rust (Tauri) for native platform integration and terminal emulation
• AI Agent: Python-based assistant (located in TAI/) for intelligent command execution

Features

Terminal Interface

• Multi-tab support with tab creation and switching
• Full terminal emulation with ANSI escape sequence parsing
• Ctrl+C signal handling for process interruption
• Real-time output rendering with HTML formatting
• Dark theme optimized for terminal work

AI Agent Integration

• Intelligent instruction interpretation
• Automatic shell command generation and execution
• Code error detection and auto-fixing
• Language support: Python, JavaScript, Rust, TypeScript, Java, C, C++
• Git integration for snapshot commits and history tracking
• Dry-run capability for safety verification

Cross-Platform Support

• Native builds for macOS, Windows, and Linux via Tauri
• Responsive UI with Chakra UI components
• System tray integration available via Tauri plugins

Getting Started

Prerequisites

• Node.js (v16 or higher) with pnpm package manager
• Rust toolchain (for building Tauri backend)
• Python 3.8+ (for AI agent)
• Git (for version control)

Installation

1. Clone the repository:

git clone https://github.com/tars-terminal/turtle.git
cd turtle

2. Install JavaScript dependencies:

pnpm install

3. Install Python dependencies for the AI agent:

cd TAI
pip install typer prompt_toolkit rich python-dotenv openai
cd ..

Development

Start the development server with hot reload:

pnpm dev

This will start:

• Vite dev server on port 1420
• Tauri development window with both frontend and backend

Build the AI agent:

pnpm build:agent

Building for Production

Build the application for your platform:

pnpm build

Build the Tauri application:

pnpm tauri build

The compiled binaries will be available in src-tauri/target/release/.

Technology Stack

Frontend

• React 18: UI library
• TypeScript: Type-safe JavaScript
• Chakra UI: Component library
• Zustand: State management
• Vite: Build tool and dev server
• React Icons: Icon library
• Next Themes: Theme management

Backend (Rust)

• Tauri 2: Desktop application framework
• serde/serde_json: JSON serialization
• nix: Unix system calls (pty, fork, exec)
• zvariant: D-Bus variant types
• once_cell: Lazy static initialization

AI Agent (Python)

• Typer: CLI framework
• prompt_toolkit: Terminal UI
• Rich: Beautiful terminal output
• OpenAI: Language model API
• python-dotenv: Environment variable management

Key Components

Terminal Management (Rust)

The Rust backend manages terminal emulation through:

• PTY (Pseudo Terminal): Uses forkpty() to create a shell subprocess
• Polling: poll() system call for non-blocking I/O
• Event Emission: Sends shell output to frontend via Tauri events

State Management (React)

The frontend uses Zustand for global state:

• Tabs: Multi-tab terminal sessions
• Input/Output: Terminal command history and output
• UI State: Active tab tracking and navigation

ANSI Escape Parsing

Converts ANSI escape sequences (colors, formatting) into HTML for proper rendering in the browser.

Development Workflow

Running Tests

pnpm test

Type Checking

pnpm typecheck

Code Formatting

The project uses Prettier for code formatting.

Git Workflow

git checkout -b feature/your-feature-name
git commit -m "feat: description of changes"
git push origin feature/your-feature-name

Configuration

Tauri Configuration

Edit src-tauri/tauri.conf.json to modify:

• App metadata (name, version, identifier)
• Window settings (size, resizable)
• Build configuration (dev/build commands)
• Security policies (CSP)
• Bundle settings (icons, formats)

Environment Variables

Create a .env file in the root directory:

OPENAI_API_KEY=your_api_key_here

The AI agent uses this key for language model requests.

Architecture

Communication Flow

1. User Input: Terminal input via React component
2. Frontend: Zustand store updates and event handling
3. Tauri Bridge: Frontend calls Rust backend via invoke()
4. Backend: PTY receives command and executes via shell
5. Output: Backend emits shell output events to frontend
6. Rendering: Frontend parses ANSI and displays in terminal

Agent Execution

1. User types instruction in terminal
2. Frontend calls execute_agent() via Tauri
3. Rust backend writes compiled Python agent binary to temp directory
4. Binary executes in PTY with user instruction
5. Agent processes instruction, may execute commands/fix code
6. Output streamed back to terminal

Troubleshooting

PTY Not Initialized

Ensure the init() command is called when the app starts. Check console logs in Tauri dev tools.

Shell Output Not Rendering

Verify ANSI escape sequence parsing in useParseAnsi() hook. Check browser console for JavaScript errors.

Agent Binary Not Found

Build the agent with pnpm build:agent and ensure the binary is in src-tauri/bin/agent.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

This project is open source. Check the LICENSE file for details.

Support

For issues, feature requests, or discussions, please open an issue on the GitHub repository.

Roadmap

Upcoming Features

• Advanced code editing plugin with completion and syntax highlighting
• Built-in web browsing tool for documentation lookup
• Command palette for quick access
• Session management and restoration
• Custom keybindings configuration
• Plugin system for extensibility

References

• Tauri Documentation
• React Documentation
• Chakra UI Documentation
• Zustand Documentation
• AgentForTerminal README