TypeScript CLI AI Conversation App - Technical Plan

Project Overview

A TypeScript CLI application that initiates and maintains an autonomous conversation between two AI personas using Ollama. The app starts with user input and then continues the conversation automatically until stopped.

Architecture Overview

Core Components

1. CLI Interface - Handle user input and display conversation
2. Conversation Manager - Orchestrate the conversation flow
3. AI Client - Interface with Ollama API
4. Persona Manager - Manage distinct AI personas
5. State Manager - Track conversation history and context

Technology Stack

• Runtime: Node.js 22
• Language: TypeScript 5.x
• Package Manager: npm/pnpm
• CLI Framework: Commander.js or Inquirer.js
• AI Integration: Ollama JavaScript client
• Testing: Vitest
• Linting: ESLint with TypeScript plugin
• Formatting: Prettier
• Build Tool: tsx/tsup for development and production builds

Project Structure

ai-conversation-cli/
├── src/
│   ├── index.ts              # Entry point
│   ├── cli/
│   │   ├── commands.ts       # CLI command definitions
│   │   └── prompts.ts        # User input handling
│   ├── conversation/
│   │   ├── manager.ts        # Conversation orchestration
│   │   ├── personas.ts       # AI persona definitions
│   │   └── history.ts        # Conversation history management
│   ├── ai/
│   │   ├── client.ts         # Ollama client wrapper
│   │   └── models.ts         # AI model configurations
│   ├── utils/
│   │   ├── logger.ts         # Logging utilities
│   │   └── formatter.ts      # Output formatting
│   └── types/
│       └── index.ts          # TypeScript type definitions
├── tests/
│   ├── unit/
│   └── integration/
├── .eslintrc.json
├── .prettierrc
├── tsconfig.json
├── vitest.config.ts
├── package.json
└── README.md

Implementation Plan

Phase 1: Project Setup

1. Initialize Project

   • Create package.json with Node 22 engine requirement
   • Install TypeScript and development dependencies
   • Configure TypeScript (tsconfig.json)
   • Set up ESLint with TypeScript rules
   • Configure Prettier
   • Set up Vitest for testing

2. Development Environment

   • Configure hot reloading with tsx
   • Set up debug configurations
   • Create npm scripts for common tasks

Phase 2: Core Infrastructure

1. CLI Foundation

   • Implement basic CLI structure using Commander.js
   • Create initial prompt for user input using Inquirer.js
   • Add graceful shutdown handling (Ctrl+C)
   • Implement colored output using chalk

2. Ollama Integration

   • Install and configure Ollama client
   • Create abstraction layer for AI interactions
   • Implement error handling for API failures
   • Add configuration for different models

Phase 3: Conversation Logic

1. Persona System

   • Define persona interface with characteristics
   • Create at least two distinct personas
   • Implement persona switching logic
   • Add personality traits to responses

2. Conversation Manager

   • Implement turn-based conversation flow
   • Add context window management
   • Create conversation history tracking
   • Implement stopping conditions

3. State Management

   • Track conversation state
   • Implement conversation export functionality
   • Add conversation replay capability

Phase 4: Features & Polish

1. Enhanced Features

   • Add conversation speed control
   • Implement conversation themes/topics
   • Add conversation statistics
   • Create conversation summaries
   • Compact context into summaries when context window limit is approached

2. User Experience

   • Add loading indicators
   • Implement real-time typing effect
   • Add conversation timestamps
   • Create clear visual separation between speakers

Phase 5: Testing & Documentation

1. Testing Strategy

   • Unit tests for core logic
   • Integration tests for Ollama interaction
   • Mock Ollama responses for testing
   • Test CLI commands and user flows

2. Documentation

   • API documentation
   • User guide
   • Configuration options
   • Example conversations

Configuration Schema

interface Config {
  ollama: {
    baseUrl: string;
    model: string;
    temperature: number;
    maxTokens: number;
  };
  conversation: {
    maxTurns?: number;
    turnDelay: number;
    contextWindow: number;
  };
  personas: {
    primary: PersonaConfig;
    secondary: PersonaConfig;
  };
}

interface PersonaConfig {
  name: string;
  personality: string;
  speakingStyle: string;
  interests: string[];
}

Key Dependencies

{
  "dependencies": {
    "commander": "^12.0.0",
    "inquirer": "^9.2.0",
    "ollama": "^0.5.0",
    "chalk": "^5.3.0",
    "ora": "^8.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.3.0",
    "@typescript-eslint/eslint-plugin": "^7.0.0",
    "@typescript-eslint/parser": "^7.0.0",
    "eslint": "^8.56.0",
    "prettier": "^3.2.0",
    "vitest": "^1.2.0",
    "tsx": "^4.7.0",
    "tsup": "^8.0.0"
  }
}

Development Workflow

1. Local Development

   npm run dev          # Start with hot reload
   npm run lint         # Run ESLint
   npm run format       # Run Prettier
   npm run test         # Run tests
   npm run test:watch   # Run tests in watch mode
   

2. Build & Distribution

   npm run build        # Build for production
   npm run start        # Run production build
   

Error Handling Strategy

1. Ollama Connection Errors

   • Retry logic with exponential backoff
   • Graceful degradation
   • Clear error messages

2. User Input Validation

   • Validate conversation starters
   • Handle empty inputs
   • Provide helpful error messages

3. Runtime Errors

   • Global error handler
   • Logging to file option
   • Debug mode for development

Performance Considerations

1. Memory Management

   • Limit conversation history size
   • Implement circular buffer for long conversations
   • Clear old context periodically

2. API Optimization

   • Implement request queuing
   • Add response caching where appropriate
   • Monitor API rate limits

Security Considerations

1. Input Sanitization

   • Sanitize user inputs
   • Prevent prompt injection
   • Validate API responses

2. Configuration Security

   • Support environment variables
   • Secure API key storage
   • No sensitive data in logs

Future Enhancements

1. Multiple AI Providers

   • Support for OpenAI, Anthropic, etc.
   • Provider abstraction layer

2. Advanced Features

   • Multi-party conversations
   • Voice input/output
   • Web interface option
   • Conversation branching

3. Analytics

   • Conversation metrics
   • Response quality tracking
   • User behavior analytics

Success Criteria

1. Functionality

   • Smooth conversation flow
   • Distinct personas
   • Reliable Ollama integration
   • Graceful error handling

2. Code Quality

   • 80%+ test coverage
   • No ESLint errors
   • Consistent formatting
   • Well-documented code

3. User Experience

   • < 2s response time
   • Clear, intuitive interface
   • Helpful error messages
   • Smooth conversation display

Notes

• Ensure Ollama is installed and running locally
• Consider Docker setup for easier distribution
• Plan for different conversation styles and topics
• Think about conversation export formats (JSON, Markdown, etc.)