Augments

An AI-powered command-line toolbelt I built for myself

Augments is a small set of CLI commands I built to help me get through the steady stream of YouTube videos, articles, and copy-paste research that piles up during a normal week. Each command takes one input – a URL, a clipboard, a feed – and runs it through a local LLM to give me back something I can actually use: a summary, a set of references, an outline.

Two examples of what it looks like in practice:

• Condense the four YouTube videos I bookmarked about the new Next.js App Router into ten minutes of notes I can paste into Obsidian.
• Hand it the link to a long blog post and get back a TLDR plus a list of the resources the author cited, ready to drop into my notes vault.

The full origin story is in the companion blog post: Building Augments: Cybernetic Enhancements for the Information Age.

Latest Updates

🤖 Local AI with Ollama

Run powerful language models locally through Ollama integration. Pick the model that fits the task: a small fast one for quick summaries, a larger one tuned for code when you want deeper analysis.

from augments.lib.llm import OllamaClient, ModelType

# Pick the best model for your task
client = OllamaClient(model=ModelType.CODE.value)  # Optimized for code
client.generate("Explain this function...")

# Or use environment variables for configuration
export OLLAMA_DEFAULT_MODEL=mistral  # Fast model for quick tasks

Want to see what’s happening under the hood? Turn on debug mode to see which models are loaded and which one was picked:

🔍 Debug Information:
   • OLLAMA_DEFAULT_MODEL: codellama
   • PYTHONPATH: /workspace
   
Available Models:
   • codellama    28f8fd6cdc67    4.9 GB    4 days ago
   • llama2       fe938a131f40    3.8 GB    14 months ago
   • mistral      d364aa8d131e    4.1 GB    14 months ago

🤖 Using model: codellama (Specialized for code)

🎨 Progress indicators that don’t lie

I kept losing track of whether long-running commands were stalled or just slow, so every command shows live progress. Different indicators per task, so you can see at a glance what stage you’re in:

🌒 Initializing YouTube Wisdom...
⠋ Fetching video metadata...
◐ Downloading transcript...
📽️ Processing: How to Build a Neural Network
⠋ Generating summary...
◐ Extracting key insights...
◓ Finding referenced resources...
✨ Processing complete!

Each loader is paired with the kind of work being done, so downloading, processing, and summarizing each have their own visual rhythm. Easier to glance at than a static spinner.

Bring Your Own Commands

Most of my own use of Augments is custom commands I’ve added for specific workflows. Adding a new one takes about 30 seconds:

1. Generate Your Command

One line to scaffold a new command:

./create_command.sh myNewCommand

This creates a new Python script with all the boilerplate you need:

scripts/
└── my_new_command.py  # Your new command

2. Add Your Logic

The template gives you a working command with progress tracking, an Ollama client, and the file utilities already wired up:

#!/usr/bin/env python3
"""
Command: myNewCommand
Process content your way!
"""

import argparse
from augments.lib.utils import get_desktop_path
from augments.lib.progress import track_progress, LoaderStyle
from augments.lib.llm import OllamaClient

def main():
    # Parse command line arguments
    parser = argparse.ArgumentParser()
    parser.add_argument("input", help="Content to process")
    args = parser.parse_args()

    # Process with progress indicator
    with track_progress("Processing", LoaderStyle.DOTS):
        result = process_input(args.input)

    print("✨ Done!")

if __name__ == "__main__":
    main()

3. Use Built-in Tools

The shared library covers the parts you’d write the same way every time anyway – progress, AI calls, file output:

# Show progress beautifully
with track_progress("Analyzing", LoaderStyle.PULSE):
    results = analyze_content()

# Process with AI
client = OllamaClient()
insights = client.generate("Explain this concept...")

# Save output nicely
path = get_desktop_path("analysis.md")
with open(path, "w") as f:
    f.write(format_results(insights))

4. Real Example: RSS Feed Analyzer

A real example – a command that summarizes recent posts from any RSS feed:

from augments.lib.llm import OllamaClient
from augments.lib.progress import track_progress, LoaderStyle
import feedparser

def process_feed(url: str):
    # Fetch the feed with progress indicator
    with track_progress(f"Reading {url}", LoaderStyle.DOTS):
        feed = feedparser.parse(url)
    
    # Use a fast model for quick summaries
    client = OllamaClient(model="mistral")
    summaries = []
    
    # Process recent entries
    for entry in feed.entries[:5]:
        with track_progress(f"Summarizing: {entry.title}", LoaderStyle.PULSE):
            summary = client.generate(f"TLDR: {entry.description}")
            summaries.append((entry.title, summary))
    
    return summaries

Run it with:

rssWisdom "https://example.com/feed.xml"

Get Started in Minutes

1. Clone and install:

git clone https://github.com/gfargo/augments.git
cd augments
./install.sh --shell zsh  # or bash

2. Set up your AI preferences:

# Choose your preferred AI model
export OLLAMA_DEFAULT_MODEL=codellama  # for code analysis
# or
export OLLAMA_DEFAULT_MODEL=mistral    # for quick summaries

3. Start processing content:

# Analyze a YouTube video
youtubeWisdom "https://youtube.com/watch?v=..."

# Process clipboard content
clipboardAnalyze

# Or try your own commands!
./create_command.sh myCommand

Configuration Options

Tweak the environment to match how you work:

# AI Settings
AUGMENTS_DEBUG=1              # See what's happening under the hood
OLLAMA_DEFAULT_MODEL=llama2   # Your go-to AI model
OPENAI_API_KEY=sk-...         # Optional: Use OpenAI when needed

# Output Settings
DESKTOP_PATH=/custom/path     # Where to save processed content

Contributing

Issues, ideas, and pull requests welcome:

• 🐛 Found a bug or have an idea? Open an issue on GitHub
• 💡 Want to contribute? Check out our GitHub repository
• 💬 Have questions? Join our Discord community

Screenshots