Skip to content
BranchesTags

Repository files navigation

⚡ 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

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 keys
echo "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:

  1. Environment variable (recommended): Set OPENAI_API_KEY in your .env file
  2. 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:

  1. Clear the terminal screen
  2. Play the neon boot animation sequence
  3. 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:

  1. Screen Initialization — Terminal clears automatically (supports both Windows cls and Unix clear)
  2. 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
  3. System Loading — 4-stage progress bar simulates module initialization
  4. 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

  • Conversation Context Passing — Feed full history into agent calls for true memory
  • MCP Server Integration — Implement MCP server for distributed compute (50% offload)
  • Multiple AI Personas — Switchable agent configurations (coding, science, general)
  • Session Persistence — Save and load conversation history
  • Markdown Rendering — Rich formatting of AI responses in the TUI
  • Command Palette — Slash commands for extended functionality
  • Streaming Responses — Real-time token-by-token AI output
  • Test Suite — Unit tests for chatbot logic, integration tests for TUI
  • Docker Support — Containerized deployment
  • Configurable Models — Runtime model switching via UI
  • [project.scripts] entry point in pyproject.toml

🌟 Why This Project Stands Out

  1. 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.

  2. 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.

  3. Cost-Free AI — Leverages OpenRouter's free-tier models for zero-cost experimentation, making AI accessible without a paid subscription.

  4. Terminal-Native Experience — Chooses a rich TUI over a web interface, demonstrating that terminal applications can deliver modern, visually appealing experiences.

  5. Cyberpunk Aesthetic — The neon boot animation, color-cycling logos, and ASCII art create a distinctive, memorable brand identity.

  6. Clean Modular Design — Four focused modules with clear responsibilities make the codebase approachable and easy to extend.

  7. Async Excellence — Non-blocking architecture ensures the UI never freezes during API calls — a common pain point in terminal applications.

  8. 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

About

Terminal Base Ui General Agent that have Tools , Memory and Guardrails to inspect and improve with context.

Topics

agentagentic-aiaiemployeedockerfastapimcpmemorypythonterminal

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages