🔥 Flame - AI-Powered CLI Coding Assistant

An intelligent command-line interface (CLI) application that functions as an AI coding assistant directly in your terminal, powered by your choice of API.

✨ Features

• Interactive REPL: Continuous chat loop with full conversation context.
• System Awareness: Automatically gathers context about your environment (OS, project structure, git status, etc.).
• Global Configuration: Persistent settings (API key, model, etc.) stored globally in ~/.flame/.env.
• Real-time Streaming: Responses stream directly into your terminal for a responsive experience.
• Safe File Operations: Create and edit files with intelligent diff previews and explicit user approval.
• Terminal Execution: Command suggestions that you can execute safely with a single keypress.
• Security First: Dangerous command detection and path validation protect your system.
• Multi-turn Logic: Full chat history maintenance for complex workflow handling.

🚀 Quick Start

Prerequisites

• Python 3.10+
• A API key
• pip or poetry for dependency management

Installation

1. Install via pip:

   pip install flamecli

2. Setup configuration:

   # Run the interactive setup to configure your API key, base URL, and model.
   # This will save your settings globally in ~/.flame/.env
   flame --setup

Test Connection

Before running the REPL, verify your setup:

flame --check

Expected output:

🔍 Testing connection to API...
✅ Connection successful!

Start the CLI

flame

Happy coding! 🔥

💬 Usage Examples

Basic Chat

You: What does this code do?
[paste code]

🤖 Flame: This code does...

Get Project Context

You: help

Available Commands:

  help          - Show this help message
  context       - Show current system context
  clear         - Clear conversation history
  exit          - Exit the program
  /run <cmd>    - Suggest running a command (AI-aware)
  /edit <file>  - Suggest editing a file
  /create <file> - Suggest creating a file

View System Context

You: context

📍 System Context:

📍 Working Directory: /path/to/project
🖥️  System: Linux 6.1.0 | Python 3.11.0
🌿 Git Status: On branch main
📂 Project Structure:
  project-name/
  ├── main.py
  ├── utils/
  └── ...
📊 File Summary:
  Total files: 24
  .py: 12
  .md: 3
  ...

AI-Suggested File Creation

You: Create a requirements.txt with common Python packages

🤖 Flame: I'll create a requirements.txt with popular packages...

📝 Create File: requirements.txt
   Suggested by AI assistant

Preview:
requests>=2.28.0
python-dotenv>=0.20.0
rich>=13.0.0
...

✅ Create this file? [y/n]: y
✅ File created: requirements.txt

AI-Suggested Command Execution

You: How do I install the dependencies?

🤖 Flame: You can run pip install...

🔧 Run Command:
   Suggested by AI assistant

Command:
   pip install -r requirements.txt

✅ Execute this command? [y/n]: y
✅ Command executed successfully

Output:
Collecting requests...
...

Clear History

You: clear
✅ Conversation history cleared

🏗️ Architecture

Directory Structure

flame/
├── api/
│   ├── __init__.py
│   └── client.py          # API wrapper
├── cli/
│   ├── __init__.py
│   ├── repl.py            # Interactive REPL loop
│   └── executor.py        # File and command execution
├── utils/
│   ├── __init__.py
│   └── context.py         # System context collector
├── main.py                # Entry point
├── pyproject.toml         # Project configuration
├── .env.example           # Environment template
└── .env                   # Your configuration (gitignored)

Component Interaction

┌─────────────────────────────────────────┐
│         main.py (Entry Point)           │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│    REPL (cli/repl.py)                  │
│  ├─ Interactive loop                   │
│  ├─ Message history                    │
│  └─ Command handling                   │
└──────────────┬──────────────────────────┘
               │
        ┌──────┴──────┬────────────┐
        ▼             ▼            ▼
   ┌────────┐   ┌──────────┐  ┌─────────┐
   │ API    │   │FileExecutor │ │CommandExecutor
   │ Client │   │(executor.py)│ │(executor.py)
   │        │   │             │ │
   │• Stream │   │• Safe file  │ │• Command checks
   │• Validate│   │  ops        │ │• Approval prompts
   │• Async   │   │• Diffs      │ │• History
   └────────┬────────┘   └──────────────┘ └─────────────┘
            │
      SystemContext
      (utils/context.py)
      ├─ OS info
      ├─ Git status
      ├─ Project structure
      └─ File summary

🔒 Security Features

File Operations Security

1. Path Validation: All file paths are validated to stay within the project directory
2. Diff Preview: Before writing, users see exactly what changes will be made
3. User Approval: Every file creation/edit requires explicit user confirmation
4. Safe by Default: Operations are blocked if path escapes project root

Command Execution Security

1. Dangerous Pattern Detection: Blocks commands matching risky patterns:

   • rm -rf / (recursive root deletion)
   • sudo (privilege escalation)
   • dd (disk operations)
   • mkfs (filesystem formatting)
   • Fork bombs

2. User Approval: Every command execution requires explicit confirmation

3. Timeout Protection: Commands are forcibly terminated after 30 seconds

4. Error Reporting: Command failures are clearly reported

API Key Security

• Store in .env file (add to .gitignore automatically)
• Never commit .env to version control
• Use environment variables in production
• Supports .env.example for template sharing

📋 Configuration

Environment Variables

Flame uses a .env file for configuration. The --setup command handles this for you, but you can also manually edit the file at ~/.flame/.env.

# Required: Your API key
FLAME_API_KEY=your_key_here

# Optional: API endpoint (defaults to a standard proxy)
FLAME_API_BASE_URL=https://api.example.com/v1

# AI model to use
FLAME_MODEL=google/gemini-3-flash-preview

# CLI settings
CLI_THEME=dark
CLI_STREAM_SPEED=normal
DEBUG=false

🎮 CLI Options

python main.py --help

usage: main.py [-h] [--version] [--check] [--dir DIR] [--model MODEL] [--debug]

Flame - AI Coding Assistant powered by API

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --check               Test connection to API
  --setup               Interactive setup to configure your API key and settings
  --dir DIR             Working directory (defaults to current directory)
  --model MODEL         AI model to use (overrides FLAME_MODEL env var)
  --debug               Enable debug mode

🐛 Troubleshooting

Connection Failed

Error: Connection failed. Check your API key and network.

Solutions:

1. Verify API key is correct in .env
2. Check internet connection
3. Verify API base URL is correct
4. Test with: python main.py --check --debug

Import Errors

Error: ModuleNotFoundError: No module named 'api'

Solutions:

1. Ensure you're in the project root directory
2. Virtual environment is activated
3. Dependencies are installed: pip install -e .

Command Won't Execute

Error: Dangerous Command Detected

Solutions:

1. Command matches safety patterns (by design)
2. Use --debug to see pattern matching
3. Use safer alternative commands
4. File path must be within project directory

📚 Advanced Usage

Using with Different Models

# Override model at runtime
python main.py --model llama2

# Or set in .env:
FLAME_MODEL=llama2

Using Different Working Directory

# Analyze a different project
python main.py --dir /path/to/other/project

Debug Mode

# See detailed error messages
python main.py --debug

🔧 Development

Running Tests

pytest tests/

Code Style

# Format code
black api/ cli/ utils/ main.py

# Lint
flake8 api/ cli/ utils/ main.py

📝 License

MIT License - feel free to use and modify!

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

🙋 Support

Need help? Try:

1. Check .env configuration
2. Run python main.py --check to verify setup
3. Use --debug flag for detailed error messages
4. Review this README for common issues

---

Made with 🔥 by API Community