AI CLI OSS — OpenAI GPT-OSS Hackathon Edition

A powerful command-line chatbot powered by OSS models via Groq API. Built for the OpenAI GPT-OSS Hackathon to showcase practical, agentic workflows in the terminal.

Hackathon Focus

• Best Overall: The absolutely most interesting application of gpt-oss — a fast, ergonomic CLI that blends conversational intelligence with practical developer workflows (analysis, guidance, and safe file operations) directly in your terminal.
• Best Local Agent: A highly useful, agentic CLI that operates purely on your local files and context with no external browsing or scraping. It never fetches from the web; it only reads your local project and talks to the model API.

Why this project for GPT-OSS:

• Uses OSS models via Groq that excel at concise analysis and code reasoning.
• Demonstrates structured prompts that adapt to codebases, enabling meaningful, context-aware assistance.
• Enables safe, explicit file edits via a clear, auditable format.

Features

• 🤖 Interactive chat sessions with OSS models (openai/gpt-oss-20b)
• 🧠 Smart Context Detection - Automatically determines when to use project context vs. general knowledge
• 📁 File context awareness - Analyzes your project files for relevant responses
• 🔐 Secure API key storage
• 💬 Single message mode for quick questions
• 🔍 Enhanced project analysis with structured insights
• 🎨 Beautiful colored terminal output
• ⚙️ Easy configuration management
• 🌐 Global CLI access

Prerequisites

• Node.js 14.0.0 or higher
• A Groq API key

Getting Your Groq API Key

1. Go to Groq Console
2. Sign in with your account
3. Click "Create API key"
4. Copy the generated API key

Installation

Install from npm (Recommended)

npm install -g ai-cli-oss

After global installation, you can use ai-chat from anywhere in your terminal.

Install from source (local dev)

# Clone and install deps
npm install

# Link globally for local development
npm install -g .

Quick Start

1. First-time setup (guided):

   ai-chat setup

   This will guide you through the initial configuration.

2. Start chatting:

   ai-chat chat

3. Ask a single question:

   ai-chat ask "What is artificial intelligence?"

Local Agent Mode (No Internet Access Beyond API)

• The CLI only reads your local files for context. It does not browse the web or call any external tools.
• For project-specific help, simply run within your repository directory:

  ai-chat analyze
  ai-chat ask "Explain this repository"

• To keep runs ephemeral (no saved key), use an environment variable:

  GROQ_API_KEY=sk_... ai-chat ask "hello"

Why GPT-OSS Shines Here

• Fast, instruction-following OSS models produce concise, actionable developer guidance.
• Strong code reasoning helps produce high-signal analysis and safe step-by-step changes.
• The CLI’s structured system prompts make model behavior predictable and auditable.

Usage

Commands

• ai-chat chat - Start an interactive chat session (default command)
• ai-chat ask <message> - Send a single message and get a response
• ai-chat analyze - Analyze current project directory
• ai-chat analyze --detailed - Detailed project analysis
• ai-chat setup - Interactive first-time setup
• ai-chat config [options] - Manage configuration
• ai-chat --help - Show help information

Configuration Options

# Set API key
ai-chat config --key YOUR_API_KEY

# Set model (default: openai/gpt-oss-20b)
ai-chat config --model openai/gpt-oss-20b

# Show current configuration
ai-chat config --show

# Clear all configuration
ai-chat config --clear

You can also supply your key via environment variables (no config needed):

# Temporarily for a single command
GROQ_API_KEY=sk_... ai-chat ask "Hello"

# PowerShell (Windows)
$env:GROQ_API_KEY="sk_..."; ai-chat chat

# Persist in your shell profile (bash/zsh)
export GROQ_API_KEY=sk_...

Optional overrides:

# Override model without changing saved config
GROQ_MODEL=openai/gpt-oss-20b ai-chat ask "hi"

🧠 Smart Context Detection

AI Chat CLI intelligently determines when to use project context vs. general knowledge!

The CLI automatically analyzes your questions and decides whether to:

• Include Project Context: For questions about your code, files, or project
• Use General Knowledge: For questions about concepts, definitions, or general topics

Examples

General Questions (No Project Context):

a i-chat ask "What is artificial intelligence?"
ai-chat ask "Explain machine learning"
ai-chat ask "What are the benefits of Python?"
ai-chat ask "How does blockchain work?"

Project-Specific Questions (Includes Context):

ai-chat ask "What does this project do?"
ai-chat ask "How can I improve my code?"
ai-chat ask "Analyze this repository"
ai-chat ask "Fix the bugs in this project"
ai-chat ask "Explain this code structure"
ai-chat ask "How do I run this project?"

How Smart Detection Works

The CLI uses intelligent pattern matching to determine context needs:

• General Knowledge Triggers: "What is...", "Define...", "Explain [concept]...", "Tell me about..."
• Project Context Triggers: "This project...", "My code...", "Analyze this...", "How does this work..."
• Keyword Detection: Looks for project-related terms like "implement", "fix", "refactor", "package.json", etc.

📁 File Context Features

When project context is detected, the CLI provides enhanced project-aware responses!

Automatic Context Detection

When you're in a project directory, the CLI automatically:

• Scans for relevant code files (.js, .py, .java, .cpp, etc.)
• Reads configuration files (package.json, README.md, etc.)
• Excludes unnecessary files (node_modules, .git, etc.)
• Provides project context to the AI for better responses

Enhanced Project Analysis

# Quick project analysis with summary
ai-chat analyze

# Comprehensive analysis with detailed insights
ai-chat analyze --detailed

Basic Analysis includes:

• Project summary and purpose
• Technologies and dependencies
• Code structure overview
• Notable observations

Detailed Analysis includes:

• Complete project overview
• Technical architecture analysis
• Code quality assessment
• Security considerations
• Performance recommendations
• Actionable improvement suggestions

Context-Aware Questions

Ask questions about your project and get relevant answers:

# The AI will automatically include your project files as context
ai-chat ask "How can I improve this code?"
ai-chat ask "What does this project do?"
ai-chat ask "How do I add a new feature?"
ai-chat ask "Are there any bugs in my code?"
ai-chat ask "How do I set up this project?"

Supported File Types

• Code: .js, .jsx, .ts, .tsx, .py, .java, .cpp, .c, .cs, .php, .rb, .go, .rs, .swift, etc.
• Web: .html, .css, .scss, .sass
• Config: .json, .yaml, .yml, .toml, .ini
• Documentation: .md, .txt, .rst
• Scripts: .sh, .bat, .ps1
• Other: .sql, .dockerfile, .gitignore

How It Works

1. Smart Detection: The CLI detects when you ask project-related questions
2. File Scanning: Scans your directory for relevant files (up to 200KB total)
3. Context Building: Creates a structured context with file contents
4. Enhanced Prompts: Sends your question along with project context to the AI
5. Relevant Responses: Get answers that are specific to your project structure and code

Configuration Storage

Your API key and settings are stored securely using the conf package:

• Windows: %APPDATA%/ai-cli-oss-nodejs/config.json
• macOS: ~/Library/Preferences/ai-cli-oss-nodejs/config.json
• Linux: ~/.config/ai-cli-oss-nodejs/config.json

Hackathon Judging Criteria Alignment

• Application of gpt-oss: Purpose-built prompts and flows that leverage OSS models’ reasoning strengths for code understanding, local project analysis, and safe file operations. No web browsing; the model focuses on your local repository context.
• Design: Simple, accessible CLI UX with thoughtful safety:
  • Clear onboarding (setup) and config (config --key, env vars)
  • Colored, readable output and progress messages
  • Explicit file-operation format for transparency and control
• Potential Impact: Makes AI-powered developer assistance universally accessible from any terminal; useful for code reviews, onboarding, documentation generation, and iterative improvements in any repo.
• Novelty of the Idea: Blends conversational AI with a minimal, auditable agentic pattern inside a CLI. No hidden actions; file changes are proposed in a standardized format that can be executed locally.

Troubleshooting

Common Issues

1. "No API key configured" error:

   ai-chat config --key YOUR_GOOGLE_API_KEY

2. "Invalid API key" error:

   • Verify your API key is correct
   • Ensure you have valid Groq API credits
   • Check that your API key has the necessary permissions

3. "API quota exceeded" error:

   • Check your Groq account billing and usage limits
   • Monitor your API usage in the Groq Console

4. Network connectivity issues:

   • Check your internet connection
   • Verify you can access Groq's services
   • Consider firewall/proxy settings

Getting Help

If you encounter issues:

1. Run ai-chat config --show to verify your configuration
2. Check the Groq documentation
3. Ensure your API key has the correct permissions

Examples

Development Assistance

ai-chat ask "How do I implement a binary search in JavaScript?"
ai-chat ask "Explain the differences between REST and GraphQL"

Learning and Education

ai-chat ask "Explain machine learning concepts"
ai-chat ask "What are design patterns in software engineering?"

Writing Help

ai-chat ask "Help me write a professional email"
ai-chat ask "Proofread this text: [your text]"

Security Notes

• Your API key is stored locally and never shared
• The tool only communicates with Groq's official API
• No conversation data is stored permanently

Contributing

Feel free to submit issues and enhancement requests!

License

MIT License - see LICENSE file for details.