ai-terminal-assistant/README.md

# AI Terminal Assistant

<div align="center">
  <h3>🤖 A powerful terminal-based AI coding assistant powered by Claude API</h3>
  <p>
    <a href="#features">Features</a> •
    <a href="#quick-start">Quick Start</a> •
    <a href="#documentation">Documentation</a> •
    <a href="#packages">Packages</a>
  </p>
  <p>
    <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg">
    <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D18.0.0-green">
    <img alt="pnpm" src="https://img.shields.io/badge/pnpm-%3E%3D8.0.0-orange">
  </p>
</div>

## 🌟 Overview

AI Terminal Assistant is a comprehensive AI-powered development toolkit that helps developers write code, debug issues, and manage projects more efficiently. Built as a modular monorepo, it provides multiple interfaces (CLI, Web, Desktop) to interact with Claude AI for various programming tasks.

## ✨ Features

### Core Capabilities
- 🧠 **Advanced AI Agent** - Powered by Claude API with streaming responses
- 🔧 **Rich Tool System** - File operations, bash commands, code search, and more
- 📝 **Smart Code Editing** - Multiple edit modes (whole, diff, search-replace)
- 🔍 **Language Server Protocol** - IDE-like code intelligence
- 💾 **Checkpoint System** - Shadow Git for safe experimentation
- 🔌 **Model Context Protocol** - Extensible tool integration
- 🎣 **Hook System** - Pre/post execution customization

### User Interfaces
- 🖥️ **CLI** - Terminal-native experience with serve/attach modes
- 🌐 **Web UI** - Modern React interface with real-time updates
- 🖱️ **Desktop App** - Tauri-based native application (Coming soon)

### Developer Experience
- 📦 **Monorepo Architecture** - Clean separation of concerns
- 🚀 **Built with Bun** - Fast runtime and bundling
- 🔥 **Hot Reload** - Development with instant feedback
- 🧪 **Comprehensive Testing** - Unit and integration tests
- 📊 **Type Safety** - Full TypeScript support

## 🚀 Quick Start

### Prerequisites
- Node.js 18+ or Bun 1.0+
- pnpm 8.0+
- Anthropic API Key

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd ai-terminal-assistant

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# Build all packages
pnpm build
```

### Running the Application

#### Option 1: Web Interface
```bash
# Start the server
pnpm server:dev

# In another terminal, start the web UI
pnpm web:dev

# Open http://localhost:5173 in your browser
```

#### Option 2: CLI Mode
```bash
# Start the server
cd packages/cli && bun run src/index.ts serve --port 3000

# In another terminal, attach to the server
cd packages/cli && bun run src/index.ts attach http://localhost:3000
```

## 📦 Packages

This monorepo contains four main packages:

| Package | Description | Status |
|---------|-------------|--------|
| [@ai-assistant/core](./packages/core) | Core agent engine, tools, and integrations | ✅ Stable |
| [@ai-assistant/server](./packages/server) | HTTP/WebSocket server with REST API | ✅ Stable |
| [@ai-assistant/cli](./packages/cli) | Command-line interface | ✅ Stable |
| [@ai-assistant/web](./packages/web) | React-based web interface | ✅ Stable |

## 🏗️ Architecture

```mermaid
graph TD
    Web[Web UI] --> Server
    CLI[CLI] --> Server
    Desktop[Desktop App] --> Server
    Server --> Core[Core Engine]
    Core --> Tools[Tool System]
    Core --> LSP[Language Server]
    Core --> MCP[Model Context Protocol]
    Core --> Checkpoint[Checkpoint System]
```

### Technology Stack

- **Runtime**: Bun / Node.js
- **Language**: TypeScript
- **Server**: Hono + Bun WebSocket
- **Frontend**: React + Vite + Tailwind CSS
- **Desktop**: Tauri (Rust + WebView)
- **Testing**: Vitest
- **Package Manager**: pnpm (monorepo)

## 📖 Documentation

Detailed documentation is available in the [docs](./docs) directory:

- [Architecture Overview](./docs/design/architecture/gui-server-client.md)
- [API Reference](./docs/api/README.md)
- [Development Guide](./docs/development/README.md)
- [Configuration Guide](./docs/configuration/README.md)

## 🛠️ Development

### Common Commands

```bash
# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test
pnpm test:coverage

# Linting
pnpm lint

# Type checking
pnpm typecheck

# Clean build artifacts
pnpm clean
```

### Package-specific Development

```bash
# Work on a specific package
pnpm --filter @ai-assistant/core dev
pnpm --filter @ai-assistant/server test
pnpm --filter @ai-assistant/web build
```

## 🔧 Configuration

### Environment Variables

Create a `.env` file in the root directory:

```env
# Required
ANTHROPIC_API_KEY=sk-ant-xxxxx

# Optional
AI_MODEL=claude-sonnet-4-20250514
AI_MAX_TOKENS=4096
SERVER_PORT=3000
SERVER_HOST=localhost
```

### Supported Models

- `claude-sonnet-4-20250514` (default)
- `claude-haiku-3-20251120`
- Other Claude models

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Claude API](https://docs.anthropic.com/claude/reference/getting-started-with-the-api) by Anthropic
- Powered by [Bun](https://bun.sh) for fast JavaScript runtime
- UI components from [Tailwind CSS](https://tailwindcss.com)
- Desktop app built with [Tauri](https://tauri.app)

## 📞 Support

- 📧 Email: support@example.com
- 💬 Discord: [Join our community](https://discord.gg/example)
- 🐛 Issues: [GitHub Issues](https://github.com/username/repo/issues)

---

<div align="center">
  Made with ❤️ by the AI Terminal Assistant Team
</div>