🤖 TerminAI

An AI-powered terminal coding assistant built with Bun, TypeScript, and Ink

TerminAI is an interactive terminal-based coding assistant that brings the power of conversational coding directly to your command line. Built with modern technologies like Bun and Ink (React for CLIs), it provides a seamless chat experience with integrated bash command execution and a smart permission system.

✨ Features

• 🎯 Interactive AI Chat - Conversational AI assistance directly in your terminal
• 🔧 Bash Command Execution - Execute shell commands with AI assistance
• 🛡️ Permission System - Granular control over command execution with safety prompts
• ⚡ Blazingly Fast - Built with Bun for lightning-fast performance
• 🎨 Beautiful Terminal UI - Powered by Ink (React for terminals)
• 💾 State Management - Efficient state handling with nanostores
• 🧪 Well Tested - Comprehensive test coverage with Bun's built-in test runner
• 🎭 Error Handling - Robust error boundaries and graceful fallbacks

🚀 Quick Start

Installation

From npm (Coming Soon)

# Global installation (when published)
npm install -g terminai
# or with bun
bun add -g terminai

# Run
terminai

From Source

# Clone the repository
git clone https://github.com/marcushohlbein/terminai.git
cd terminai

# Install dependencies
bun install

# Run in development mode
bun run dev

📖 Usage

Start the AI assistant:

bun run dev

Chat Mode

Simply type your questions and press Enter to chat with the AI assistant.

Bash Mode

Switch to bash mode to execute shell commands with AI assistance. The permission system will prompt you before executing any commands.

🏗️ Project Structure

This is a monorepo containing the TerminAI CLI application:

terminai/
├── packages/
│   └── cli/          # Main CLI application
│       ├── src/
│       │   ├── components/  # Ink React components
│       │   ├── hooks/       # Custom React hooks
│       │   ├── store/       # Nanostores state management
│       │   ├── types/       # TypeScript type definitions
│       │   └── utils/       # Utility functions
│       ├── package.json
│       └── README.md        # Detailed CLI documentation
├── LICENSE
├── package.json
└── README.md

🛠️ Development

Prerequisites

• Bun 1.2 or higher
• Git

Setup

# Clone the repository
git clone https://github.com/marcushohlbein/terminai.git
cd terminai

# Install dependencies
bun install

# Run in development mode
bun run dev

Available Scripts

• bun run dev - Start the CLI in development mode
• bun run test - Run tests
• bun run test:watch - Run tests in watch mode
• bun run test:coverage - Generate test coverage report
• bun run check - Run linting and formatting checks
• bun run check-types - Type check the codebase

Testing

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Generate coverage report
bun test --coverage

🎨 Tech Stack

• Runtime: Bun - Fast all-in-one JavaScript runtime
• UI Framework: Ink - React for CLIs
• Language: TypeScript - Type-safe JavaScript
• State Management: Nanostores - Lightweight state manager
• Testing: Bun Test - Built-in test runner
• Linting: Biome & Ultracite - Fast code quality tools
• Monorepo: Turborepo - High-performance build system

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (bun test && bun run check)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Marcus Hohlbein

• GitHub: @marcushohlbein

🙏 Acknowledgments

• Built with Bun
• UI powered by Ink
• State management by Nanostores

📚 Documentation

For detailed CLI documentation, see the CLI README.

---

Made with ❤️ in Hamburg