flouri 1.0.0

AI-powered bash environment enhancement tool.

Flouri (flouri.sh)

╔═════════════════════════════════════════════════════════════════════╗
║                                                                     ║
║  ███████╗██╗      ██████╗ ██╗   ██╗██████╗ ██╗   ███████╗██╗  ██╗   ║
║  ██╔════╝██║     ██╔═══██╗██║   ██║██╔══██╗██║   ██╔════╝██║  ██║   ║
║  █████╗  ██║     ██║   ██║██║   ██║██████╔╝██║   ███████╗███████║   ║
║  ██╔══╝  ██║     ██║   ██║██║   ██║██╔══██╗██║   ╚════██║██╔══██║   ║
║  ██║     ███████╗╚██████╔╝╚██████╔╝██║  ██║██║██╗███████║██║  ██║   ║
║  ╚═╝     ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝╚═╝╚══════╝╚═╝  ╚═╝   ║
║                                                                     ║
║                    AI-Powered Terminal Environment                  ║
║                                                                     ║
╚═════════════════════════════════════════════════════════════════════╝

Flouri is an open-source tool that enhances your terminal environment with agentic AI capabilities. It allows you to interact with various LLMs directly from your terminal and execute complex workflows through AI orchestration.

Features

• Terminal Environment: AI-enabled terminal that looks and feels like a real bash terminal

  • Execute commands directly (e.g., ls, git status, cd ~/projects)
  • AI assistance available on-demand with ? prefix or Ctrl+A
  • Real-time command output with color-coded results

• AI Assistance: Get help from AI without leaving your terminal

  $ ? explain the difference between git merge and rebase
  $ ? how do I check disk usage?
  $ ? help me write a script to find large files
  

• Direct Command Execution: Run bash commands immediately - no agent wrapper needed

  $ ls -la
  $ git status
  $ cd ~/projects
  

• Smart Completions: Bash-style tab completion with support for custom completion scripts

  • Built-in completions for common commands (cd, git, etc.)
  • Extensible completion system for custom commands
  • Nested directory completion for cd command

• Security Controls: Allowlist and blacklist for AI-executed commands (when AI runs commands via tools)

Prerequisites

• Python 3.10 or later (3.12+ recommended)
• An API key for your chosen LLM provider (e.g., OpenAI, Anthropic, Google)

Upgrading Python

If you need to upgrade Python, you can use:

# Using pyenv (recommended)
pyenv install 3.12.0
pyenv global 3.12.0

# Or download from python.org

Quick Start

1. Install and configure:

   git clone https://github.com/made-after-dark/flouri.git
   cd flouri
   python3.12 -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"
   cp env.example .env
   # Edit .env and add your API_KEY
   

2. Launch the terminal:

   flouri
   

   When you launch Flouri, you'll see:

   • A beautiful ASCII banner animation
   • Welcome message with usage hints
   • Your current directory in the prompt
   • Git branch information (if in a git repository)
   • Command history automatically loaded from previous sessions

3. Start using it:

   $ ls -la                    # Execute commands directly
   $ ? explain git merge       # Ask AI for help
   $ git status                # Normal bash commands work
   $ Ctrl+A                    # Or press Ctrl+A to ask AI
   

Installation

From Source

1. Clone the repository:

   git clone https://github.com/made-after-dark/flouri.git
   cd flouri
   

2. Create and activate a virtual environment:

   python3.12 -m venv .venv
   source .venv/bin/activate
   

3. Install dependencies:

   pip install -e ".[dev]"
   

4. Set up your API key:

   cp env.example .env
   # Edit .env and add your API_KEY and preferred MODEL
   

   The .env file is automatically loaded - no need to source it!

5. (Optional) Install pre-commit hooks for code quality:

   pre-commit install
   

Usage Examples

Daily Workflow Examples

# Navigate and explore
$ cd ~/projects/myapp
$ ls -la                    # Color-coded file listing
$ cd src/components         # Tab completion for nested paths

# Git operations with AI help
$ ? how do I squash the last 3 commits?
$ git log --oneline
$ ? create a commit message for these changes: [paste diff]

# File operations
$ find . -name "*.py" -type f
$ ? show me the largest files in this directory
$ cat config.json | ? explain what this configuration does

# Development tasks
$ ? help me set up a Python virtual environment
$ ? write a script to backup my dotfiles
$ ? explain the difference between async and await in Python

Advanced Usage

# Combine commands with AI
$ ls -la && ? explain what each file in this directory does

# AI-assisted debugging
$ python script.py
$ ? the script failed with error X, how do I fix it?

# Project management
$ ? analyze this project and suggest a better directory structure
$ ? generate a README for this project based on the code
$ ? what dependencies does this project need?

Terminal Interface (TUI) - Recommended

Launch the AI-enabled terminal environment:

flouri
# or
flouri tui

What Happens When You Open Flouri?

When you launch Flouri, the following happens:

1. Banner Display: An animated ASCII banner welcomes you
2. Configuration Loading:
   • Environment variables from .env are loaded
   • Command allowlist/blacklist from config/commands.json is loaded
   • Session logging is initialized
3. Plugin System Initialization:
   • Built-in plugins are registered (zsh bindings, command enhancers)
   • Completion system loads custom completion scripts
4. History Restoration:
   • Command history is loaded from ~/.config/flouri/history
   • Previous session commands are available via arrow keys
5. Ready to Use: You're presented with a prompt showing:
   • Current working directory
   • Git branch (if in a git repository)
   • Git status indicators (if applicable)

Interactive Terminal Features

This opens an interactive terminal where you can:

1. Execute commands directly (just like a normal terminal):

   $ ls -la                           # List files with details
   $ git status                       # Check git status
   $ cd ~/projects                    # Change directory
   $ pwd                              # Print working directory
   $ cat README.md                    # View file contents
   $ grep -r "function" src/          # Search in files
   $ find . -name "*.py"              # Find Python files
   

2. Get AI assistance using the ? prefix:

   $ ? explain the difference between git merge and rebase
   $ ? how do I check disk usage?
   $ ? help me write a script to find large files
   $ ? what's the best way to organize this project?
   $ ? show me how to use docker compose
   

3. Use keyboard shortcuts:

   • Ctrl+A - Start an AI prompt
   • Tab - Auto-complete commands and paths (with nested directory support)
   • ↑/↓ - Navigate command history
   • Ctrl+R - Reverse search through history (fzf-like)
   • Ctrl+L - Clear screen (preserves welcome message)
   • Ctrl+D - Exit Flouri
   • Ctrl+C - Cancel current operation

4. Enhanced Features:

   $ cd                              # Goes to home directory (zsh-like)
   $ cd ...                          # Goes back 2 directories
   $ cd ....                         # Goes back 3 directories
   $ ls                              # Color-coded output (directories, executables, etc.)
   $ git checkout <TAB>             # Smart git command completion
   

Command-Line Interface (CLI)

For non-interactive use or scripting:

# Ask questions (AI responds with text)
flouri agent "Explain how Docker containers work"

# Ask questions with command execution
flouri agent "Show me git status and list all Python files"

# With allowlist (only allow specific commands for AI execution)
flouri agent --allowlist "ls,cd,git,find" "Show me git status and list files"

# With blacklist (prevent specific commands)
flouri agent --blacklist "rm,dd,format" "Help me organize my project files"

# With live streaming (real-time output as AI generates response)
flouri agent --stream "Explain how Docker containers work"
flouri agent -s "List files and show git status"  # Short form

# Complex workflows
flouri agent "Analyze my project structure and suggest improvements"
flouri agent "Find all TODO comments in the codebase and create a summary"

Example CLI Workflows

# Development workflow
flouri agent "Check git status, run tests, and show me any failing tests"

# File management
flouri agent "Find all large files (>100MB) in the current directory"

# Code analysis
flouri agent "Review the code in src/ and suggest refactoring opportunities"

# Documentation
flouri agent "Generate a summary of all the functions in utils.py"

Bash Integration

Add to your ~/.bashrc or ~/.zshrc:

# Add flouri to PATH if installed locally
export PATH=$PATH:/path/to/flouri/.venv/bin

# Create convenient alias (optional)
alias ai='flouri'

Then you can use:

# Launch terminal interface
ai

# Or use CLI mode
ai agent "What is Kubernetes?"

Configuration

Environment Variables

Create a .env file in the project root (see env.example):

API_KEY=your-api-key-here
MODEL=gpt-4o-mini

The .env file is automatically loaded when you run the application - no need to source it!

Supported Models

Flouri uses LiteLLM for multi-provider support. You can use models from:

• OpenAI: gpt-4o-mini, gpt-4, gpt-3.5-turbo, etc.
• Anthropic: claude-3-opus-20240229, claude-3-sonnet-20240229, etc.
• Google: gemini/gemini-2.0-flash, gemini/gemini-pro, etc.
• And many more - see LiteLLM documentation for the full list

To use a different model, set the MODEL environment variable:

MODEL=anthropic/claude-3-opus-20240229

Commands Configuration (Allowlist/Blacklist)

The allowlist and blacklist are managed in config/commands.json. This file is automatically created and updated by the agent.

{
  "allowlist": [
    "ls",
    "git"
  ],
  "blacklist": [
    "rm",
    "dd"
  ]
}

You can manually edit this file, or use the agent's tools to manage it.

Command History

Flouri automatically saves your command history across sessions:

• History Location: ~/.config/flouri/history
• History Features:
  • Persistent across sessions (stored in ~/.config/flouri/history)
  • Navigate with ↑/↓ arrow keys
  • Reverse search with Ctrl+R (fzf-like interface)
  • Case-insensitive search
  • In-memory history limited to 1000 entries per session

The history file is automatically created on first use and persists all your commands for easy access in future sessions.

Development

Prerequisites

• Python 3.10+ (3.12+ recommended)
• pip (Python package installer)
• pre-commit (for git hooks)

Setup

# Install dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

pytest

Linting & Type Checking

ruff check .
black --check .
mypy flouri

Formatting

black .
ruff format .

Project Structure

flouri/
├── .github/              # GitHub Actions workflows
├── flouri/              # Main application source code
│   ├── agent/            # Agent definitions and logic
│   ├── completions/      # Command completion system
│   │   ├── git.py        # Git command completions
│   │   ├── loader.py     # Completion script loader
│   │   └── registry.py   # Completion registry
│   ├── config/           # Configuration management
│   ├── logging/          # Logging utilities
│   ├── plugins/          # Plugin system for extending capabilities
│   │   ├── base.py       # Plugin base classes
│   │   ├── cd_completer.py  # Enhanced cd completion
│   │   ├── enhancers.py  # Command output enhancers
│   │   └── zsh_bindings.py  # Example: zsh-like bindings
│   ├── runner/           # Agent execution logic
│   ├── tools/            # Custom tools for bash execution (modular by context)
│   │   ├── bash/         # Bash execution tools (execute_bash, set_cwd, get_user)
│   │   ├── config/       # Configuration tools (allowlist/blacklist management)
│   │   ├── history/      # History tools (read_bash_history, read_conversation_history)
│   │   ├── system/       # System information tools (get_current_datetime)
│   │   └── globals.py    # Shared global variables
│   └── ui/               # Text User Interface (TUI) and CLI
├── config/               # Persistent configuration files (e.g., commands.json)
├── docs/                 # Project documentation
│   ├── architecture.md   # System architecture
│   ├── plugins.md        # Plugin system guide
│   └── third-party-libraries.md
├── tests/                # Unit and integration tests
├── .env.example          # Example environment variables
├── pyproject.toml        # Project metadata and build configuration
├── README.md             # Project README
├── CHANGELOG.md          # Project changelog
├── CONTRIBUTING.md       # Contribution guidelines
├── SECURITY.md           # Security policy
└── LICENSE               # License file

Extending Flouri

Plugin System

Flouri includes a powerful plugin system that allows you to add custom commands, aliases, and behaviors. Create plugins to:

• Add command aliases (e.g., ll -> ls -la)
• Implement zsh-like features (e.g., cd ... to go back directories)
• Add custom shortcuts and workflows
• Extend terminal capabilities
• Enhance command output with colors and hints

See docs/plugins.md for detailed documentation on creating plugins.

Example: The ZshBindingsPlugin adds zsh-like behaviors:

• cd (alone) → goes to home directory
• cd ... → goes back 2 directories
• cd .... → goes back 3 directories

Completion System

Flouri includes a flexible completion system that supports:

• Built-in completions: Common commands like cd and git have enhanced completions
• Custom completion scripts: Create completion scripts for any command
• Nested directory completion: Smart path completion for cd with nested directory support

Completion scripts can be placed in:

• Project completions: completions/ directory in the project root
• User completions: ~/.config/flouri/completions/

See the completion system in flouri/completions/ for examples.

Security Considerations

• Command Execution: The agent mode can execute commands. Always review what the agent plans to do before confirming execution.
• Allowlist/Blacklist: Use allowlists in production environments to restrict command execution.
• API Keys: Never commit your .env file or API keys to version control.
• Permissions: The agent runs with the same permissions as your user account.

For detailed security information, see SECURITY.md.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Powered by LiteLLM for seamless LLM integration
• Built with Google ADK for agent orchestration
• Terminal interface powered by prompt-toolkit
• Syntax highlighting by Pygments

Roadmap

• Interactive terminal environment
• Config file for persistent settings (commands.json)
• Plugin system for custom tools
• Command completion system
• Better command validation and sandboxing
• Multi-agent orchestration
• Web UI option
• Additional completion scripts for more commands

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions