🦜 parrot

Architecture

Parrot follows a layered architecture with graceful degradation at each level:

User Command Fails (Exit Code != 0)
         ↓
    Shell Hook (bash/zsh/fish)
         ↓
    parrot mock "command" "exit_code"
         ↓
    Load Configuration
    - Check PARROT_CONFIG env
    - Load /etc/parrot/config.toml
    - Load ~/.config/parrot/config.toml
    - Apply environment overrides
         ↓
    Context Extraction
    ├── Command type detection (40+ types)
    ├── Error classification (20+ categories)
    ├── Intent parsing (what were they trying to do?)
    └── Environment context (CI, git, project, time)
         ↓
    LLM Manager (Smart Fallback)
    ├── 1. Try API backend (OpenAI/Anthropic)
    │   └── Timeout: 3s default
    ├── 2. Try Local backend (Ollama)
    │   └── Timeout: 5s default
    └── 3. Fall through to 6-tier intelligence
         ↓
    Response Processing
    ├── Clean LLM artifacts
    ├── Apply personality filter
    └── Format for terminal
         ↓
    Output (colored, formatted)

Key Modules

• cmd/ - CLI commands (mock, install, setup, configure, status)
• internal/config/ - Configuration loading and validation
• internal/llm/ - LLM manager, backends, response generation
• internal/context/ - Environment and command context extraction
• internal/intelligence/ - 6-tier fallback intelligence system
• internal/output/ - Formatting, colors, personality application

Backend System

Parrot supports three backend types with automatic fallback:

1. API Backend (Primary)

Cloud-based LLM providers for highest quality responses. Supports OpenAI, Anthropic Claude, and any OpenAI-compatible API endpoint.

• Default timeout: 3 seconds
• Automatically falls back on timeout or error
• API key required (via config or PARROT_API_KEY env)

2. Local Backend (Secondary)

Ollama-based local LLM for 100% private, offline operation. No data leaves your machine.

• Default timeout: 5 seconds (local models may be slower)
• Mode-dependent: "snappy" uses 3s, "spicy" uses 5s
• Background model warmup for better performance
• Use OLLAMA_KEEP_ALIVE="1h" to keep model loaded

3. Fallback Intelligence (Tertiary)

Built-in 6-tier intelligence system. Guaranteed to work with zero external dependencies. Uses ML-inspired algorithms for context-aware selection from ~3000 insults.

• Sub-20ms latency
• No network required
• Learns from user patterns
• Persists history for improvement

LLM Manager

The LLM manager (internal/llm/manager.go) coordinates backend selection and handles the fallback chain:

func (m *Manager) Generate(ctx Context) Response {
    // 1. Try API backend if enabled and configured
    if m.config.API.Enabled && m.apiBackend.Ready() {
        resp, err := m.apiBackend.Generate(ctx, m.config.API.Timeout)
        if err == nil {
            return m.clean(resp, "api")
        }
    }

    // 2. Try local Ollama if enabled and running
    if m.config.Local.Enabled && m.localBackend.Ready() {
        timeout := m.getLocalTimeout()
        resp, err := m.localBackend.Generate(ctx, timeout)
        if err == nil {
            return m.clean(resp, "local")
        }
    }

    // 3. Fall through to 6-tier intelligence
    return m.fallbackIntelligence.Generate(ctx)
}

Response Cleaning

LLM responses are processed before display:

• Maximum 150 characters (truncated for terminal UX)
• Remove LLM artifacts ("Sure!", "Here's...", etc.)
• Strip quotes and markdown formatting
• Remove annotations and explanations
• Apply personality-appropriate tone

Response Cache

Parrot caches responses to avoid repeated LLM calls for the same failure patterns:

Cache Key Components

• Command: The failed command (normalized)
• Type: Command type (git, npm, docker, etc.)
• Exit code: The specific exit code
• Mode: snappy vs spicy

LRU Eviction

The cache uses LRU (Least Recently Used) eviction to maintain a reasonable size. Default capacity is 1000 entries.

Cache Location

Shell Integration

Parrot integrates with your shell to automatically intercept failed commands. The parrot install command auto-detects your shell and installs the appropriate hooks.

Bash Hooks

For Bash, parrot uses PROMPT_COMMAND to check the exit status of the previous command:

# Bash hook mechanism
__parrot_last_command=""
__parrot_last_exit_code=0

parrot_debug_trap() {
    __parrot_last_command="$BASH_COMMAND"
}

parrot_prompt_command() {
    local exit_code=$?
    if [[ $exit_code -ne 0 && -n "$__parrot_last_command" ]]; then
        if [[ "$PARROT_ASYNC" == "true" ]]; then
            parrot mock "$__parrot_last_command" "$exit_code" &
        else
            parrot mock "$__parrot_last_command" "$exit_code"
        fi
    fi
    __parrot_last_command=""
}

trap 'parrot_debug_trap' DEBUG
PROMPT_COMMAND="parrot_prompt_command; ${PROMPT_COMMAND}"

Manual Installation

Add to ~/.bashrc:

export OLLAMA_KEEP_ALIVE="1h"
source /usr/share/parrot/parrot-hook.sh

Zsh Hooks

For Zsh, parrot uses preexec and precmd hooks:

# Zsh hook mechanism
autoload -Uz add-zsh-hook

__parrot_last_command=""

parrot_preexec() {
    __parrot_last_command="$1"
}

parrot_precmd() {
    local exit_code=$?
    if [[ $exit_code -ne 0 && -n "$__parrot_last_command" ]]; then
        if [[ "$PARROT_ASYNC" == "true" ]]; then
            parrot mock "$__parrot_last_command" "$exit_code" &
        else
            parrot mock "$__parrot_last_command" "$exit_code"
        fi
    fi
    __parrot_last_command=""
}

add-zsh-hook preexec parrot_preexec
add-zsh-hook precmd parrot_precmd

Manual Installation

Add to ~/.zshrc:

export OLLAMA_KEEP_ALIVE="1h"
source /usr/share/parrot/parrot-hook.sh

Fish Hooks

For Fish, parrot uses the fish_postexec event:

function parrot_postexec --on-event fish_postexec
    set -l last_status $status
    set -l last_cmd $argv[1]

    if test $last_status -ne 0
        if test "$PARROT_ASYNC" = "true"
            parrot mock "$last_cmd" "$last_status" &
        else
            parrot mock "$last_cmd" "$last_status"
        end
    end
end

Installation

Error Classification

The error classifier (internal/llm/error_classifier.go) recognizes 20+ error categories from exit codes, command patterns, and keywords:

Classification Priority

Classification follows a priority order:

1. Exit code match (most specific)
2. Command prefix match (git, npm, docker, etc.)
3. Keyword detection in command or context
4. Generic fallback based on exit code ranges

Personality System

Parrot supports three personality levels that affect response tone and severity:

Mild

Gentle, constructive feedback. Severity level 1-4. Good for professional environments or users who prefer encouragement over roasting.

🦜 That command didn't work. Maybe check the documentation?
🦜 Hmm, something went wrong. The error message might have clues.
🦜 That didn't go as planned. Double-check the syntax?

Sarcastic (Default)

Witty, clever mocking. Severity level 4-7. Balanced humor and feedback.

🦜 Git rejected your code harder than your last pull request.
🦜 Permission denied. Even your own computer doesn't trust you.
🦜 npm install failed. The node_modules folder is crying somewhere.

Savage

Brutal, devastating roasts. Severity level 6-10. Not recommended for sensitive souls.

🦜 Your docker build failed harder than your career trajectory.
🦜 Segfault. Your code quality mirrors your life choices.
🦜 Git rejected you. Just like everyone else eventually does.

Personality Selection

Context Awareness

Parrot extracts context from the environment to deliver more relevant responses:

Time of Day

Different responses for late night coding vs. morning:

🦜 It's 3 AM. The bugs aren't the only thing that needs sleep.
🦜 Late night coding? Bold strategy. Let's see if it pays off.

Git Context

Branch-aware responses:

• main/master: Extra severity for breaking the main branch
• feature/*: Feature-specific jokes
• hotfix/*: Urgency-aware responses
• release/*: Release pressure jokes

CI/CD Detection

Detects CI environments via environment variables:

• GitHub Actions (GITHUB_ACTIONS)
• GitLab CI (GITLAB_CI)
• Jenkins (JENKINS_URL)
• CircleCI (CIRCLECI)
• Travis CI (TRAVIS)

Project Type Detection

Detects project type from configuration files:

• Node.js (package.json)
• Rust (Cargo.toml)
• Go (go.mod)
• Python (pyproject.toml, setup.py)
• Docker (Dockerfile, docker-compose.yml)

Data Persistence

Parrot persists data for continuous learning and improvement:

Data Safety

• All writes are atomic (write to temp, then rename)
• Data is loaded lazily on first use
• Corrupted files are automatically reset
• Total disk usage: typically 50-200KB

Reset Data

Tier 1: Basic Context Matching

The foundation tier extracts basic information from the failed command:

Command Type Detection (40+ types)

• VCS: git, svn, hg, cvs
• Package managers: npm, yarn, pip, cargo, go, brew, dnf, apt
• Containers: docker, podman, kubectl, helm
• Build tools: make, cmake, gradle, maven, cargo build
• Languages: python, node, ruby, rustc, gcc, javac
• System: sudo, chmod, chown, ssh, scp, rsync

Exit Code Awareness

Argument Pattern Matching

• --force / -f: Force-related jokes
• sudo: Privilege escalation jokes
• -r / --recursive: Recursion jokes
• --help / --version: RTFM jokes

Tier 2: Environment Detection

Tier 2 considers the broader environment context:

Time of Day

• Late night (12 AM - 5 AM): Sleep deprivation jokes
• Early morning (5 AM - 9 AM): Coffee jokes
• Work hours (9 AM - 6 PM): Normal responses
• Evening (6 PM - 12 AM): Overtime jokes

Git Branch Context

• main/master: "Breaking main? Breaking everyone's day."
• feature/*: "Feature branch: Featured failure."
• hotfix/*: "Hotfix that's about to get hotter."
• release/*: "Release branch, release the tears."

Working Directory

• /tmp: Temporary code jokes
• /root: Root user jokes
• ~/Desktop: Desktop development jokes
• /var/log: Log analysis jokes

Shell Type

Detected from SHELL environment variable: bash, zsh, fish, ksh, etc.

Tier 3: LLM-like Context Awareness

Tier 3 applies more sophisticated context understanding:

CI/CD Detection

Checks environment variables for CI systems:

CI Environment Variables Checked:
- GITHUB_ACTIONS, GITHUB_WORKFLOW
- GITLAB_CI, GITLAB_PIPELINE_ID
- JENKINS_URL, BUILD_NUMBER
- CIRCLECI, CIRCLE_JOB
- TRAVIS, TRAVIS_JOB_ID
- AZURE_PIPELINES, BUILD_BUILDID
- CI (generic)

CI responses include team-shame elements: "Everyone on the team got your failure notification."

Error Pattern Recognition

Parses error output for specific patterns:

• permission_denied: EACCES, "denied", "forbidden"
• connection_refused: ECONNREFUSED, "connection refused"
• timeout: "timed out", "timeout"
• disk_full: ENOSPC, "no space left"

Repeated Failure Detection

Tracks consecutive failures of the same command:

• 2nd attempt: "Same command, same failure."
• 3rd attempt: "Third time's NOT the charm."
• 5+ attempts: Escalating to savage mode automatically

Tier 4: Historical Learning

Tier 4 uses persistent history to personalize responses:

Failure Streak Tracking

Tracks consecutive and total failures per command type:

{
  "npm_install": {
    "total_failures": 47,
    "current_streak": 3,
    "max_streak": 7,
    "last_failure": "2024-12-15T14:23:00Z"
  },
  "git_push": {
    "total_failures": 23,
    "current_streak": 0,
    "max_streak": 4,
    "last_failure": "2024-12-14T09:15:00Z"
  }
}

Pattern-based Insults

Uses history to generate personalized responses:

🦜 You've failed npm install 47 times. At this point it's not
   the dependencies, it's you.
🦜 Git has rejected you 23 times. Take the hint.

Dynamic Template Generation

Combines templates with history data for infinite variations:

• Insert failure counts
• Reference previous commands
• Compare to historical performance
• Mention time since last success

Tier 5: Hybrid Ensemble ML

Tier 5 implements ML-inspired techniques in pure Go:

TF-IDF Scoring

Term Frequency-Inverse Document Frequency for semantic matching:

TF-IDF(term, insult, corpus) = TF(term, insult) × IDF(term, corpus)

Where:
- TF = frequency of term in insult / total terms in insult
- IDF = log(total insults / insults containing term)

Context terms are extracted from:
- Command tokens
- Error keywords
- Environment context

Markov Chain Generation

Generates novel insults from a trained model:

• Trained on ~3000 insult corpus
• 2nd-order Markov chain (bigram context)
• Temperature-controlled sampling
• Post-generation validation

5-Factor Weighted Voting

Ensemble combines multiple scoring methods:

Final Score = weighted average of:
1. TF-IDF semantic similarity (weight: 0.25)
2. Tag match score (weight: 0.20)
3. Personality fit (weight: 0.15)
4. Novelty score (weight: 0.25)
5. Context relevance (weight: 0.15)

Tier 6: Advanced ML Techniques

The most sophisticated tier implements cutting-edge ML concepts in pure Go:

Contextual Memory Graph

Tracks failure sequences as a directed graph to predict and respond to patterns:

Graph Structure:
Nodes = (command_type, exit_code, context)
Edges = transitions between failure states
Weight = frequency × recency

Example graph:
  git_add(1) → git_commit(1) → git_push(1)
       ↑           ↓
       └───────────┘ (common cycle)

When git_add fails, if the user typically follows with
git_commit which also fails, proactively mock the pattern.

Pattern Detection

The graph identifies common failure sequences and generates responses like:

🦜 Ah, the classic git-add-commit-push trifecta of failure.
🦜 Let me guess: npm install, npm run build, npm test - all failed?

GAN-inspired Adversarial Generator

Implements a GAN-inspired generator/critic system for creating novel insults:

Adversarial Generation Loop:
1. Generator produces 5 candidate insults
2. Critic scores each on 5 dimensions
3. Best candidate selected if quality >= 0.6
4. If all fail, fall back to lower tier

Quality Dimensions:
┌─────────────┬────────┬──────────────────────────┐
│ Dimension   │ Weight │ Description              │
├─────────────┼────────┼──────────────────────────┤
│ Relevance   │ 0.30   │ Context match (command,  │
│             │        │ error, environment)      │
├─────────────┼────────┼──────────────────────────┤
│ Novelty     │ 0.25   │ Not used recently        │
├─────────────┼────────┼──────────────────────────┤
│ Brutality   │ 0.20   │ Matches personality      │
├─────────────┼────────┼──────────────────────────┤
│ Coherence   │ 0.15   │ Grammatically valid      │
├─────────────┼────────┼──────────────────────────┤
│ Length      │ 0.10   │ Optimal range (20-150)   │
└─────────────┴────────┴──────────────────────────┘

Example Scoring

Candidate: "Your docker build failed harder than your last deployment"

Scores:
  Relevance:  0.90  (docker context match)
  Novelty:    0.85  (first time used today)
  Brutality:  0.75  (savage personality match)
  Coherence:  1.00  (grammatically perfect)
  Length:     1.00  (55 chars, optimal range)
──────────────────────────────────────────────
  Weighted:   0.87  (> 0.6 threshold, ACCEPTED)

Contextual Vector Embeddings

32-dimensional vector space for semantic similarity:

Embedding Dimensions (32 total):
- [0-7]:   Command type (one-hot, 8 categories)
- [8-15]:  Error category (one-hot, 8 categories)
- [16-19]: Exit code features (normalized, bucketed)
- [20-23]: Time features (hour, day of week, normalized)
- [24-27]: Context features (CI, git, sudo, etc.)
- [28-31]: History features (streak, total, recency)

Similarity = cosine(context_embedding, insult_embedding)

Insult embeddings are pre-computed at startup.
Context embedding is computed on-the-fly.

Edit Distance Matcher

Uses Levenshtein distance to find similar past commands:

• Normalized distance threshold: 70%
• Adapts successful insults from similar commands
• Handles typos and minor variations

Reinforcement Learning Feedback

Tracks response effectiveness to improve selection weights:

Effectiveness Signals

• Positive: User immediately retries (engaged)
• Positive: User doesn't repeat same mistake
• Negative: User disables parrot after response
• Neutral: Long delay before next command

Weight Updates

Weight Update Rule:
w_new = w_old + α × (reward - baseline) × gradient

Where:
- α = learning rate (0.01)
- reward = effectiveness signal (+1, 0, -1)
- baseline = running average reward
- gradient = feature activation

Example:
If "git rejected you" gets positive signal for git push failures,
that insult's weight increases for git-related contexts.

Over time, the system learns which insults work best for each user's patterns.