TactiTerm/README.md

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

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:

   git clone https://github.com/your-username/TactiTerm.git
   cd TactiTerm
   

2. Install dependencies:

   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:

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:

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

{
  "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.

---