# TactiTerm

**Tactile Terminal:** A WebUI / TUI built to help teach and study programming concepts in an interactive, hands-on way.

> I found it frustrating that there wasn't a simple, easy to use program for studying program in an interactive or kinesthetic way. So, while I worked on other projects, I decided to slop together a program and leverage local LLMs to build **TactiTerm**.
>
> A self-sufficient, offline capable IDE, with an LLM powered tutor to help guide you through mental roadblocks, and build up confidence when it comes to programming in various languages.

---

## Overview

**TactiTerm** is an interactive software engineering tutor designed with a "guidance over answers" philosophy. Rather than providing copy-paste solutions, TactiTerm utilizes an **LLM Harness** to ask probing questions, provide hints, and guide users toward mastering concepts across various languages.

TactiTerm features both a rich **Terminal User Interface (TUI)** for command-line use, and a modern **Web UI** featuring the Monaco Editor.

---

## Features

- **AI Mentor:** Provides step-by-step guidance, code review, and conceptual hints without spoiling direct answers.
- **Dual Interfaces:**
  - **TUI:** Built with Python and Textual for lightweight, keyboard-driven terminal workflows.
  - **Web UI:** Built with React, Vite, TypeScript, Tailwind CSS, and Monaco Editor.
- **10 Supported Languages:** Python, C#, C++, Java, JavaScript, TypeScript, Rust, Lua, HTML, and Go.
- **Real-time Linting & Execution:** Tree-sitter powered syntax validation and safe local code execution.
- **Interactive Syntax Handbook:** Comprehensive reference catalog with on-demand AI code examples for functions and core language topics.
- **AI Challenge Generator (GenTUI):** Create and save custom Markdown programming challenges tailored to specific subjects and difficulties.
- **Configurable & Network Ready:** Easily configure LLM endpoints, ports, and enable `"public": true` to host the Web UI across your local network (`0.0.0.0`).

---

## Quick Start

### Prerequisites

- [Devbox](https://www.jetify.com/devbox) 

> Currently we only officially support running TactiTerm through devbox. This is to simplify the deployment process across devices. If you dare, and you have the prequisites installed; you should be able to run TactiTerm without it.

### Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/your-username/TactiTerm.git
   cd TactiTerm
   ```

2. Install dependencies:
   ```bash
   devbox run install
   ```
   *(or `make install` inside `devbox shell`)*

---

## Usage

TactiTerm is executed via the use of **Devbox** run commands.

### Terminal Interface (TUI)

Launch the interactive terminal application:
```bash
devbox run tui
```
*(or `make tui` inside `devbox shell`)*

Additional TUI modes:
- `devbox run gentui` - Launch the standalone GenTUI AI Challenge Generator.
- `devbox run -- make tui-debug` - Launch TUI in debug logging mode.

### Web Interface (Web UI)

Launch the FastAPI backend server and Vite frontend dev server:
```bash
devbox run web
```
*(or `make web` inside `devbox shell`)*

Then open your browser to `http://localhost:5173`.

---

## Configuration

When initialized, TactiTerm automatically generates a `config.json` file in the root directory if one does not exist.

### `config.json` Example

```json
{
  "llm": {
    "base_url": "http://localhost:8080/v1",
    "model": "local-model",
    "api_key": "not-needed",
    "temperature": 0.7,
    "max_tokens": 512,
    "timeout_seconds": 60.0
  },
  "web": {
    "host": "127.0.0.1",
    "port": 8000,
    "public": false
  }
}
```

### Key Settings

- **LLM Settings:** Point `base_url` to any OpenAI-compatible server (LocalAI, vLLM, Ollama, LM Studio, or OpenAI API).
- **Web UI Public Access:** Set `"public": true` under `"web"` (or set environment variable `TACTTERM_WEB_PUBLIC=true`) to bind the server to `0.0.0.0`, allowing other devices on your local network to connect.

### Environment Variable Overrides

- `TACTTERM_LLM_BASE_URL` - Override LLM API URL.
- `TACTTERM_LLM_MODEL` - Override LLM model name.
- `TACTTERM_WEB_HOST` - Override web server bind address.
- `TACTTERM_WEB_PORT` - Override web server port (default: 8000).
- `TACTTERM_WEB_PUBLIC` - Set to `true` to enable network binding (`0.0.0.0`).

---

## Architecture

- **Backend (`src/api/main.py`):** FastAPI application serving REST endpoints for challenges, code linting, code execution, mentoring guidance, and handbook references.
- **Core Engine (`src/core/`):**
  - `config.py`: Application config manager with auto-generation and env overrides.
  - `executor.py`: Subprocess execution engine for multi-language code snippets.
  - `linter.py`: Tree-sitter syntax checker.
  - `mentor.py`: Async Socratic mentor prompt & LLM service.
  - `handbook.py`: Reference catalog and example generator.
  - `generator.py`: AI challenge generation service.
- **TUI Client (`src/tui/`):** Textual terminal application.
- **Web Client (`frontend/`):** React + TypeScript SPA powered by Vite, Tailwind CSS, and Monaco Editor.

---