felon — Anonymous Offline Terminal Agent

A CLI tool that wraps your terminal with an offline AI that converts natural language to shell commands. Uses a local GGUF model. No cloud, no telemetry, no API keys.

Also known as: fsi (Ferrell Synthetic Intelligence) or nomad

Quick Start

# Install
pip install rich
git clone https://github.com/yourusername/felon-terminal
cd felon-terminal && pip install .

# Or download from HF
# wget https://huggingface.co/FerrellSyntheticIntelligence/fsi-felon/resolve/main/felon.tar.gz
# tar xzf felon.tar.gz && cd felon && pip install .

# Run
fsi

On first run, felon scans ~/ for git repos and builds a context map of your projects. Without a model, type $ <command> to run commands directly.

Usage

$ fsi

  ╔═══╗╔═══╗╔════╗╔═══╗╔═══╗
  ╚══╗ ║║ ══╣║ ══╝║╔══╝╚══╗ ║
  ╔══╝ ║║ ══╣║ ║  ║╚══╗╔══╝ ║
  ╚═══╝╚═══╝╚╝  ╚═══╝╚═══╝

           nomad
  anonymous · offline · learns

  ◇ found 14 project(s)
  ◇ you have 14 project(s)
  ◇   - felon: Python (9)

┌─ ◆ you ───────────────────────────┐
│ find all large files               │
└────────────────────────────────────┘
┌─ ◈ nomad ─────────────────────────┐
│ $ find . -type f -size +100M      │
│ ● exit 0                           │
│ ./data/big.tar.gz                   │
└────────────────────────────────────┘
  run this? [Y/n]:

Commands

Input	Action
find all large files	AI generates a command, you approve
$ git push	Run command directly
!!	Re-run last command
rescan	Re-scan codebase
scaninfo	Show project knowledge
feedback	Rate last response
export	Export interaction history for fine-tuning
clear	Clear screen
exit	Quit

Architecture

felon/
├── cli.py          # Rich TUI chat interface (Alaska dark theme)
├── engine.py       # LLM inference (llama.cpp server or local bindings)
├── shell.py        # Safe execution with timeout, danger detection
├── scanner.py      # Codebase scanner (auto-discovers projects)
├── history.py      # Interaction logger + training data export
├── context.py      # Session context (cwd, git, OS)
├── config.py       # ~/.felon/config.json
└── train_terminal.py  # LoRA fine-tune on collected usage data

How the Learning Works

1. First run: scanner.py finds all git repos in ~/, fingerprints languages and dependencies
2. Every interaction: User input, generated command, approval status, output, and ratings are logged to ~/.felon/history.jsonl
3. Fine-tuning: Run train_terminal.py on exported history to create a personalized model that understands your workflows
4. Continual: Over time, the model adapts to your project patterns and command style

Configuration

~/.felon/config.json:

{
  "mode": "none",
  "model_path": "models/assassin-f16.gguf",
  "server_url": "http://127.0.0.1:8080",
  "temperature": 0.3,
  "max_tokens": 128,
  "confirm_command": true,
  "timeout": 30
}

• mode: "none" (direct commands only), "server" (llama.cpp HTTP), "local" (llama-cpp-python)
• confirm_command: Always ask before executing AI-generated commands

Model Setup

Option 1: Built-in local model

# Download FSI-FELON-168M GGUF
mkdir -p ~/.felon/models
wget -P ~/.felon/models https://huggingface.co/FerrellSyntheticIntelligence/FSI-FELON-168M/resolve/main/assassin-f16.gguf

# Set config
echo '{"mode": "local", "model_path": "~/.felon/models/assassin-f16.gguf"}' > ~/.felon/config.json

Option 2: llama.cpp server

# Start llama.cpp server with any GGUF
./llama-server -m assassin-f16.gguf --host 127.0.0.1 --port 8080

# In felon config
echo '{"mode": "server", "server_url": "http://127.0.0.1:8080"}' > ~/.felon/config.json

Terminal Training

To fine-tune the model on your usage patterns:

# Collect usage data by using the tool
# Then export and train
python felon/train_terminal.py \
  --data ~/.felon/history.jsonl \
  --model FerrellSyntheticIntelligence/FSI-FELON-168M \
  --output ./my-personal-model \
  --epochs 3 \
  --gguf

Requires: torch, transformers, peft, trl, datasets, accelerate

Performance

Mode	Startup	Response	Use Case
No model	Instant	—	Direct commands only
Server (llama.cpp)	1-2s	~50ms	Recommended for tablet
Local (llama-cpp-python)	2-5s	~50ms	Laptop/desktop

Dependencies

• Runtime: Python 3.10+, rich
• AI (optional): llama.cpp server (for server mode) or llama-cpp-python (for local mode)
• Training (optional): torch, transformers, peft, trl, datasets, accelerate

Related

• FSI-FELON-168M — The GGUF model
• Prometheus Distillation Pipeline — Training scripts and data

License

Apache 2.0