⚡ ANAS CLI Dev — MCP AI Terminal

Version: 0.1.0 | Python: 3.14+ | License: MIT

A cutting-edge terminal-based AI assistant powered by the OpenAI Agents SDK, featuring a cyberpunk neon boot sequence, a rich Textual TUI, and an AI agent routed through OpenRouter for free-tier LLM access. Designed as an MCP (Model Context Protocol) compute node to handle up to 50% of server-side AI inference.

✨ Features

🤖 AI Agent (OpenAI Agents SDK)

OpenRouter Integration — Routes requests through OpenRouter for multi-model flexibility
Free-Tier Model — Uses arcee-ai/trinity-large-thinking:free for cost-free experimentation
Conversation Memory — Maintains a history of all exchanges with the AI
History Tutor Persona — Pre-configured agent optimized for concise, clear historical answers
Async Architecture — Non-blocking AI calls keep the UI responsive

🖥️ Terminal UI (Textual Framework)

Rich TUI Chat Interface — Full-featured terminal app with scrollable chat log
Real-Time Clock Header — Live clock display in the top bar
Stylized Borders — Cyan-bordered chat panel, green-bordered input field
Keyboard-Friendly — Footer with keybindings, rapid input submission
Loading States — Visual feedback while the AI processes responses
Error Handling — Graceful error messages displayed inline

🚀 Neon Boot Animation

ASCII Logo — Custom "ANAS CLI Dev" ASCII art with large-format rendering
Typewriter Text Effect — Animated title typing itself character by character
Neon Color Cycling — Multi-color cycling animation (cyan → blue → magenta)
Visual Boot Sound — Simulated audio-visual boot sequence
Loading Progress — 4-stage animated progress bar:
- ⚡ Powering AI Core
- 🧠 Syncing Neural Network
- 📦 Loading Modules
- 🖥️ Starting Interface
SYSTEM READY Screen — Confirmation panel before entering the chat

🔧 Developer Experience

Bleeding-Edge Stack — Python 3.14 + openai-agents v0.0.7 + Textual v8.2.6
uv-Powered — Blazing-fast Rust-based package management
Clean Separation of Concerns — Modular architecture with distinct layers (launcher, UI, AI logic, animation)
Cross-Platform — Windows and Unix support with automatic terminal detection
.env Configuration — Secure API key management via environment variables
Conversation REPL Mode — Standalone CLI loop for debugging and testing

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│ run.py │
│ (Entry Point) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────┐ │
│ │ final_animation.py │ ◄── Neon splash screen │
│ │ (Presentation) │ (rich/Panel animations) │
│ └──────────┬───────────┘ │
│ │ │
│ ┌──────────▼───────────┐ │
│ │ cli.py │ ◄── Textual TUI │
│ │ (UI / Interaction) │ (Header, Input, RichLog) │
│ └──────────┬───────────┘ │
│ │ async calls │
│ ┌──────────▼───────────┐ │
│ │ chatbot.py │ ◄── OpenAI Agents SDK │
│ │ (AI / Business Logic)│ (Agent, Runner, OpenRouter) │
│ └──────────────────────┘ │
│ │
│ ┌──────────────────────┐ │
│ │ main.py │ ◄── Scratchpad / test file │
│ │ (Development) │ (gitignored) │
│ └──────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────┤
│ Data Flow: User Input → TUI → AI Agent → OpenRouter API │
│ → Response → TUI Display │
└─────────────────────────────────────────────────────────────┘

Component Breakdown

Module	Role	Key Technologies
`run.py`	Application launcher & orchestrator	`os.system`
`final_animation.py`	Boot sequence & visual effects	`rich` (Panel, Progress, Live)
`cli.py`	Terminal UI & user interaction	`textual` (App, Header, Input, RichLog)
`chatbot.py`	AI agent logic & API integration	`agents` (Agent, Runner, OpenAIChatCompletionsModel)
`main.py`	Development scratchpad (gitignored)	`agents`, `asyncio`

🛠️ Tech Stack

Category	Technology	Version
Language	Python	>=3.14
AI Framework	OpenAI Agents SDK	0.0.7
OpenAI Client	openai	2.37.0
Terminal UI	Textual	8.2.6
Terminal Formatting	Rich	15.0.0
ASCII Banners	pyfiglet	1.0.4
Env Management	python-dotenv	1.2.2
Cross-platform Colors	colorama	0.4.6
Data Validation	pydantic	2.13.4
Async HTTP	httpx	0.28.1
Package Manager	uv	0.11.7
MCP SDK	mcp	1.27.0
HTTP Client	requests	2.34.2

📦 Installation

Prerequisites

Python 3.14+ (CPython)
uv package manager (install guide)
An OpenRouter API key (get one free)

Setup

# 1. Clone the repository
git clone https://github.com/yourusername/mcp.git
cd mcp
# 2. Create virtual environment & install dependencies
uv venv
uv sync
# 3. Configure your API keysecho"OPENROUTER_API_KEY=sk-or-v1-your-key-here"> .env

Note: The .env file is automatically excluded from version control via .gitignore.

API Key Configuration

The application supports two methods of API key management:

Environment variable (recommended): Set OPENAI_API_KEY in your .env file
Direct assignment: The chatbot module has a placeholder that can be replaced with your key

Keys are loaded via python-dotenv and passed to the OpenRouter client for routing to the free-tier model.

🚀 Usage

Launch the Full Application

uv run python run.py

This will:

Clear the terminal screen
Play the neon boot animation sequence
Launch the Textual TUI chat interface

Standalone Chatbot (REPL Mode)

# Edit chatbot.py to uncomment the bottom line:# import asyncio# asyncio.run(main())
uv run python chatbot.py

Quick Agent Test

uv run python main.py

🎮 How It Works

Starting the Application

When you run python run.py, the application enters a carefully orchestrated startup sequence:

Screen Initialization — Terminal clears automatically (supports both Windows cls and Unix clear)
Boot Sequence — The neon animation plays:
- ASCII logo renders in bright cyan
- Visual "boot sound" pulses 5 times
- Title cycles through neon colors (6 cycles)
- Typewriter effect types the title
System Loading — 4-stage progress bar simulates module initialization
Chat Interface — Textual TUI appears, ready for input

Chatting with the AI

Type your message in the input field (green border)
Press Enter to send
Your message appears in the chat panel (cyan border)
The AI responds with a concise history-focused answer
Error messages are displayed inline if the API call fails

AI Agent Configuration

The "History Tutor" agent in chatbot.py is configured with:

Model:arcee-ai/trinity-large-thinking:free (OpenRouter free tier)
Instructions: Clear, concise historical answers
Conversation Context: Full history stored and available for context
Async Runner: Non-blocking execution via Runner.run()

📁 Project Structure

MCP/
├── run.py # Application entry point
├── chatbot.py # AI agent logic (OpenAI Agents SDK)
├── cli.py # Textual TUI chat interface
├── final_animation.py # Neon boot animation sequence
├── main.py # Development scratchpad (gitignored)
├── pyproject.toml # Project definition & dependencies
├── uv.lock # Lock file for reproducible builds
├── .env # API keys (gitignored)
├── .gitignore # Git exclusion rules
├── .python-version # Python version: 3.14
├── README.md # This file
├── .venv/ # Virtual environment (gitignored)
├── __pycache__/ # Python bytecode cache (gitignored)
└── .git/ # Git repository

⚙️ Configuration

Environment Variables (`.env`)

Variable	Required	Description
`OPENAI_API_KEY`	Yes	API key for OpenAI/OpenRouter
`OPENROUTER_API_KEY`	Yes	OpenRouter-specific API key

Agent Configuration (`chatbot.py`)

Setting	Current Value	Description
Model	`arcee-ai/trinity-large-thinking:free`	OpenRouter model ID
Base URL	`https://openrouter.ai/api/v1`	OpenRouter API endpoint
Agent Name	"History Tutor"	Agent identity
Instructions	Short history answers	System prompt
Tracing	Disabled	Telemetry setting

TUI Configuration (`cli.py`)

Setting	Current Value	Description
Screen Background	Black	Terminal background color
Chat Border	Cyan (`round`)	Chat panel border style
Input Border	Green (`round`)	Input field border style
Header Clock	Enabled	Live clock display

🧪 Development

Code Conventions

Async-first: All I/O operations use asyncio/await
Minimal dependencies: Only 6 core runtime deps in pyproject.toml
Clean separation: UI logic never mixes with AI/business logic
Error resilience: Try/except guards around all external calls

Testing

Tests are not yet implemented. The main.py file serves as a manual test harness for agent calls. Future test coverage will use pytest with asyncio support.

Building

# Install in development mode
uv pip install -e .

Common Tasks

# Run the application
uv run python run.py
# Update dependencies
uv sync
# Add a new dependency
uv add package-name

🗺️ Roadmap

🌟 Why This Project Stands Out

Bleeding-Edge Technology — Built on Python 3.14 (the latest CPython release) and the brand-new openai-agents SDK v0.0.7, placing it at the forefront of Python AI development.
MCP-Ready Architecture — Named and designed around the Model Context Protocol, with the mcp Python SDK already installed and a clear vision for distributed AI compute.
Cost-Free AI — Leverages OpenRouter's free-tier models for zero-cost experimentation, making AI accessible without a paid subscription.
Terminal-Native Experience — Chooses a rich TUI over a web interface, demonstrating that terminal applications can deliver modern, visually appealing experiences.
Cyberpunk Aesthetic — The neon boot animation, color-cycling logos, and ASCII art create a distinctive, memorable brand identity.
Clean Modular Design — Four focused modules with clear responsibilities make the codebase approachable and easy to extend.
Async Excellence — Non-blocking architecture ensures the UI never freezes during API calls — a common pain point in terminal applications.
Developer-Friendly — Minimal dependencies, uv for lightning-fast package management, and a straightforward setup process.

🤝 Contributing

Contributions are welcome! This is an early-stage project with lots of room for growth. Feel free to:

Open issues for bugs or feature suggestions
Submit PRs for improvements
Experiment with different AI models and configurations

📄 License

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

_{Built with ❤️ using Python 3.14 · OpenAI Agents SDK · Textual · Rich}
_{ANAS CLI Dev — MCP AI Terminal}

Navigation Menu

Repository files navigation

⚡ ANAS CLI Dev — MCP AI Terminal

✨ Features

🤖 AI Agent (OpenAI Agents SDK)

🖥️ Terminal UI (Textual Framework)

🚀 Neon Boot Animation

🔧 Developer Experience

🏗️ Architecture

Component Breakdown

🛠️ Tech Stack

📦 Installation

Prerequisites

Setup

API Key Configuration

🚀 Usage

Launch the Full Application

Standalone Chatbot (REPL Mode)

Quick Agent Test

🎮 How It Works

Starting the Application

Chatting with the AI

AI Agent Configuration

📁 Project Structure

⚙️ Configuration

Environment Variables (`.env`)

Agent Configuration (`chatbot.py`)

TUI Configuration (`cli.py`)

🧪 Development

Code Conventions

Testing

Building

Common Tasks

🗺️ Roadmap

🌟 Why This Project Stands Out

🤝 Contributing

📄 License

About

Contributors

Languages

Name		Name	Last commit message	Last commit date
.vscode		.vscode
python		python
testing		testing
.gitignore		.gitignore
.python-version		.python-version
README.md		README.md
chatbot.py		chatbot.py
cli.py		cli.py
final_animation.py		final_animation.py
pyproject.toml		pyproject.toml
run.py		run.py
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

⚡ ANAS CLI Dev — MCP AI Terminal

✨ Features

🤖 AI Agent (OpenAI Agents SDK)

🖥️ Terminal UI (Textual Framework)

🚀 Neon Boot Animation

🔧 Developer Experience

🏗️ Architecture

Component Breakdown

🛠️ Tech Stack

📦 Installation

Prerequisites

Setup

API Key Configuration

🚀 Usage

Launch the Full Application

Standalone Chatbot (REPL Mode)

Quick Agent Test

🎮 How It Works

Starting the Application

Chatting with the AI

AI Agent Configuration

📁 Project Structure

⚙️ Configuration

Environment Variables (.env)

Agent Configuration (chatbot.py)

TUI Configuration (cli.py)

🧪 Development

Code Conventions

Testing

Building

Common Tasks

🗺️ Roadmap

🌟 Why This Project Stands Out

🤝 Contributing

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Contributors

Languages

Environment Variables (`.env`)

Agent Configuration (`chatbot.py`)

TUI Configuration (`cli.py`)