What FELLA Does

FELLA is an interactive chat-first CLI for Windows that turns natural language into file operations, desktop actions, and browser automation:

organise downloads by type
open the latest pdf from downloads
move report.pdf from desktop to documents
create a folder on desktop called Projects
open notepad
undo

Under the hood, FELLA runs an agentic loop:

1. Reads your natural-language intent.
2. Formulates tool calls (search, list, move, organise, launch, screen automation).
3. Executes with security path guards and action policies.
4. Feeds tool results back to the model for next-step planning.
5. Returns formatted responses directly in your terminal.

Destructive operations are confirmation-gated. Organise operations run as preview-first and apply only after explicit confirmation.

Quick Start

1. Installation

# Clone the repository
git clone https://github.com/Deepakchandrasekar05/FELLA.git
cd FELLA

# Install dependencies
npm install

2. Configuration

Create or update .env in the project root or %USERPROFILE%\.fella\.env:

GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.3-70b-versatile
SUPABASE_URL=your_supabase_url_here
SUPABASE_ANON_KEY=your_supabase_anon_key_here

3. Running FELLA CLI

Launch the interactive terminal interface directly:

# Via npm script:
npm run cli

# Or directly:
node bin/fella.js

# On Windows:
bin\fella.bat

Available Commands

| Command | Description | |---|---| | npm run cli | Launch interactive FELLA terminal interface | | fella sessions | List previous saved chat sessions | | fella resume <id> | Resume a saved session conversation | | fella delete sessions <id> | Delete a session from SQLite database | | fella login | Sign in with email and password | | fella login --google | Sign in with Google account in browser | | fella signup | Create a new account | | fella logout | Clear saved credentials | | fella whoami | Show currently signed-in user | | npm test | Run the comprehensive test suite (45 assertions) |

Project Structure

FELLA/
├── bin/
│   ├── fella.bat               # Windows batch launcher
│   └── fella.js                # Cross-platform Node launcher (loads tsx & JSX)
├── cli/                        # React 19 + Ink Terminal UI (JSX)
│   ├── app.jsx                 # Interactive TUI state and screen management
│   ├── index.jsx               # CLI entrypoint & argument router
│   ├── authCommands.js         # Interactive login / signup / OAuth handlers
│   └── components/
│       ├── header.jsx          # Gradient ASCII logo and version badges
│       ├── inputBar.jsx        # Real-time prompt input with key handling
│       ├── messageList.jsx     # Streaming message thread and spinner
│       ├── statusBar.jsx       # Shortcuts footer & session indicator
│       ├── fellaLogo.jsx       # Pixel-art ASCII rendering
│       └── catArt.js           # Logo pixel data
└── server/                     # Core Agentic Engine & 14 System Tools
    ├── agent/                  # System prompts & conversation loop
    ├── auth/                   # Supabase authentication & token persistence
    ├── execution/              # Engine, ToolRegistry, and UndoStack
    ├── llm/                    # Groq client & tool-calling router
    ├── memory/                 # SQLite turn history & semantic fact store
    ├── platform/               # Windows native helpers & shell integrations
    ├── security/               # PathGuard directory sandbox & policies
    └── tools/                  # 14 agent tools (files, apps, screen, browser)

Security Policy

• PathGuard strictly enforces system folder access restrictions:
  • System directories (C:\Windows, C:\Program Files, C:\ProgramData) are blocked.
  • Directory traversal (../, ..\) is rejected.
• Mutating operations (deleteFile, organiseByRule, moveFile) trigger interactive confirmation prompts before execution.