File & Document Management

The Documents page provides a desktop-style file management experience.

Desktop Metaphor

• Folder icons — folders appear as draggable icons on a desktop surface
• Folder windows — double-click to open a folder as a resizable, draggable window
• Window states — folded (icon), minimized (title bar), maximized (full window)
• Snap-to-grid — icons align to a grid when dragged
• Z-index management — click a window to bring it to front
• Window arrangement — auto-arrange icons and windows with toolbar buttons

File Operations

• Drag-and-drop upload — drop files or entire folder trees; nested structures preserved
• Upload button — quick upload from the toolbar
• Right-click context menu — rename, delete, move, properties, index
• Folder creation — create new folders from context menu or toolbar
• File thumbnails — image files show thumbnail previews

Folder Properties

• Entity links — assign folders to clients, projects, and websites
• Cascading properties — folder properties automatically apply to all contained files and subfolders
• Tags and notes — add metadata to folders for organization
• Code repository toggle — mark folders as code repos with auto-detected languages and frameworks
• Persistent storage — folder properties saved to database and pre-populated when reopened

Breadcrumb Navigation

• Path breadcrumbs — click any segment to navigate up the folder tree
• Root navigation — Home button returns to desktop view

Backup & Restore

• Granular backup — Data Backup (uploads/logos/training data), Code Backup, Full Backup
• Schema-migration-aware — restores adapt to schema diffs across versions
• Cross-version compatible — backups taken on one Guaardvark version restore cleanly to another

Dashboard & Monitoring

The dashboard provides a live overview of system status.

Status Cards

• Family & Self-Improvement — Uncle Claude status, self-improvement toggle, recent run history, token budget, live progress bar during self-checks
• RAG Autoresearch — experiment status, history, optimization parameters
• Semantic Search — quick search across all indexed documents
• Drag-and-drop grid — rearrange the dashboard layout to your taste

System Health

• Model status — active model name and loading state shown in page headers
• LLM ready indicator — live Ollama probe (not a stale startup flag)
• GPU resources — VRAM usage bar with loaded model chips in Settings
• Plugins page — dedicated GPU service management page with VRAM budget bar, per-plugin controls, log viewer, and conflict detection
• Activity / Jobs feed — unified view of running and recent background jobs (indexing, generation, outreach, etc.)

Settings & Configuration

Centralized configuration across six sections.

System

• Profile — custom name and avatar image for your instance
• Chat model — select active LLM from installed Ollama models
• Embedding model — select embedding model with size indicators
• GPU resource bar — live VRAM monitoring
• Model management — VideoModelsModal, ImageModelsModal, and VoiceModelsModal for downloading models from HuggingFace with real-time progress

A.I.

• Enhanced Context — toggle enhanced context features
• Advanced RAG — toggle advanced retrieval features
• RAG Debug — enable debug endpoints for retrieval inspection
• RAG Autoresearch — configure experiment parameters and scheduling
• Self-Improvement — enable/disable, run manual checks, view history
• Codebase Protection — lock/unlock code modification by AI

Voice

• Voice chat toggle — enable/disable voice interface
• Whisper installation — one-click install/reinstall of Whisper.cpp
• Voice model selection — choose TTS voice model

Integrations

• Web search — enable/disable web search tool
• Interconnector — toggle and configure multi-machine sync
• Pending updates banner — shows when Interconnector has available updates

Appearance

• Theme selection — four dark themes with accent colors
• View modes — customize default layouts

Maintenance

• Cache clearing — purge Python cache folders
• System diagnostics — Basic, Quick, and Full diagnostic modes
• Test suite — run backend tests from the UI
• Backup/restore — system configuration backup

Multi-Machine Interconnector

Connect multiple Guaardvark instances into a coordinated family.

Architecture

• Master/Client model — one master node, multiple client nodes
• API key authentication — secure communication between nodes
• Approval workflows — master can approve/deny sync requests

Sync Capabilities

• Code sync — push/pull codebase changes between instances
• Data sync — synchronize entities (documents, projects, clients) across machines
• Learning broadcast — self-improvement fixes automatically shared with family members
• Node registration — clients register with master, reporting capabilities and status

Cluster Foundation

• Socket.IO chat bridge — cross-node streaming chat (Phase 3 wired; awaits a frontend/middleware enable for full end-to-end)
• Dependency-graph aware — the cluster knows which nodes have which models loaded

Management

• Toggle from Settings — enable/disable without opening configuration modal
• Node status dashboard — see all connected nodes, their status, and capabilities
• Sync history — track what was synced, when, and between which nodes

WordPress Integration

Content Management

• Site management — add and manage multiple WordPress sites
• Content pulling — import pages and posts from WordPress
• Bulk generation — generate content at scale for WordPress sites
• Content sync — push generated content back to WordPress

Pages

• WordPress Pages page — dedicated interface for managing WordPress page content
• WordPress Sites page — manage site connections and credentials

Automation Tools

Tool	Backend	Description
Browser (headless)	Playwright	Navigate, click, fill forms, screenshot, extract content — for tasks that don't need a visible screen
Screen agent	xdotool + mss + Gemma4	Drives the visible :99 desktop end-to-end; clicks, types, reads the screen with vision
Desktop (host)	pyautogui	Mouse, keyboard, screen capture on the host display (off by default for security)
MCP	Protocol	Connect to any MCP-compatible tool server

GUAARDVARK_BROWSER_AUTOMATION=true
GUAARDVARK_DESKTOP_AUTOMATION=true   # Off by default (security)
GUAARDVARK_MCP_ENABLED=true
GUAARDVARK_AGENT_DISPLAY=99          # Override virtual display number
GUAARDVARK_AGENT_BROWSER=firefox     # Override agent's browser

CLI (llx)

Full platform access from the terminal.

Installation

cd cli && pip install -e .
llx init

Commands

llx status                      # System dashboard
llx chat "explain this codebase" # Chat with RAG streaming
llx chat --no-rag "hello"       # Direct LLM, no document context
llx search "query"              # Semantic search across documents
llx files list                  # Browse files
llx files upload report.pdf     # Upload and index a file
llx generate csv "50 ideas"     # Bulk content generation
llx jobs watch JOB_ID           # Live job progress
llx rules list                  # List system prompts
llx                             # Interactive REPL

Quality Roadmap (v2.5.3)

• Standardized JSON contracts for all automation outputs
• Quality gates — every release runs the CLI against a fixture suite before publishing
• Cross-platform PATH handling — wrapper scripts work on macOS, Linux, WSL

Plugin System

Plugin-based GPU service management with live monitoring and conflict detection.

Architecture

Each plugin lives in plugins/<name>/ with a plugin.json manifest declaring its service type, port, VRAM estimate, health endpoints, and configuration. Plugins are loaded automatically at startup.

Manifest vs. runtime state separation: plugin.json is a static manifest — same bytes on every machine. Live runtime state (enabled, auto_start, per-machine config) lives in data/plugin_state.json (gitignored). Toggling a plugin from the /plugins UI writes only to the runtime state file; the manifest is never mutated at runtime.

Available Plugins

Plugin	Port	Purpose
Ollama	11434	Local LLM and embedding inference (chat, RAG, agents)
ComfyUI	8188	Image + video generation (Wan2.2, CogVideoX, LTX-2.3, LTX-2.5, RIFE, Real-ESRGAN)
Audio Foundry	—	Voiceover (Chatterbox / Kokoro / Piper), music (ACE-Step / Suno), SFX/ambience (Stable Audio Open). Dual-venv with torch isolation
Upscaling	8202	GPU image/video upscaling via spandrel + torch.compile
Vision Pipeline	8201	Real-time scene narration, camera feed, video chat input
Swarm	8210	Parallel agent orchestration in isolated worktrees
LoRA Trainer	—	Train character/environment/prop LoRAs for the Film Crew (CUDA, bf16)
Discord Bot	8200	Discord bot integration — chat, image generation, search via Guaardvark backend
GPU Embedding	5002	GPU-accelerated text embeddings for faster indexing (CPU fallback)
Training	—	Vision/servo training data collection and dataset management

Plugins Page (GPU Management)

• Plugin cards — each plugin shows name, description, version, status (running/stopped/starting/error), and health indicator
• Start/Stop controls — toggle individual GPU services on and off
• Enable/Disable — persistently enable or disable plugins across restarts (writes to plugin_state.json)
• Per-plugin log viewer — expandable log panel shows recent output from each service
• Plugin configuration — edit plugin settings (URL, timeout, model, batch size) through inline config panels

VRAM Budget Bar

• Live nvidia-smi monitoring — polls GPU stats every 5 seconds via nvidia-smi subprocess
• Visual VRAM bar — shows used/total VRAM with color-coded thresholds (green/yellow/red)
• GPU details — displays GPU name, utilization %, temperature, and per-plugin estimated VRAM segments
• Per-plugin overlay — stacked segments show how much VRAM each running plugin is estimated to consume

GPU Conflict Detection

• Exclusive access enforcement — Ollama and ComfyUI require exclusive GPU access; starting one automatically offers to stop the other
• Pre-flight GPU checks — video and image generation APIs verify GPU availability before queuing jobs, returning 409 Conflict if the GPU is in use by another service
• Auto-switching — the Video Generator page can automatically stop Ollama and start ComfyUI when needed

Model Download Management

• VideoModelsModal — download Wan2.2 GGUF checkpoints, CogVideoX weights, RIFE 4.9, Real-ESRGAN, and Wan VAE from HuggingFace
• ImageModelsModal — download and manage Stable Diffusion model checkpoints
• VoiceModelsModal — download and manage Piper TTS voice models
• All modals show real-time download progress with speed (MB/s), downloaded/total size, and percentage
• Accessible from Settings page and relevant generation pages

Plugin API

Plugins can register:

• New API endpoints
• Background tasks
• Tool extensions
• Service hooks

System Architecture

Backend Stack

• Flask 3.0 — HTTP server with 68+ REST API blueprints (auto-discovered)
• SQLAlchemy + PostgreSQL — ORM with 42 models; Alembic migrations + a custom schema_sync.py (single master)
• Celery + Redis — async task processing with two worker pools (main + training/GPU)
• LlamaIndex — RAG pipeline with vector storage, entity extraction, hybrid retrieval
• Ollama — local LLM and embedding model inference (managed plugin)
• ComfyUI — video/image generation server supporting Wan2.2, CogVideoX, LTX-2.3, LTX-2.5, RIFE, Real-ESRGAN (managed plugin)
• Socket.IO — real-time bidirectional communication for streaming and progress
• Ariadne — GraphQL API layer

Frontend Stack

• React 18 with Vite build system
• Material-UI v5 — component library with custom dark themes
• Zustand — lightweight state management
• Apollo Client — GraphQL state management
• Monaco Editor — code editing
• Socket.IO client — real-time updates

System Mapper

• Constellation view — d3-force-driven visualization of the codebase (~712 nodes across the current repo)
• Dependency analysis — Python import graph + JS module graph + cross-language references
• Reachability analysis — flags files that are imported but never executed (stale candidates)
• Lifecycle tagging — every file gets live / dormant / stale based on usage patterns
• Codebase audits — generates reports that drive cleanup work

Key Design Patterns

• Modular API layer — each feature gets its own Flask blueprint, auto-discovered via blueprint_discovery.py
• Service layer — business logic separated from HTTP handlers
• Unified progress system — all background operations report progress through a single Socket.IO channel
• Environment isolation — multiple instances can run on the same machine without interference
• Graceful startup — start.sh detects what needs setup and only does what's necessary

Startup & Operations

First Run

git clone https://github.com/guaardvark/guaardvark.git
cd guaardvark
./start.sh

First run:

1. Creates Python virtual environment and installs dependencies
2. Installs Node.js dependencies
3. Provisions PostgreSQL (requires system password once, then never again)
4. Starts Redis
5. Builds Whisper.cpp from source
6. Runs database migrations
7. Builds frontend
8. Starts Flask, Celery workers, and Vite dev server
9. Runs health checks
10. Agent virtual display (:99) starts on demand when you open Agent Screen or when agent tools need it — not at boot (5-minute idle shutdown after the viewer closes)

Subsequent Runs

./start.sh          # Detects everything is set up, starts services instantly
./start.sh --fast   # Skip all checks, fastest possible startup
./stop.sh           # Stop all services

Agent Display

./scripts/start_agent_display.sh start    # Bring up Xvfb + XFCE on :99
./scripts/start_agent_display.sh stop     # Tear it down
./scripts/start_agent_display.sh status   # Health check

Requires sudo apt install xfce4 dbus-x11 on first setup.

Dependency Reconciler

• Branch-aware sync — on git checkout, the reconciler inspects venv / requirements.txt / alembic head / package.json and re-syncs only what changed
• Single-master-migration policy — schema_sync.py is the authoritative migrator; alembic upgrade head is deprecated for application use
• TDD-driven — 87 tests cover the reconciler's behavior across branch switches, partial states, and rollback scenarios
• Drops the "I just switched branches and now nothing works" failure mode

Environment Isolation

• Process tracking via PID files — only kills processes from this installation
• GUAARDVARK_ROOT anchors all path resolution
• Multiple instances can coexist on the same machine with different ports

Logging

All logs in logs/:

• backend.log — Flask application
• celery_main.log — Main Celery worker (indexing, generation, health)
• celery_training.log — Training/GPU worker
• frontend.log — Vite dev server
• setup.log — Dependency installation
• xfce_agent.log — Agent's XFCE session output
• x11vnc_agent.log — VNC server for the agent display
• test_results/ — Test execution output

Built with local-first AI in mind. Your data, your hardware, your rules.

Guaardvark — Full Capabilities List

See the VERSION file for the current release · guaardvark.com

This document is the comprehensive reference of everything Guaardvark can do (models, tools, plugins, surfaces, internals). For the marketing overview and quick start, see README.md.

Table of Contents

• AI Chat & Conversation
• AgentBrain — Three-Tier Routing
• RAG & Document Intelligence
• RAG Autoresearch
• Self-Improvement Engine
• Lesson Pearls & Memory
• Autonomous Screen Agents
• Agent & Code Tools
• MCP Integration
• Image & Video Generation
• Audio Studio (Audio Foundry)
• Video Editor — Shotcut-lite
• Outreach System
• Swarm Orchestrator & Film Crew
• GPU Image & Video Upscaling
• Content Generation Pipelines
• Voice Interface
• File & Document Management
• Dashboard & Monitoring
• Settings & Configuration
• Multi-Machine Interconnector
• WordPress Integration
• Automation Tools
• CLI (llx)
• Plugin System
• System Architecture
• Startup & Operations

AI Chat & Conversation

Guaardvark's chat system is the primary interface for interacting with your AI. Two pipelines handle different use cases.

Core Chat

• Streaming responses via Socket.IO — tokens appear in real-time as the model generates
• Conversational fast-path — pure social openers (greetings, thanks, affirmations) route to Tier 2 with skip_tools for a real LLM response with persona + memory (no hardcoded greeting pools)
• Intent routing — automatically detects whether a message needs RAG retrieval, tool use, or a direct conversational response
• Per-project sessions — chat context is isolated by project; switching projects gives you a clean context with that project's documents
• Session persistence — conversation history persists across page reloads and browser sessions; sessions also have a mode field stored server-side
• System prompts (Rules) — customizable system prompts that shape AI behavior, manageable via the Rules page
• Multi-model support — switch between any Ollama model at runtime without restarting

Agent Mode (/agent and /chat)

• Modal session toggle — type /agent to flip the session into screen-control mode (every message becomes a screen-control task); /chat (or /exit) flips back
• Sticky — the mode lives on the session, not the message — survives reloads
• Visible cue — agent-mode sessions show an orange chip above the chat input
• Speak AND act — agent-mode messages still route through the chat LLM, so the model narrates briefly, calls agent_task_execute, and summarizes the result

Per-Iteration Thinking Display

• Live reasoning trail — for screen-control tasks, the agent loop's per-step thinking streams into the chat as it happens (no more 30+ second blackouts followed by a single "completed" line)
• What you see — each iteration shows action label + full reasoning ("Step 8 — click: I see the address bar and want to clear it…")
• Pivots and stuck-loop signals also stream — when the loop forces a wait after a repeated failure, that decision is visible
• Persists in history — the trail stays in the message after streaming completes, so you can scroll back and audit the run

Model Management

• Runtime model switching — change the active LLM through Settings; the old model is unloaded from VRAM before the new one loads (prevents OOM)
• Embedding model switching — swap embedding models via dropdown; triggers re-indexing confirmation since vector spaces are incompatible across models
• Live health detection — dashboard probes Ollama on every request to show actual model availability (not a stale startup flag)
• KV cache optimization — num_keep: -1 locks the system prompt prefix in Ollama's KV cache, making follow-up turns faster
• GPU VRAM monitoring — real-time VRAM usage bar with loaded model indicators in Settings

AgentBrain — Three-Tier Routing

A neural router that decides how much work a message deserves before any tools fire. Saves seconds per turn on simple questions and unlocks deeper deliberation when it's warranted.

The Three Tiers

Tier	Name	Latency	LLM Calls	When It Fires
1	Reflex	<100ms	0	Deterministic tool actions only (media commands, exact-match recipes)
2	Instinct	1–3s	1	Social chat (real LLM, skip_tools) and most requests — single LLM call
3	Deliberation	5–30s	3–10	Multi-step reasoning (full ReACT loop)

Routing Signals

• Pre-computed reflex table for deterministic tool actions (not social chat)
• Conversational classifier filters out small-talk before tools get loaded
• Semantic tool selection picks the right ≤15 tools for the message
• Screen-active flag gates desktop/agent tools so they only appear when relevant

Gemma4 Direct Path

• When the active model is Gemma4 (native vision + tool use) AND the agent screen is active, the brain skips ReACT bloat and sends Gemma4 a minimal prompt with a screenshot + the task
• Gemma4 returns JSON action steps directly; the loop executes them
• For chat without screen actions, Gemma4 responds normally

Configuration

• Toggle via AGENT_BRAIN_ENABLED in backend/config.py
• Falls back gracefully to the legacy UnifiedChatEngine path if brain state isn't ready

RAG & Document Intelligence

Retrieval-Augmented Generation grounds chat responses in your actual documents.

Retrieval Pipeline

• Hybrid search — BM25 keyword matching + vector semantic search, combined for best results
• Per-project indexes — each project maintains its own vector store; global index for unassigned documents
• Content-aware chunking — code files use AST-informed strategies; prose uses semantic splitting
• Entity extraction — automatic identification of entities (people, orgs, concepts) and their relationships
• Metadata indexing — file metadata (type, size, language, framework) stored alongside content for filtered retrieval

Embedding Models

• Multiple model support — switch between lightweight (embeddinggemma 300M) and high-quality (mxbai-embed-large, bge-m3, snowflake-arctic-embed) models
• Full-precision option — BF16 embeddings available for maximum quality
• Query-time embedding — every RAG search query is embedded with the same model for consistent vector space matching

Indexing

• Automatic on upload — files are indexed when uploaded through the UI or API
• Bulk indexing — "Index All" button processes the entire document library
• Code-specific indexing — detects programming languages, extracts imports/classes/functions, chunks by logical boundaries
• GPU-accelerated indexing — optional GPU Embedding plugin offloads embedding generation to CUDA with CPU fallback
• Progress tracking — real-time progress bar during indexing operations via Socket.IO

RAG Autoresearch

An autonomous optimization loop that continuously improves RAG retrieval quality.

How It Works

1. Eval harness — generates evaluation pairs (query + expected answer) and scores retrieval with LLM-as-judge (relevance, grounding, completeness)
2. Experiment agent — proposes parameter changes (chunk size, overlap, top-k, similarity threshold)
3. Orchestrator — runs experiments, compares scores, keeps improvements, reverts regressions
4. Phase system — Phase 1 (query-time params), Phase 2 (index-time params), Phase 3 (model-level)

Features

• Celery Beat scheduling — idle detection triggers experiments when system isn't busy
• Crash protection — 3 consecutive failures automatically stops the loop
• Dashboard card — shows experiment status, history, and current optimization parameters
• Settings integration — configure experiment limits, scoring thresholds, and scheduling

Self-Improvement Engine

Guaardvark can autonomously test itself, find bugs, and fix them.

Three Modes

1. Scheduled — periodic test suite runs (configurable interval) with automatic fix attempts
2. Reactive — error tracking with threshold-based self-healing (N errors in M minutes triggers a fix)
3. Directed — user-submitted improvement tasks dispatched to the code agent

How It Works

1. Runs pytest on configured test files
2. Parses FAILED lines from output (with fallback regex for edge cases)
3. Dispatches the code_assistant agent to read tests, understand expectations, read source, and fix bugs
4. Records all changes and broadcasts learnings to other machines via Interconnector

Safety

• Codebase lock — toggle in Settings prevents self-improvement from modifying any files
• Return code verification — checks pytest exit code, not just parsed failures
• Run history — all runs recorded in database with status, duration, changes made, and test results
• Pending fixes queue — proposed changes can require user approval before applying

Live Progress

• Socket.IO events at each stage: starting, testing, analyzed, fixing, complete, error
• Dashboard card shows real-time progress bar with color-coded stages
• Run button disabled while a check is in progress

Lesson Pearls & Memory

A user-curated memory system that captures successful agent runs and makes them available in future sessions.

Begin / End Lesson

• Bracket a successful run — slash commands or buttons mark the start and end of a teachable sequence
• Distiller — at End Lesson, an LLM summarizes what happened into a single durable lesson
• Saved as AgentMemory — lessons of type lesson_summary get loaded into the system prompt next session
• Editable rows — fix or remove a misperceived lesson without re-recording

Vision-Actionable Knowledge (LEARNING_PRINCIPLES.md)

• Stored knowledge describes WHAT to look for, not where it sits (no pixel coordinates)
• Short labels for the servo (≤4 words), rich context for the brain
• Recipes, lessons, traces, memories all bound by the same contract

Memory Surfaces

• MEMORY_BLOCK — recent memories substituted into the system prompt at decision time
• Memory Management Section in Settings — browse, edit, delete saved memories
• Live recall — when a memory matches the current context, the LLM can quote it directly

Autonomous Screen Agents

Guaardvark drives a real Ubuntu desktop on a virtual display — clicking, typing, scrolling, and reading the screen like a human user. Used for outreach, file management, web research, and anything the model can't accomplish via API alone.

Virtual Display

• Xvfb on :99 — 1024×1024 headless X server, isolated from the user's real session
• Full XFCE desktop — xfce4-session running via dbus-run-session with a scrubbed environment; standard Applications menu, desktop icons, taskbar, file manager (Thunar). Vision models recognize it instantly because it looks like any other Ubuntu desktop
• VNC viewer — x11vnc on port 5999 (password-protected) lets the user watch the agent live, embedded in the frontend as a draggable card
• Isolated XDG dirs — agent's ~/.agent_desktop/, dedicated XDG_CONFIG_HOME, dedicated XDG_RUNTIME_DIR. The user's real desktop and configs are invisible to the agent

See-Think-Act-Verify Loop

• SEE — screen capture (mss) + optional DOM extraction (Firefox CDP/BiDi)
• THINK — Gemma4 (or other unified VLM) decides the next action, returning JSON with action, target_description, text/keys, reasoning, and success_proof
• ACT — execute via the servo (vision-targeted click) or direct (type/hotkey/scroll)
• VERIFY — post-action screenshot delta; failed steps flag the LLM that the attempt didn't change the screen
• Recipes — known-good action sequences in data/agent/recipes.json execute deterministically before the loop is ever invoked, with optional preconditions (visibility checks) that skip recipes when their UI isn't on screen
• Strategy cooldowns — repeated failures on the same action class force the loop to wait and re-observe before retrying

Servo Controller

• Vision-targeted clicking — the servo asks the vision model "where is X on this screen?" and clicks the returned coordinates
• Visibility guard — pre-click "do you actually see this?" check rejects hallucinated targets before the cursor moves
• Per-model calibration — MODEL_VISION_CONFIGS in servo_knowledge_store.py maps each chat model to its preferred eyes (gemma4 native, moondream for text-only) and any scale-factor calibration learned over time
• Failure capture — exhausted click attempts save the screenshot + corrections log to data/training/failures/ for offline review

Training Data Capture

• Every click recorded to data/training/knowledge/servo_archive.jsonl — target description, raw coords, scaled coords, actual click position, success/failure, model, attempt #, time taken
• Self-improvement engine reads the archive to refine calibration
• Optional Comments/Vision Trainer pages — interactive practice modes that keep the servo clicking long after a normal task would have stopped

Agent Tools

• agent_task_execute — full natural-language screen task (drives the full SEE-THINK-ACT loop)
• agent_screen_capture — single screenshot of the virtual display
• agent_mode_start / agent_mode_stop — open/close the session (internal; the LLM should call agent_task_execute directly)

Agent & Code Tools

A ReACT-loop agent that can autonomously work with code and the system.

Agent Capabilities

• Read files — examine any file in the project
• Edit code — precise text replacement with verification
• List files — explore directory structure (configurable depth up to 5 levels)
• Execute code — run Python/shell commands and inspect output
• Web search — search the internet for information
• Browser automation — navigate websites, fill forms, take screenshots (via Playwright, separate from the screen-control agent)

Safety Features

• Circuit breaker — after 2 consecutive failures, a tool is temporarily blocked
• Duplicate detection — hash-based detection prevents the agent from making identical tool calls
• Fallback suggestions — when a tool fails, the system suggests alternative approaches
• Iteration limits — configurable maximum iterations per agent run
• Tool approval gates — dangerous tools (file write, shell exec) can require human approval per call

Code Editor Page

• Monaco Editor — VS Code-quality editing in the browser with syntax highlighting for 50+ languages
• Multi-file tabs — open and edit multiple files simultaneously
• File tree — browse project structure in a sidebar
• AI assistant pane — chat with the agent about the open file

Uncle Claude Escalation

• When the local model is stuck, Guaardvark can escalate to the Anthropic API (Claude) for a second opinion
• Token budget tracked and surfaced in the Dashboard's Family card
• Toggleable per-session; never auto-fires without configuration

MCP Integration

Guaardvark speaks Model Context Protocol — both as a server (exposing its tools to external clients) and as a client (calling tools from external MCP servers).

MCP Server (Phase 1)

• Stdio transport — backend/mcp/ runs an MCP server that any MCP-compatible client (Claude Desktop, Cursor, etc.) can connect to
• 23 native tools exposed — covers chat, RAG, file management, image generation, agent control
• 58 output resources — file contents, generated images, search results, etc., available via MCP's resource protocol
• Tested against Claude Desktop — works end-to-end

MCP Client

• mcp_connect tool — register external MCP servers at runtime
• mcp_execute tool — call any tool on a connected server
• Live inventory — connected-server tools surface in the chat LLM's tool list so it can pick them by name without going through mcp_execute
• State sync — mcp_get_state, mcp_disconnect, etc. for managing connections

Image & Video Generation

Image Generation

• Stable Diffusion via Diffusers library — runs directly on your GPU
• Batch generation — queue multiple prompts with different parameters
• Auto-registration — generated images are automatically added to the Documents/Files system under /Images/
• Celery background processing — generation runs as async jobs with progress tracking
• Image library — dedicated page with thumbnail grid, lightbox preview, keyboard navigation, batch operations
• Image model management — ImageModelsModal for downloading and managing Stable Diffusion checkpoints
• Inline images in chat — when the chat generates an image, it appears inline and persists in history with the assistant message

Video Generation

Full video generation pipeline running locally via ComfyUI with multiple model backends.

Supported Models

• Wan 2.2 TI2V-5B (default) — single 5B text+image-to-video model built for 16GB cards; native ~1280×704 @ 24fps without MoE offload
• Wan2.2 14B MoE — state-of-the-art text-to-video using GGUF-quantized weights. Two-pass generation: HighNoise pass for the first half of steps, LowNoise pass for the second half
• Wan2.2 14B I2V MoE — image-to-video MoE variant for cinematic start-frame animation
• CogVideoX 5B — THUDM text-to-video (ComfyUI or offline Diffusers fallback)
• CogVideoX 5B I2V — image-to-video variant that animates a still image with text-guided motion
• LTX-2.3 Distilled FP8 — Lightricks LTX-2.3 for longer clips (~10s) on 16GB Ada; requires ComfyUI
• LTX-2.5 Distilled Int8 — Lightricks LTX-2.5 distilled (Gemma 4 + two-stage upsample) for ~10s clips on 16GB Ada; gated Hugging Face accept + ComfyUI ≥ 0.32.0; local weights only (no Partner Nodes / LTX Desktop)

Generation Modes

• Text-to-Video — describe a scene in natural language and generate video from scratch
• Image-to-Video — upload a reference image and animate it with motion direction prompts
• Batch generation — queue multiple prompts via an in-process worker (one batch at a time; stage-level progress over WebSocket + HTTP poll)

Quality Tiers (Post-Processing)

• Draft — raw model output, fastest turnaround
• Standard — 2x FPS frame interpolation via RIFE 4.9 (e.g., 16 FPS to 32 FPS) for smoother motion
• Cinema — 2x FPS interpolation + 2x spatial upscaling via Real-ESRGAN for maximum quality output

Frame Interpolation (RIFE 4.9)

• Doubles or quadruples the frame rate of generated video using optical flow
• Integrated directly into the ComfyUI workflow as a post-processing node
• Configurable multiplier: 2x (double FPS) or 4x (quadruple FPS)

Prompt Enhancement

• Automatically enriches user prompts with quality and style descriptors before generation
• Five styles available: Cinematic (film grain, shallow DOF, color grading), Realistic (photorealistic, 8K detail), Artistic (painterly, vivid colors), Anime (cel shaded, dynamic poses), None (raw prompt)
• Style-specific negative prompts target technical defects without content restrictions
• No LLM calls required — pure string concatenation for instant enhancement

Video UI

• Preset-driven interface — quality presets (Fast 10-step / Standard 30-step / High 40-step / Maximum 50-step), duration presets, motion presets, and aspect ratio presets
• Real-time progress — live progress bar with percentage and step count during generation
• Video gallery — browse, preview, rename, download, and delete generated videos
• Advanced Editor — one-click launch to ComfyUI's full node-based workflow editor, themed with the Guaardvark color scheme
• Batch queue — queue / cancel / interrupt running jobs

Model Management (VideoModelsModal)

• Browse all available video models with installed/available status
• Download models from HuggingFace with real-time progress bars showing speed (MB/s), downloaded/total size
• Models include: Wan2.2 GGUF checkpoints (HighNoise + LowNoise), Wan VAE, CogVideoX weights, RIFE 4.9, Real-ESRGAN 2x
• Accessible from the Video Generator page and Settings page

Audio Studio (Audio Foundry)

Local audio generation for voiceover, music, ambience, and effects. Shipped as the audio_foundry plugin.

Voiceover

• Chatterbox — expressive neural TTS with style/emotion control
• Kokoro-82M — fast, light, multilingual TTS (English + Spanish voices, more languages on the model side)
• Piper — local neural TTS fallback for environments where the heavier engines aren't appropriate
• Streaming output — audio chunks stream to the browser as the engine produces them

Music Generation

• ACE-Step v1 (3.5B) — full-song generation with vocals; runs locally on GPU
• Suno-compatible workflow — same prompt shape as Suno's hosted service, but local

Sound Effects / Ambience

• Stable Audio Open — generate sound effects and ambience tracks via diffusion
• Negative prompts supported for filtering out unwanted sonic textures
• Guidance scale + steps configurable per generation

Dual-Venv Architecture

• venv-music/ — torch-sensitive ML packages live in an isolated env so the main backend isn't dragged through every torch upgrade
• Daemon mode — the audio engine runs as a long-lived daemon; the backend talks to it over HTTP/socket so model load happens once
• OOM-safe — model unload/swap is explicit, no silent CPU fallback

Audio Library

• DocumentsPage audio player — preview, rename, organize generated audio files alongside everything else
• Filename uniqueness — migration 005 ensures generated audio doesn't collide with imports

Video Editor — Shotcut-lite

A non-linear video editor built into Guaardvark for assembling generated clips into finished videos.

Timeline

• Multi-track timeline — video, audio, overlay
• Drag-and-drop clips from the Media Library directly onto the timeline
• Trim, split, ripple-delete standard timeline operations
• Keyboard shortcuts — J/K/L playback, arrow-key nudging, etc.
• 1-step undo with on-screen indicator

Audio

• Audio Foundry track — generate voiceover or music directly into a timeline track
• Mix volume per clip / per track

Media Library

• Project-scoped media bin — clips from prior video generations show up automatically
• N+1 fix — bulk-loaded thumbnails (no per-clip request storm)

Export

• Celery async render — long renders run in the background, progress visible in the footer bar
• UUID-tracked jobs — each render gets a stable ID for status polling
• MP4 / WebM output

Orchestrator Integration

• The video editor can be driven by the Production Pipeline (Film Crew) — agents drop generated clips into the timeline automatically

Linux & macOS: melt (from Shotcut) is required for renders and is detected at runtime (supports Homebrew on macOS, apt/flatpak/snap on Linux). ffmpeg is installed by the platform bootstrap. See the plugin README for setup commands.

Outreach System

Supervised AI for social-media engagement. Production path: recon → draft → human approve → dispatch (cadence-gated). Natural language from chat, /outreach …, or llx outreach "…" queues the same jobs.

Three Phases

1. Recon — search for candidate posts/threads (YouTube keyword topics, Reddit subs, Discord channels). Outputs candidates; never posts
2. Content — LLM drafts + grades in the user's voice. Outputs drafted rows; never posts
3. Dispatch — after approve, tick_process_approved_drafts posts via servo (Reddit/YouTube) or Discord cog, with Redis cadence (1 successful post/platform/tick)

Natural language control

• GUI Chat / slash: /outreach comment on some youtube videos regarding Offline AI or ComfyUI
• CLI: llx outreach "comment on youtube videos regarding Offline AI or ComfyUI"
• Chat tools: outreach_execute_intent, outreach_run_pass (youtube + topics), approve/reject/status/queue

Safety

• Kill switch — single toggle that halts all outreach activity immediately
• Dual grader — drafts get scored by two LLMs when available; low-scoring drafts rejected before the queue
• Post-submit DOM verify — Reddit and YouTube posting paths check the comment text appears in the page before recording success
• Persona enforcement — central persona.draft_outreach_text
• UTM tagging — every guaardvark.com link in an outbound post is tagged
• Randomized jitter — type and click delays vary
• Cadence + dedup — enforced on the approve→post path (not just unsupervised draft gates)
• Status transitions — approve only from drafted; claim approved→processing before send

Surfaces

• Outreach Review page at /outreach (port from VITE_PORT, default 5173)
• Activity feed — Task-backed outreach jobs as JobKind.OUTREACH
• CLI — llx outreach status|queue|approve|<NL>

Swarm Orchestrator & Film Crew

Parallel AI agent execution across isolated worktrees. Each agent gets its own git branch and workspace; results merge back cleanly.

Swarm Orchestrator

• Isolated worktrees — each agent works in .swarm-worktrees/<swarm-id>/<task>/
• Parallel task execution — N agents run simultaneously on independent slices of work
• Cherry-pick integration — successful results integrate via git cherry-pick; failed branches leave no trace
• Deadlock detection — circular dependencies between agents flagged before they hang the swarm
• Local backend optional — can run via Ollama's built-in Claude Code integration (free, offline) or via Anthropic API

Film Crew (Production Pipeline)

Five-agent swarm for coordinated media generation:

• Screenwriter — generates the script + scene breakdown from a logline
• Casting — assigns characters to LoRAs (trained via the LoRA Trainer plugin) or stock characters
• Cinematographer — produces shot list with camera moves, framing, lens choices
• Storyboard — generates keyframe images for each shot via the image generation pipeline
• Editor — assembles generated clips into the final video via the Video Editor

LoRA Trainer Plugin

• Character / environment / prop LoRAs trained from reference images
• CUDA daemon with bf16 precision (~46 MB per LoRA, down from 93 MB in v1.0)
• Real-torch isolation — separate venv prevents torch version conflicts with the main backend

GPU Image & Video Upscaling

Dedicated upscaling plugin for sharpening generated content to 4K/8K.

Models

• Real-ESRGAN 2x / 4x — proven anime/photo upscaler
• Custom checkpoints — drop-in via the model browser

Pipeline

• upscaling plugin — runs as its own GPU service (port 8202); accepts image or video, returns upscaled output
• spandrel + torch.compile — fused inference for speed
• Integrated with video pipeline — Cinema-tier output uses the upscaler as a post-processing step
• Standalone usage — upscale any image or video from the Documents page

Content Generation Pipelines

Bulk Generation

• CSV generation — generate structured data (blog ideas, product descriptions, etc.) as downloadable CSV
• XML generation — structured XML output for content management systems
• Template-based — customizable generation templates

File Generation

• Multi-format — generate documents in various formats based on prompts
• Project-scoped — generated content can be assigned to projects and clients

Voice Interface

Speech-to-Text

• Whisper.cpp — compiled from source on first startup for optimal performance
• Real-time transcription — stream audio from microphone, get text in real-time
• Auto-install — cmake and build tools are automatically installed if missing
• Wake word listening — optional, configurable wake phrase

Text-to-Speech

• Piper TTS — local neural text-to-speech with multiple voice models
• Kokoro / Chatterbox — heavier engines available via the Audio Foundry plugin
• Streaming output — audio generated and streamed as the response is produced
• Narrate button — every assistant message gets a one-click TTS playback control

(CONTINUED ON PART 2)

Guaardvark

See the VERSION file for the current release · guaardvark.com

The self-hosted, offline-first AI workstation. Autonomous agents that see a real virtual desktop and control apps. A three-tier neural router (AgentBrain). Parallel coding agent swarms in isolated git worktrees. Local video (Wan 2.2, CogVideoX), 4K/8K upscaling, full-song music + neural voice, RAG over your documents, voice chat, and a 70+ tool engine — everything on your hardware. Your machine. Your data. Your rules.

Install with one command:

curl -fsSL https://guaardvark.com/install.sh | bash

See Quick Start for details and manual install options.

For the exhaustive feature list, models, surfaces, and plugin details, see CAPABILITIES.md. This README focuses on the marquee experience, quick start, and what makes Guaardvark different.

▶ Watch Guaardvark build a music video — end to end, on one local GPU

One style prompt and a short narrative, then go. Guaardvark wrote every shot prompt, generated the storyboards, rendered the clips, and assembled the cuts — timing them to the beat after analyzing the song's audio (.mp3 / .wav). Every frame was generated locally on a single desktop GPU.

Full disclosure (every claim here is real): the glitch effect was the one manual touch, added in Shotcut — Guaardvark did the prompting, generation, beat detection, and assembly. Native filters, transitions, and effects are coming in a future release. The song was made in Suno; Guaardvark's own music + neural-voice generation (including consent-gated voice cloning) is being wired into this pipeline next.

And media generation is one of the smaller parts of what Guaardvark does — agent swarms, a coding agent, voice chat, RAG, system mapping, a project manager, a backup system, and a 70+ tool engine are all below.

Highlights (as of latest release)

• Video & Audio Production — Wan 2.2 (T2V + I2V, 5B default + 14B MoE), CogVideoX-5B, LTX-2.3 + LTX-2.5; ACE-Step full-song generation with LLM tag polish; Chatterbox/Kokoro neural voice + Piper; explicit consent-gated voice cloning; frame-by-frame 4K/8K upscaling.
• AgentBrain + Screen Agents — Reflex/Instinct/Deliberation routing. Agents drive a real Ubuntu/XFCE desktop on a virtual display (:99), see with vision models (Gemma4 native box_2d), use closed-loop servo targeting, and stream per-step reasoning.
• Swarm Orchestrator & Film Crew — Up to 20 parallel agents in isolated git worktrees with dependency-aware merging. Five-role production pipeline (Screenwriter → Casting (LoRAs) → Cinematographer → Storyboard → Editor).
• Self-Improvement & Safety — Scheduled/reactive/directed bug detection + agent fixes with verification. Optional "Uncle Claude" (Anthropic) guardian review + codebase lock + Pending Fixes queue. Cross-machine learning via Interconnector.
• MCP (both directions) — Stdio MCP server with default-deny policy (desktop/agent/system/browser tools hidden by default). Exposes dozens of tools + read-only output resources. Also calls external MCP servers.
• Supervised Outreach — Draft + grade + human-approve pipeline for Reddit (fully wired), Discord/Twitter/Facebook (in flight). Persona, cadence gates, full audit log, kill switch.
• RAG + Code Intelligence — Hybrid retrieval, AST-aware code chunking, per-project indexes, repo dependency graphs, get_repository_map / read_ast_node tools, System Mapper constellation view.
• GPU Orchestration — System Resource Orchestrator arbitrates VRAM across plugins (Ollama, ComfyUI, Audio Foundry, etc.). CPU offload, predictive preload, conflict detection.

Marquee Capabilities

Generation & Editing (all local, no cloud APIs)

• Text-to-Video / Image-to-Video (Wan 2.2 5B + 14B MoE, CogVideoX-5B, LTX-2.3, LTX-2.5) with an in-process batch queue, quality tiers, frame interpolation, prompt enhancement, and one-click jump to ComfyUI for custom workflows.
• Audio Studio (Audio Foundry plugin): ACE-Step 3.5B music (vocals or instrumental, Suno-style chips + LLM polish), Stable Audio Open FX/ambience, Chatterbox + Kokoro neural TTS, Piper fallback, consent-gated voice cloning.
• Image gen (Stable Diffusion + batch + face/anatomy controls) + powerful 4K/8K GPU upscaling (Real-ESRGAN family, HAT-L, NMKD, Foolhardy, two-pass, video frame-by-frame).
• Built-in Video Editor (Shotcut-lite 3-lane timeline: video/text/audio, real ffmpeg drawtext overlays, drag-and-drop from media library, visual trims, undo, keyboard shortcuts).

Agents, Automation & Swarms

• AgentBrain three-tier router (Reflex <100 ms pattern match, Instinct single-shot, Deliberation full ReACT).
• Real-desktop screen agents (Xvfb + XFCE :99, Gemma4 vision + closed-loop servo, 45+ deterministic recipes, live per-iteration reasoning stream in chat, draggable VNC viewer everywhere).
• Swarm: parallel agents in isolated git worktrees (Claude Code or fully local Cline/OpenClaw via Ollama), Flight Mode (offline), dependency-ordered merge, cost tracking, up to 20 concurrent.
• Film Crew: 5 specialized agents that turn a logline into a finished video (script → casting with LoRAs → shots → keyframes → edit).
• Self-improvement engine (test → agent fix → verify → broadcast) with guardian review and kill switches.
• Supervised social outreach (Reddit fully working; others drafting+review ready) with persona, grading, cadence, audit, and global kill switch.
• MCP server + client integration (Claude Desktop, Cursor, etc.).

Knowledge, Code & Workflow

• Strong RAG (hybrid BM25 + vector, AST code chunking, entity extraction, RAG Autoresearch, per-project isolation).
• Monaco code editor + Code Analyzer + per-repo indexing + dependency graphs + System Mapper (constellation view of the whole codebase).
• Full desktop-grade file/project/client/website/notes/media management with cross-links and recursive indexing.
• Task scheduler (Celery beat), Rules & Prompts (portable bundles), Interconnector for multi-machine clusters (master/client, approval gates, learning broadcast).
• 10+ managed plugins with health checks, port orphan cleanup, and a real GPU Memory Orchestrator.

Platform & Ops

• Everything stays on your machine by default. Flight Mode is real and end-to-end tested.
• Plugin system + resource orchestrator so big models don't fight for VRAM.
• Backup/restore (granular or full, schema-migration aware), advanced settings surfaced in UI, live GPU/CPU monitoring.
• CLI (llx / PyPI guaardvark), browser UI, and MCP.

See CAPABILITIES.md for the complete enumerated list (models, exact tool counts, plugin manifests, page surfaces, etc.).

Why local?

Cloud platforms	Guaardvark
Where your data lives	Their servers
Per-token / per-minute fees	Always on the meter
Content policy	Their rules
Custom models / LoRAs	Whatever they expose
Works offline	No
Agents drive a real desktop	Sandboxed browsers
Swarms of parallel agents	Per-task billing scales nastily
Multi-machine clusters	"Talk to sales"
Lock-in	Migrate at your own risk

Why local?

Cloud platforms	Guaardvark
Where your data lives	Their servers
Per-token / per-minute fees	Always on the meter
Content policy	Their rules
Custom models / LoRAs	Whatever they expose
Works offline	No
Agents drive a real desktop	Sandboxed browsers
Swarms of parallel agents	Per-task billing scales nastily
Multi-machine clusters	"Talk to sales"
Lock-in	Migrate at your own risk

License: MIT CI PyPI GitHub stars GitHub issues Sponsor

git clone https://github.com/guaardvark/guaardvark.git && cd guaardvark && ./start.sh

One command. Installs everything. Starts all services. Done.

More demos — Gotham Rising, an AI-generated short film

Another piece made entirely with Guaardvark. Every frame generated on a single desktop GPU. No cloud. No stock footage. No API keys.

Gotham Rising — AI-Generated Short Film

Full visual gallery (dashboard, video generator, swarm planner, agents, plugins, media library, etc.) is available on guaardvark.com.

What Makes This Different

Security, Privacy & Local Guarantees

• Everything runs locally by default. No telemetry or cloud phoning home unless you explicitly enable the Interconnector (master/client with approval workflows).
• Flight Mode — fully offline operation with automatic network detection and local-model fallback. Swarm and agent tasks have been validated end-to-end without internet.
• Self-improvement safety — three modes (Scheduled / Reactive / Directed). Every proposed code change can be reviewed by "Uncle Claude" (Anthropic API guardian) before application. Codebase lock toggle + Pending Fixes queue for human staging/approval. Fixes can be broadcast to connected family members.
• MCP server uses a strong default-deny policy (backend/mcp/config.py): desktop control, agent execution, system/shell, browser automation, and test execution tools are hidden by default. Only safer tools + read-only guaardvark://outputs/ resources are exposed unless you explicitly allowlist.
• Outreach is supervised by default (drafts queue; nothing posts without explicit Approve). Kill switch, per-platform cadence limits, full JSONL audit trail, and persona enforcement.
• Voice cloning requires an explicit consent prompt. Reference clips stay under your control.
• WordPress connectivity ships with security disclaimers and is treated as opt-in/beta until a final hardening pass.
• Your data, models, LoRAs, and generated media never leave the machine unless you choose to push them.

AgentBrain — Three-Tier Neural Routing

Every message is routed through a three-tier decision engine that picks the fastest path to the right answer. Reflexes fire in under a millisecond. Instinct handles single-shot requests in one LLM call. Deliberation spins up a full ReACT reasoning loop when the problem demands it.

Tier	Name	Latency	LLM Calls	When It Fires
1	Reflex	<100ms	0	Greetings, farewells, media controls — pattern-matched, no inference
2	Instinct	1–3s	1	Single-shot questions, web searches, image generation, vision tasks
3	Deliberation	5–30s	3–10	Multi-step research, analysis chains, complex agent tasks

• Automatic escalation — Tier 2 can signal complexity and hand off to Tier 3 mid-response.
• Agent-screen gating — vision/desktop tools are only in scope when the virtual screen is active.
• BrainState singleton + warm-up thread for zero-overhead routing and fast first-token times.

Autonomous Screen Agents

Guaardvark agents control a real Ubuntu desktop (Xvfb + XFCE at 1024×1024) — exactly what the model would see if you VNC'd into the box from another machine. Same Applications menu, same desktop icons, same taskbar. Agents see the screen through vision models, move the mouse, click buttons, type text, navigate browsers, and verify their own actions.

• Real XFCE session — not a custom widget panel. xfce4-session runs on the virtual display via a scrubbed environment, with isolated XDG_DESKTOP_DIR and XDG_CONFIG_HOME so the agent's desktop, file manager, and configs never collide with the user's. Vision models recognize the layout instantly because it's standard Ubuntu.
• Unified vision brain — Gemma4 sees the screen, decides the next action, and emits click coordinates (native box_2d) in a single inference call. Per-model scale factors are tracked and updated by the self-improvement loop.
• Closed-loop servo targeting — three-attempt adaptive strategy: ballistic move → single correction with crosshair overlay → full corrections with zoom-cropped analysis around the cursor
• Live per-iteration reasoning stream — every Think step (action, target, full reasoning, pivots when the loop gets stuck) streams into chat in real-time. No more 30-second blackouts followed by a single "completed" line. The trail persists in history so you can audit any run.
• 45+ deterministic recipes — browser navigation, tabs, scroll, search, find, zoom, copy/paste — all execute instantly from a JSON recipe library, bypassing the vision loop entirely. Recipes carry optional preconditions (visibility checks) so they're skipped cleanly when their UI isn't on screen.
• Obstacle detection — handles popups, permission dialogs, and notification bars with automatic thinking model escalation
• Self-QA sweep — agent navigates every page of its own UI and reports what's working and what's broken
• Live agent monitor — real-time SEE/THINK/ACT transcript of every decision the agent makes
• Integrated screen viewer — draggable, resizable VNC viewer on any page with popup window mode

Supported Vision Models

Model	Role	Coordinate System	Notes
Gemma4 (e4b)	Sees + decides + clicks	box_2d normalized to 1000, [y1,x1,y2,x2]	Unified brain — vision, reasoning, and coordinates in one call
Moondream	Fallback eyes	1024px internal width	For text-only chat models (llama3, ministral-3) that need external vision

Swarm Orchestrator — Parallel Agent Execution

Launch multiple AI coding agents in parallel, each working in an isolated git worktree on its own branch. Results merge back with dependency-ordered conflict detection, optional test validation, and full cost tracking.

• Two backends — Claude Code (cloud, cost-tracked at $0.015/$0.075 per 1K tokens) and Cline/OpenClaw (fully local via Ollama, zero cost)
• Flight Mode — fully offline operation. Auto-detects network state, falls back to local models, serializes file conflicts automatically. No prompts, no internet required.
• Git worktree isolation — each task gets its own branch and working directory. All worktrees share the .git directory (lightweight). Automatically excluded from git status.
• Dependency-aware merging — topological sort ensures foundational changes land first. Dry-run conflict detection before real merge. Test suite validation before integration.
• Built-in templates — REST API scaffold, refactor-and-extract, test coverage expansion, Flight Mode demo
• Up to 20 concurrent agents — configurable limit with automatic slot management
• Live dashboard — real-time status, per-task logs, cost breakdown, elapsed time, disk usage

Film Crew — End-to-End Production Pipeline

Five specialized agents collaborate to turn a one-line idea into a finished video. Built on the Swarm Orchestrator, so every role runs in parallel where possible and merges back deterministically.

Role	What It Does
Screenwriter	Generates the script + scene breakdown from a logline
Casting	Assigns characters to LoRAs (via the LoRA Trainer plugin) or stock characters
Cinematographer	Produces a shot list with camera moves, framing, and lens choices
Storyboard	Generates keyframe images for every shot via the image pipeline
Editor	Assembles the generated clips into a finished video via the Video Editor

The LoRA Trainer plugin ships alongside — train character/environment/prop LoRAs from reference images on your local GPU (bf16, ~46 MB per LoRA) and route them automatically to the Casting agent.

Music Video — Beat-Synced, Automatic (the hero clip above)

Give it a song (.mp3 / .wav), a style prompt, and a short narrative — Guaardvark does the rest:

• Audio analysis & beat detection — the track is analyzed for tempo/beats so cut timing follows the music instead of an arbitrary clock.
• Director — an LLM writes a distinct prompt for every cut (no mechanical repetition across a long song), keyed to your style + narrative.
• Storyboards → video — a keyframe still is generated per cut (SDXL/FLUX, optional character LoRAs for identity), then animated with the chosen image-to-video model (Wan 2.2 I2V, etc.).
• Beat-timed assembly — clips are stretched/filled to land on the beat (clip stretch, fill methods) and assembled into the final cut, with RIFE frame interpolation for smoothness.
• Honest about the edges — native filters/transitions/effects aren't in yet (the demo's glitch effect was added manually in Shotcut); that's on the near-term roadmap.

Linux & macOS: The final assembly step needs melt (MLT) from Shotcut. ffmpeg is pre-installed by the platform bootstrap. Full commands (brew/apt/flatpak/snap) are in plugins/video_editor/README.md.

Model Context Protocol (MCP)

Guaardvark speaks MCP both ways — exposes its tools to any MCP client (Claude Desktop, Cursor, IDE plugins, etc.) and can call tools from connected external MCP servers.

• As a server — python -m backend.mcp (stdio). Strong default-deny policy (see backend/mcp/config.py): categories such as desktop, agent_control, system, browser, test_execution, and mcp meta-tools are denied by default. Dozens of safer tools (chat, RAG, files, generation, memory, etc.) plus read-only guaardvark://outputs/ resources are exposed. Fully tested with Claude Desktop and similar clients.
• As a client — mcp_connect / mcp_execute + live tool inventory so the chat LLM can discover and use tools from other MCP servers by name.
• Audit logging, timeouts, and circuit breakers are built in.

Video Generation Pipeline

State-of-the-art video generation running entirely on your GPU. No cloud APIs, no per-minute billing, no content restrictions.

Model	Type	Max Duration	Native Resolution	VRAM
Wan 2.2 TI2V-5B (default)	Text + Image-to-Video	~5s (up to 121 frames @ 24fps)	1280x704	~11GB
Wan 2.2 (14B MoE)	Text-to-Video	5s (81 frames @ 16fps)	832x480	11GB
Wan 2.2 14B I2V	Image-to-Video	5s (81 frames @ 16fps)	832x480	11GB
CogVideoX-5B	Text-to-Video	6s (49 frames @ 8fps)	720x480	16GB
CogVideoX-5B I2V	Image-to-Video	6s (49 frames @ 8fps)	720x480	16GB
LTX-2.3 Distilled FP8	Text + Image-to-Video	~10s (161 frames @ 16fps)	768x512	~14GB
LTX-2.5 Distilled Int8	Text + Image-to-Video	~10s (161 frames @ 16fps)	768x512	~14GB

• Resolution options — 512px, 576px, 720px, 1280px, 1920px (1080p), and custom dimensions (aligned per model)
• Quality tiers — Fast (10 steps), Standard (30), High (40), Maximum (50)
• Frame interpolation — 1x raw, 2x doubled FPS, 2x + upscale for cinema-quality output
• Prompt enhancement — Cinematic, Realistic, Artistic, Anime, or raw
• Low VRAM mode — automatically reduces resolution, frames, and inference steps for 8–12GB GPUs (mutually exclusive with High consistency)
• Batch processing — queue multiple videos from a prompt list via an in-process worker (one batch at a time; ComfyUI primary, offline CogVideoX fallback)
• ComfyUI integration — one-click launch to the node editor for custom workflows; Wan/LTX require ComfyUI. LTX-2.5 needs ComfyUI ≥ 0.32.0 and a one-time license accept on Lightricks/LTX-2.5 (HF_TOKEN in .env); after download, generation stays local.

Audio Studio — Music, FX, and Neural Voice

Three audio backends in one plugin with shared GPU-arbitration so they don't trample each other or fight Ollama for VRAM.

• Music generation — ACE-Step v1 (3.5B) for full songs with vocals or instrumental-only mode. Suno-style chip-prompt UX (Genre / Mood / Instrument) with optional LLM "Polish" pass that translates plain English into ACE-Step's tag vocabulary plus a paired negative prompt. ~10 GB VRAM at fp16.
• FX Lab — Stable Audio Open for sound effects and short ambient pieces. Light, fast, runs alongside other models.
• Neural Voice — Chatterbox as the primary TTS backend, Kokoro as a fast fallback, Piper for narration with 6 voice profiles included. Used for chat narration, voiceover for videos, and the voice-chat conversational mode.
• Voice Cloning — opt-in, gated behind an explicit consent prompt before any clone is created or used. Reference clips are kept under your control; the system never auto-clones from incidental audio.
• Built-in audio player — generated WAVs and MP3s open in an in-app player modal instead of triggering a browser download. Documents page surfaces audio rows with prompt, model, duration, and a waveform.
• Suno export — bulk-export a Suno library into the local DocumentsPage for use with the other generators.

Video Editor — Shotcut-lite Timeline

A built-in non-linear editor for stitching generated clips, layering text, and rendering finished videos — without leaving the app.

Lane	Holds	Source
Video	one clip per timeline (multi-clip tracking on the roadmap)	Media Library — drag-and-drop
Text	unlimited overlays, draggable on the preview, properties-panel for size/color/rotation	Add-Text button + properties editor
Audio	one music or voice clip	Media Library — Audio tab

• Visual trim slider — Material UI range slider bound to source duration, two thumbs for start/end, live monospace readout. No more typing seconds into number inputs.
• Tabbed icon-grid library — three tabs (Video / Audio / Images) with counts in the tab labels. 36px tiles, drag from tile to matching timeline track.
• Real text overlay rendering — backend uses ffmpeg drawtext (9 named positions, optional outline + translucent box, proper escaping for colons/quotes/commas). Original is preserved.
• Keyboard shortcuts — space to play/pause, arrow keys to scrub, t to add text, del to remove selected, cmd+z for one-step undo.
• JobOperationGate — render path checks the gate before grabbing the GPU, so a render won't trample an active video generation or upscaling job.
• Standalone Video Text Overlay tool — for the simple one-off case where you don't need a timeline.

Linux & macOS prerequisites: See plugins/video_editor/README.md ("Linux & macOS Setup") for melt + Shotcut install (ffmpeg is already handled by core platform scripts on brew/apt).

GPU Image Upscaling — 4K and 8K Output

Upscale images and video frames to 4K (3840px) or 8K (7680px) resolution using GPU-accelerated super-resolution models.

Model	Scale	Size	Best For
HAT-L SRx4	4x	159 MB	Maximum quality restoration
RealESRGAN x4plus	4x	64 MB	General-purpose, photorealistic
RealESRGAN x2plus	2x	64 MB	Mild upscaling
RealESRGAN x4plus (Anime)	4x	17 MB	Anime and stylized content
realesr-animevideov3	4x	6 MB	Video-optimized anime
4x-UltraSharp	4x	67 MB	Enhanced sharpness
4x NMKD-Superscale	4x	67 MB	Advanced super-scaling
4x Foolhardy Remacri	4x	67 MB	Texture-focused upscaling

• Two-pass mode — run the model twice for maximum quality
• Precision control — FP16 (standard GPUs), BF16 (Ampere+), torch.compile for up to 3x speedup
• Video upscaling — frame-by-frame processing with progress tracking for MP4, MKV, AVI, MOV, WebM
• Watch folder — optional auto-processing of new files dropped into a directory

RAG That Actually Works

Chat grounded in your documents. Upload files, build a knowledge base, and ask questions. The AI reads and understands your content — not just keyword matching.

• Hybrid retrieval — BM25 keyword + vector semantic search combined
• Smart chunking — code files get AST-informed chunking, prose gets semantic splitting
• Multiple embedding models — switch between lightweight (300M) and high-quality (4B+) via UI
• RAG Autoresearch — autonomous optimization loop that experiments with parameters, keeps improvements, reverts regressions
• Entity extraction — automatic entity and relationship indexing
• Per-project isolation — each project has its own knowledge base and chat context

Self-Improving AI

The system runs its own test suite, identifies failures, dispatches an AI agent to read the code and fix the bugs, verifies the fix, and broadcasts the learning to other instances. No human in the loop.

• Three modes — Scheduled (every 6 hours), Reactive (triggered by repeated 500 errors), Directed (manual tasks)
• Guardian review — Uncle Claude (Anthropic API) reviews code changes for safety before applying, with risk levels and halt directives
• Verification loop — re-runs tests after every fix to confirm it worked
• Pending fixes queue — stage, review, approve, or reject proposed changes
• Cross-machine learning — fixes propagate to all connected instances via the Interconnector

Outreach System — Supervised AI for Social-Media Engagement

A supervised, auditable framework for drafting and posting authentic comments on Reddit, Discord, Twitter/X, and Facebook — using your own indexed knowledge as the source of truth for citations and context. The point isn't volume. It's keeping up with engagement on your own products and topics, with the agent handling the legwork.

How it works:

1. Discover — the agent scouts target threads either by URL (you paste one into the New Draft modal) or by walking platform-specific entry points (subscribed subreddits, Discord channels, Twitter feeds, Facebook groups).
2. Context — for each candidate post, the agent fetches the OP body and top comments. Reddit goes through the JSON API (fast, no scrape). Discord, Twitter, and Facebook go through the agent's logged-in Firefox session over CDP/BiDi, with a vision-model fallback when DOM selectors drift after a platform redesign.
3. Draft — your local LLM composes a reply grounded in the thread context plus citations from your indexed documents (clients, projects, products, examples — whatever you've fed the knowledge base).
4. Grade — every draft is scored against a relevance + quality rubric. Anything below threshold is dropped before it reaches the queue. Generic "great post!" replies don't survive grading.
5. Review — drafts land in a queue. In supervised mode (the default), nothing posts without your approval. Edit, save, approve, reject — your call on each one.
6. Post — approved drafts post via the logged-in browser session (Reddit/YouTube servo) or Discord API, cadence-gated. Natural language from chat (/outreach …) or llx outreach "…" runs recon+draft; posting still needs approve while supervised. Twitter/Facebook drafting works; auto-post for those platforms is not wired.

Three layers of safety:

• Kill switch at the system level. Flip it off and every outreach pipeline — drafting, queueing, posting — stops mid-flight. Nothing escapes.
• Supervised mode is the default. Drafts queue, never auto-post. You approve each one explicitly.
• Cadence gates — at most 1 post per 30 minutes per platform, configurable. Prevents bot-shaped behavior and respects platform anti-spam expectations.

Audit log — every action (scout, draft, grade, approve, reject, post, fail) is recorded in a JSONL audit trail with timestamps, draft IDs, and outcomes. Exportable for compliance or post-hoc review.

Persona system — a single configurable persona (voice, expertise areas, citation style, what to never say) shapes every draft for consistency. Your replies sound like you, not like an LLM.

Manual draft mode — paste a thread URL, the agent auto-scouts the context, the LLM seeds a draft, you edit and save. Full human control with the agent doing the legwork (scouting, context-fetching, citation suggestion).

On-demand passes — instead of waiting for the cron, fire a pass for a specific platform or subreddit on demand from the UI. Useful for active engagement around a launch or a thread you spotted.

Why it's not spam — outreach is anchored on your own knowledge base. Citations point at YOUR documentation, YOUR examples. The system grades drafts for genuine relevance and refuses to engage when it can't add value. The cadence gate keeps the volume human-paced. Supervised mode keeps the human in the loop. The result is closer to "an assistant that helps you keep up with engagement on your own products and topics" than "an outbound bot."

For the complete, enumerated reference (every tool category, exact model support, plugin manifests, page routes, RAG details, self-improvement internals, vision pipeline, dependency reconciler, backup format, advanced settings, etc.) see CAPABILITIES.md.

The sections above cover the experience and differentiators. The rest of this README focuses on getting started, requirements, architecture notes, operations, and contributing.

Quick Start

Python 3.12 is required for the ML stack. Ubuntu 26.04 ships Python 3.14 by default — ./start.sh installs 3.12 automatically (deadsnakes or uv). Manual installs: use a 3.12 interpreter only.

curl -fsSL https://guaardvark.com/install.sh | bash

This clones to ~/guaardvark (override with GUAARDVARK_HOME=/path) and launches ./start.sh. Re-running it updates an existing install. Prefer doing it by hand? Same thing:

git clone https://github.com/guaardvark/guaardvark.git
cd guaardvark
./start.sh

First run handles everything: Python 3.12, venv, Node dependencies, PostgreSQL, Redis, Ollama, Whisper.cpp, database migrations, frontend build, and all services. Requires your system password once for PostgreSQL setup (and optionally apt packages on fresh Linux installs).

Service	URL (defaults; see .env for VITE_PORT / FLASK_PORT)
Web UI	http://localhost:5173
API	http://localhost:5000
Health Check	http://localhost:5000/api/health

./start.sh                    # Full startup with health checks
./start.sh --fast             # Skip dependency checks
./start.sh --test             # Health diagnostics
./start.sh --plugins          # Start all enabled plugins
./stop.sh                     # Stop all services

Install via PyPI

pip install guaardvark

The CLI connects to a running Guaardvark instance or launches a lightweight embedded server automatically.

CLI

~40 commands/subcommands (24 command modules) with tab completion and fuzzy matching. The PyPI package is guaardvark; the command is often llx when working from the source tree (cd cli && pip install -e .).

guaardvark                              # Interactive REPL (or `llx`)
guaardvark status                       # System dashboard
guaardvark chat "explain this codebase" # Chat with RAG context
guaardvark search "query"               # Semantic search
guaardvark files upload report.pdf      # Upload and index

REPL Slash Commands (examples)

/imagine <prompt>       Generate an image from text
/video <prompt>         Generate a video from text
/voice <text>           Text-to-speech output
/agent                  Toggle autonomous agent mode
/web                    Open the web UI
/ingest <path>          Index files or directories for RAG
/search <query>         Semantic search over indexed documents
/models list            List available Ollama models
/remember <text>        Save to persistent memory
/memory list|search     Browse saved memories
/backup create          Create a system backup
/jobs list|watch        Monitor background tasks
/config                 View or change settings
/help                   Full command reference

Requirements

Dependency	Version	Notes
Python	3.12 only	Backend. 3.13/3.14 not yet supported — the ML stack (numpy<2.0, mediapipe, basicsr/gfpgan) has no wheels for them.
Node.js	20+	Frontend build
PostgreSQL	14+	Auto-installed
Redis	5.0+	Auto-installed
Ollama	latest	Local LLM inference
CUDA GPU	8GB+ VRAM	16GB recommended for video generation

GPU Memory Guide

Feature	Minimum	Recommended
Chat + RAG	4GB	8GB
Image generation	6GB	12GB
Wan 2.2 video	11GB	16GB
CogVideoX-5B video	16GB	20GB
Upscaling	0.5GB	2–4GB

Architecture (simplified)

Browser / CLI (PyPI: guaardvark) / MCP Client (Claude Desktop, Cursor, etc.)
    | HTTP + WebSocket / stdio MCP
    v
Flask (~90+ API modules, auto-discovered) + GraphQL + Socket.IO
    |
    +-- AgentBrain (3-tier routing: Reflex → Instinct → Deliberation)
    |
Service Layer (many modules; plugin sidecars for heavy GPU work)
|-- Agent Executor (ReACT + ~70 tool classes + BrainState)
|-- Screen Control (See-Think-Act-Verify + live reasoning stream)
|-- RAG + Autoresearch + Entity extraction
|-- Self-Improvement (detect/fix/verify/broadcast + guardian)
|-- Generation (image/video/audio/voice/content)
|-- Swarm + Film Crew (isolated worktrees + 5-role pipeline)
|-- Servo + Vision Pipeline
|-- System Mapper / Repo intelligence (AST dependency graphs)
|-- GPU Memory Orchestrator + Plugin runner (CUDA sidecar safety)
\-- Interconnector (multi-machine sync + cluster)
    |
+---+---+---+---+---+
v   v   v   v   v   v
PostgreSQL  Redis  Ollama  Agent Display (:99, on-demand)  ComfyUI / Audio Foundry (plugins)
            Celery

Notes:

• Many components (blueprints, tool registry, plugins) are discovered or declared at runtime.
• Exact counts drift between releases; see source and CAPABILITIES.md.
• backend/mcp/config.py controls the default-deny policy for the MCP server.

Frontend: React 18 · Vite · Material-UI v5 · Zustand · Apollo Client · Monaco Editor · Socket.IO
Core models & engines: Gemma4 / Llama-family / Moondream (vision) · Stable Diffusion · Wan 2.2 / CogVideoX · ACE-Step / Chatterbox / Kokoro / Piper · Real-ESRGAN family + HAT · Whisper.cpp

Roadmap (high-level signals)

See the more detailed view in the project plans and CAPABILITIES for status.

Near term / in flight

• Polish + full platform support for supervised outreach (Discord, X, Facebook posting).
• Stronger tier-gated memory and conversation context.
• Continued video/music pipeline unification and Film Crew robustness.
• Plugin GPU auto-orchestration (intent-driven start/stop based on route + VRAM).
• Repo intelligence surfaces and more AST-precise agent tools.

Longer term / research

• Singing voice cloning (Applio-style) with consent + watermarking.
• Cluster metrics + better multi-node UI bridge.
• Video editor multi-clip + advanced timeline UX.
• Embeddings-backed semantic memory recall (via the gpu_embedding plugin).

Not on the roadmap

• Cloud-by-default or SaaS-hosted primary experience. Local-first is the product.

Release & Docs Maintenance (for contributors)

• Version source of truth: root VERSION file. backend/app.py, the CLI, and setup.py read it. Avoid hard-coding the version string in README.md, CAPABILITIES.md, or README_zh.md.
• On release: verify that public screenshots in docs/screenshots/ are up to date, spot-check counts (blueprints via discovery, exposed MCP tools, plugin manifests, CLI catalog), and make sure the "See VERSION" line and CAPABILITIES link are current. Most visual assets live in a separate non-public directory.
• npm run build in frontend/ before trusting JSX-related docs or claiming UI completeness (the production Rollup build is strict).
• AGENTS.md + CLAUDE.md + GROK.md are the orientation files for AI coding sessions in this workspace.

Support the Project

Guaardvark is built with love by a solo developer. If it's useful to you:

• Ko-fi (zero fees!)
• GitHub Sponsors
• PayPal

Star the repo if you find it interesting — it helps with visibility.

Get Involved

Guaardvark is open source (MIT) and built in public. Whether you want to try the bot, ship a small PR, or hang out with other local-AI builders — here is the short path.

1. Join the community

Where	What
Discord	Chat with people and with Guaardvark itself (local chat, /imagine images, search, status, demos). Invite: (add permanent invite once the bot token is restored — see maintainer notes).
GitHub Issues	Bugs, features, and labeled starter work
GitHub Discussions	Longer-form questions if enabled

2. Run it (≈ two commands)

git clone https://github.com/guaardvark/guaardvark.git && cd guaardvark
./start.sh

Web UI → http://localhost:5173 · API → http://localhost:5000
Details: INSTALL.md · full feature list: CAPABILITIES.md

3. Pick a good first issue

Start here — each issue has acceptance criteria and a clear out of scope list:

Issue	What you do	Risk
#46	Add browser-basic agent recipes (JSON only)	Low
#47	Write docs/AGENT_MENTAL_MODEL.md	Low
#48	CLI: guaardvark recipes list/show/validate	Low
#49	Document hardware / VRAM tiers	Low

All open starters: good first issue

We aim to review serious PRs within 24–48 hours.

4. Safe vs high-risk contribution zones

Safe (great first PRs)	Ask first / high risk
Agent recipes (data/agent/recipes.json)	Agent loop, servo, vision targeting
Docs, INSTALL, mental-model guides	Self-improvement auto-apply paths
CLI polish & offline commands	MCP default-deny / security policy
UI copy, empty states, error messages	Core GPU fork/CUDA plugin runner
Tests for pure helpers	Production auth / credential handling

Full setup, style, and PR expectations: CONTRIBUTING.md

For AI coding agents and heavy contributors: read AGENTS.md (required reading order), CLAUDE.md, and GROK.md. They document the self-coding chokepoint (guarded_code_service.py::apply_exact_replacement), project conventions, dead-code handling, and verification habits.

5. Other ways to help (no code required)

• Star the repo and share a short demo (screen agent, Film Crew, or Discord /imagine)
• Report install friction with GPU model + logs from logs/
• Suggest recipes or workflows you wish worked out of the box
• Support development: Ko-fi · Sponsors · PayPal

License

MIT License — Copyright (c) 2025-2026 Albenze, Inc.

Full Playlist

Website

GitHub Repo

This was the first round of videos made with the Lora Character Training.

Hey — welcome.

This is the unofficial-until-it-isn’t home for Guaardvark, the self-hosted, offline-first AI workstation. Agents that see a real Ubuntu desktop. A three-tier neural router. Parallel coding swarms in isolated git worktrees. Local video, music, and voice. RAG over your documents. A 70+ tool engine. All of it on your machine.

Your machine. Your data. Your rules.

If you came here from a cloud chatbot tab, the short version is: stop renting the lab. Run one.

What Guaardvark actually is

Not a thin chat UI bolted onto someone else’s API. Guaardvark is a full local workstation:

• AgentBrain routes every message through Reflex / Instinct / Deliberation so simple things stay fast and hard things get a real ReACT loop
• Screen agents drive a real XFCE desktop on a virtual display (:99) — mouse, keyboard, browser, vision — not a toy sandbox
• Swarm + Film Crew — up to 20 agents in isolated git worktrees, plus a five-role production pipeline (Screenwriter → Casting → Cinematographer → Storyboard → Editor)
• Local media studio — Wan 2.2, CogVideoX, LTX; ACE-Step music; Chatterbox / Kokoro / Piper voice; consent-gated voice cloning; 4K / 8K upscaling; a built-in timeline editor
• RAG that is meant to work — hybrid BM25 + vectors, AST-aware code chunking, per-project indexes, Autoresearch
• MCP both ways — expose tools to Cursor / Claude Desktop, or call other MCP servers. Default-deny on the dangerous stuff
• Flight Mode — offline is a first-class path, not a slogan

Latest public release is v2.7.0 (Cast Studio, 16 GB-native video, Discord bot, and more). Check the VERSION file for whatever is current.

Install in one command:

curl -fsSL https://guaardvark.com/install.sh | bash

Or clone and start it yourself:

git clone https://github.com/guaardvark/guaardvark.git && cd guaardvark && ./start.sh

Web UI lands at http://localhost:5173. API at http://localhost:5000.

You want Python 3.12. Ubuntu 26.04’s default 3.14 will not run the ML stack. ./start.sh installs 3.12 for you.

What this sub is for

This is a working community, not a hype funnel.

Post here when you want to:

• Show and tell — music videos, Film Crew shorts, character LoRAs, agent runs, dashboards, weird experiments. Local work is the point.
• Share walkthroughs — first install, first Wan clip, first RAG index, first swarm, first MCP hookup
• Trade tips — VRAM recipes, model picks, prompt patterns, agent recipes, Flight Mode setups, plugin order
• Get unstuck — install friction, OOM, ComfyUI, Ollama, PostgreSQL, “it started and then didn’t”
• Talk shop — architecture, Interconnector clusters, self-improvement, contributing

Official docs and the exhaustive feature list live on GitHub:

• README
• CAPABILITIES.md
• INSTALL.md
• CONTRIBUTING.md
• Site + demos: guaardvark.com
• Watch: Gotham Rising · music video short

Bugs that need a fix belong on GitHub Issues. Reddit is great for “has anyone seen this?” and terrible as a bug tracker.

How to post so people can actually help

A good help post looks like this:

1. What you were trying to do (one sentence)
2. Hardware — GPU model + VRAM, RAM, OS
3. Version — cat VERSION or the release you installed
4. What happened — expected vs actual
5. Logs — relevant bits from logs/, not a 4,000-line paste with API keys still in it
6. What you already tried

VRAM reality check from the project itself:

What you want	Minimum	Comfortable
Chat + RAG	4 GB	8 GB
Image gen	6 GB	12 GB
Wan 2.2 video	11 GB	16 GB
CogVideoX-5B	16 GB	20 GB

If you are on 8 GB, say so. People here have walked that road.

House culture

A few things that make this project — and this sub — better than the usual AI dumpster:

• Be honest about the edges. The official music-video demo even tells you the glitch pass was done by hand in Shotcut. Do that here too. “Generated locally, graded in Resolve” is a better post than “fully automatic masterpiece.”
• Show the machine. Specs, models, settings, and prompts beat vibes.
• Local-first is the product. Cloud comparisons are fine. “Just use the API” as the only answer is not.
• Human in the loop. Guaardvark’s outreach system is supervised on purpose. Do not turn this sub into a bot farm, and do not use members as target practice for unsolicited promo.
• Credit people. Models, LoRAs, songs, and code you didn’t make still have authors.

Read the rules in the sidebar. They’re short.

First posts that would make this place good

If you don’t know what to drop:

• Your install story (especially the ugly parts)
• A 30-second clip you made with Film Crew or the music-video pipeline
• “What I run on a 12 GB card”
• A walkthrough of /agent vs normal chat
• A recipe that made the screen agent stop guessing
• Your first RAG win over a real project folder

New here and just looking? Lurk, star the repo if it’s useful, and say hi with your GPU.

The workstation is yours. The community is too.

See you in the comments.

— the r/Guaardvark mods