Guaardvark README

Why Guaardvark

• It runs on your machine. Language models, retrieval, agents and every generator run on your own hardware, through Ollama, ComfyUI and Guaardvark's own GPU services. No cloud API keys, no per-token or per-minute fees, nothing reported home. Web access, posting and every other outbound path stay off until you switch them on or start them, and all of them are declared in one file, egress.json.
• One install is the whole studio. Chat and RAG, screen agents, coding swarms and a full media pipeline share one GPU through a single orchestrator, so a video render and a language model take turns instead of fighting over VRAM.
• Your coding agent can drive it. A built-in MCP server, fifteen agent skills and a Claude Code plugin let Claude Code, Cursor, Codex, Gemini CLI and other agents run every flow: "make a music video from this song", "film this script", "train a LoRA of this character", "swarm this refactor".
• You approve what matters. Nothing posts and no voice is cloned without an explicit yes from you, and fixes Guaardvark writes for its own code wait for your review. The MCP server hides desktop, shell and browser tools unless you allowlist them.

Quick start

Linux with an NVIDIA GPU (16 GB for video, 12 GB for the Wan 2.2 5B; chat, RAG and agents run on less, see the hardware tiers). A fresh Ubuntu desktop has no curl or git; run sudo apt install -y curl git first.

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

Then open http://localhost:5173. The script is install.sh from this repository: it clones to ~/guaardvark and runs ./start.sh, which installs everything on the first run. To read it before it runs, download it first (curl -fsSL https://guaardvark.com/install.sh -o install.sh, read it, then bash install.sh), or install by hand.

Add it to Claude Code (two lines, no clone):

/plugin marketplace add guaardvark/guaardvark
/plugin install guaardvark@guaardvark

Other ways in: Docker · macOS on Apple Silicon · the CLI from PyPI · the full install guide. The current release is in the VERSION file.

Features

• Chat with your own files. Local RAG on pgvector: keyword and vector search fused per query, cross-encoder reranking, source citations, and retrieval that shows the chunks and scores behind an answer. Autoresearch tunes retrieval overnight. ▶ Ep 3
• Agents on a real desktop. Screen agents get an Ubuntu desktop of their own, see it with a vision model, click with closed-loop targeting, and work in a real browser while you watch from any page. ▶ Ep 4
• Parallel coding agents. A swarm of coding agents, each in its own git worktree, merged back in dependency order. Runs on Claude Code or fully locally through Ollama.
• MCP, both ways. An MCP server that plugs into Claude Code, Cursor, Codex, Gemini CLI, Zed and more with one command, and an MCP client so chat can use tools from other servers. ▶ Ep 21 · ▶ Ep 16
• Video generation. 13 local video models across five families (Wan 2.2, LTX, HunyuanVideo, CogVideoX, and MiniMax H3 with its own soundtrack), video LoRAs, a batch queue, frame interpolation, and one click into ComfyUI. ▶ Ep 6
• LoRA training and consistent characters. Train character, environment and prop LoRAs from a few reference photos on your own GPU, import LoRAs trained elsewhere, and keep the same character across images, video, music videos and Film Crew productions. Details
• Images. Z-Image, FLUX.1, Krea 2, SDXL and Sana Sprint (1024 stills in seconds, even on 8 GB cards) generation, photo edits by instruction, inpainting and outpainting, and 4K/8K upscaling. ▶ Ep 5
• Music and voice. Full songs with vocals, sound effects, three neural text-to-speech engines, consent-gated voice cloning, and hands-free voice chat.

The complete, enumerated list of models, tools, plugins and pages is in CAPABILITIES.md.

Chat with your own files (local RAG)

Upload documents, build a knowledge base per project, and ask questions. Answers are grounded in your files and cite where they came from.

• Hybrid retrieval. Postgres full-text keyword search and vector search, fused with a per-query weighting that leans toward keywords for identifier-like queries and toward meaning for prose.
• Cross-encoder reranking. A reranker (one Install in Settings) reads the query and passage together and reorders the candidates. It is admitted against free VRAM and falls back to CPU rather than competing with image or video generation.
• Layout-aware parsing. PDF, DOCX and PPTX are parsed for reading order and section headers, and PDF passages carry the page they came from. (Scanned documents need OCR, which is not installed by default; they say so rather than indexing as empty.)
• Grounded citations. Every chunk carries its source file and section breadcrumb (and, for PDFs, the page), written into the embedded text as well, so a passage lifted from the middle of a document still says where it came from.
• Smart chunking. Code gets AST-informed chunks, so a function stays one chunk; prose gets semantic splitting.
• Postgres-backed vector store. Embeddings live in pgvector next to the rest of your data, with an ANN index and a persisted full-text index, covered by the same backups.
• Retrieval that shows its work. Live retrieval tests show the actual chunks and scores behind an answer (Episode 3), and every query can return a trace of which retrieval legs ran, so a degraded answer can be told apart from a bad one.
• More: index profiles (the same documents projected more than one way), corpus-level summaries for "what are the themes across all of this", a choice of embedding models from 300M to 4B+, entity extraction, and per-project isolation.

Autoresearch tunes retrieval while you sleep. An overnight loop proposes changes to chunking and retrieval settings, scores them with an LLM-as-judge harness, keeps the wins and reverts the regressions, bounded by a wall-clock budget, a run ledger and a circuit breaker. The morning report says what changed and why.

One chat box, three speeds. Every message goes through a three-tier router that picks the fastest path to the right answer (Episode 2):

Desktop and vision tools are only offered to the model while the agent screen is active.

Agents that use a real desktop and browser

Guaardvark's agents control a real Ubuntu desktop (Xvfb and XFCE on display :99): the same Applications menu, desktop icons and taskbar you would see if you connected to the box over VNC. They see the screen through a vision model, move the mouse, click, type, browse, and check their own work. The desktop is isolated from yours: its own XDG_DESKTOP_DIR and XDG_CONFIG_HOME, so the agent's files and settings never collide with your session.

• One vision brain. Gemma4 sees the screen, decides the next action and returns click coordinates in a single inference call.
• Closed-loop targeting. The servo moves, checks where the cursor actually landed, and corrects until it is on the target, rejecting targets the model cannot really see.
• Live reasoning. Every step (action, target, reasoning, pivots when the loop is stuck) streams into chat as it happens and stays in history, so any run can be audited.
• Deterministic recipes. Common browser actions (navigation, tabs, back and forward, find, zoom, bookmarks, YouTube search) run instantly from a recipe library instead of the vision loop, and every recipe is checked against safety bounds before it loads.
• Done means done. The agent claims a task is finished only when it can show proof on the screen.
• Watch it work. A draggable, resizable viewer of the agent's desktop on any page, with a pop-out window.

Parallel coding agents (Swarm)

Launch several coding agents at once, each in an isolated git worktree on its own branch. Results merge back with dependency-ordered conflict detection, optional test validation, and a live dashboard.

• Backends: Claude Code, or Cline/OpenClaw running fully locally on an Ollama model.
• Flight Mode keeps a swarm offline: tasks run on the local backend only.
• Git worktree isolation: every task gets its own branch and working directory, sharing one .git directory.
• Dependency-aware merging: a topological sort lands foundational changes first, with a dry-run conflict check before the real merge and tests before integration.
• Templates for a REST API scaffold, refactor-and-extract, test-coverage expansion, and more.
• Live dashboard: status, per-task logs, cost, elapsed time and disk use. Five agents run at once by default; the dashboard takes up to 20.

Film Crew runs on the same orchestrator (see Directors).

MCP server, agent skills and the Claude Code plugin

Guaardvark speaks the Model Context Protocol both ways: it exposes its tools to any MCP client, and it can call tools on other MCP servers. Episode 21 shows five coding agents (opencode on a local model, Codex, Cursor, Grok and Antigravity) making pictures, clips, songs and voices through it.

• One-command setup. python -m backend.mcp install finds the agent clients on your machine (Claude Code, Codex, Cursor, Grok, Antigravity, opencode, Claude Desktop, Zed, Gemini CLI) and writes the guaardvark server entry into their configs, backing up existing files and leaving other entries alone. python -m backend.mcp doctor diagnoses a broken setup with a server self-test, a real stdio handshake, and a scan for stale client configs.
• Claude Code plugin. /plugin marketplace add guaardvark/guaardvark, then /plugin install guaardvark@guaardvark. It asks for the path of your Guaardvark checkout, starts the MCP server from there, and loads every skill as /guaardvark:<skill>.
• Agent skills. .agents/skills/ has one skill per flow (images, video, music video, Film Crew, voice, music, upscaling, Cast and LoRA training, Hugging Face model onboarding, swarm, knowledge, code, outreach, operations, setup) in the Agent Skills format, so Claude Code, Cursor, Codex and OpenClaw know which tool to call for each job. python -m backend.mcp install --skills links them into ~/.claude/skills.
• As a server: python -m backend.mcp (stdio) or python -m backend.mcp http (streamable HTTP on 127.0.0.1:8788/mcp, loopback-only by default). python -m backend.mcp list-tools prints the live tool list. Generation tools queue by default and return a batch id for get_generation_status; every call runs under an enforced timeout.
• Default-deny policy (backend/mcp/config.py): desktop control, agent control, system and shell, browser automation, test execution and MCP meta-tools are hidden unless you allowlist them, and so are tools that need approval. More than 50 tools are exposed by default (RAG, files, generation, memory, code search, web), plus read-only guaardvark://outputs/ resources.
• As a client: mcp_connect and mcp_execute, with a live inventory so the chat model can find and use tools from other MCP servers by name. Audit logging, timeouts and circuit breakers are built in.

More in docs/mcp.md.

Local video, image, music and voice generation

All generation runs on your GPU. No cloud APIs, no per-minute billing.

Video generation

MiniMax H3 also comes as unpruned Int8 and BF16 builds for 24 GB and 48 GB cards, which makes 13 video models in all.

• Resolutions of 512, 576, 720, 1280 and 1920 px (1080p), aligned per model.
• Quality tiers: Fast (10 steps), Standard (30), High (40), Maximum (50). Each model declares the fewest steps it renders well at, and a preset below that floor is raised to it (Wan and MiniMax H3: 20). MiniMax H3 also offers 8- and 4-step turbo profiles through its distilled LoRAs.
• Frame interpolation with RIFE (1x raw, 2x frame rate, 2x plus upscale), prompt enhancement styles (Cinematic, Realistic, Artistic, Anime, or raw), a low-VRAM mode for Wan and CogVideoX, and a batch queue for prompt lists.
• ComfyUI integration: one click into the node editor for custom workflows. Wan and LTX run through 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 the download, generation stays local.
• MiniMax H3 generates picture and sound in one pass. Guaardvark compiles your prompt into the model's structured format (numbered shots with cut times, speaker ids, tagged dialogue), and the Film Crew renders each scene as one spoken window on it. It is licensed under the MiniMax H3 Community License, which names the EU, UK, South Korea and USA as territories that need MiniMax's application form; the Video Models dialog shows the license and the link, and posts carrying H3 clips add a "Generated with MiniMax H3" line.
• Video generation needs a 16 GB-class card, except the Wan 2.2 5B, which is admitted from 11 GB; see docs/HARDWARE.md.

LoRA training and consistent characters

Train your own LoRAs on your own GPU and keep the same character, place or object across everything Guaardvark makes.

• Character, environment and prop LoRAs from a few photos. In the Cast Library, add reference photos, approve the generated samples, and train. The LoRA Trainer uses Z-Image Turbo as its default base (SDXL for older setups) and trains in bf16. A character LoRA trained from 5 photos at 512 px for 400 steps (rank 16) is about 33 MB.
• Consistent characters. Pick a Cast member on the Images, Video Generator or Music Video pages, or let Film Crew's Casting role assign one. Stills and keyframes are rendered with that character's LoRA, and video models animate those keyframes, so every shot starts from a frame made with the same character LoRA.
• Import LoRAs trained elsewhere. Attach a .safetensors LoRA from Ostris AI-Toolkit, kohya or diffusers/PEFT to a Cast member; Z-Image Turbo and FLUX.1 Dev layouts are accepted, and the key layout is checked before it is stored.
• Video LoRAs. Add a video LoRA from its Hugging Face URL for the model it was trained on and pick it in the Video Generator; it loads into the Wan 2.2, LTX, HunyuanVideo or MiniMax H3 workflow in ComfyUI. Speed LoRAs are in the catalog: 8- and 4-step turbo profiles for MiniMax H3 and an experimental 4-step Lightning profile for Wan 2.2 14B.
• Image LoRAs from Hugging Face are added the same way and offered only for the models they fit.

Images and upscaling

• Image generation with Z-Image, FLUX.1, Krea 2, SDXL and Stable Diffusion 1.5 fine-tunes, batch runs from a prompt list or CSV, and anatomy controls.
• Photo editing by instruction (Qwen-Image-Edit, FLUX.1 Kontext), inpainting, outpainting and background removal, from the Images pages or straight from chat.
• Add any Hugging Face model (checkpoint or LoRA) from its URL.
• 4K and 8K upscaling on the GPU with nine models, from HAT-L (maximum-quality restoration) to anime-tuned Real-ESRGAN variants: two-pass mode, FP16/BF16 with optional torch.compile, frame-by-frame video upscaling, and an optional watch folder. The model table is in CAPABILITIES.md.

Music, sound and voice

The Audio Foundry plugin runs three audio backends with shared GPU arbitration, so they don't trample each other or fight Ollama for VRAM.

• Music: ACE-Step v1 (3.5B) writes full songs with vocals, or instrumentals. Pick genre, mood and instrument chips, with an optional LLM "Polish" pass that turns plain English into ACE-Step's tag vocabulary plus a paired negative prompt. ACE-Step 1.5 is an optional install.
• FX Lab: Stable Audio Open for sound effects and short ambient pieces.
• Neural voice: Chatterbox as the main text-to-speech engine, Kokoro as a fast fallback, and Piper for narration. Used for chat narration, video voiceover and voice chat.
• Voice cloning: opt-in, behind an explicit consent prompt before any clone is created or used. Reference clips stay under your control, and nothing is cloned from incidental audio.
• Voice chat: local Whisper speech-to-text, one microphone for the whole app, hands-free conversation, and a narrate button on every chat reply.
• Generated audio opens in an in-app player.

Directors: Film Crew, music videos and the editor

Film Crew turns a one-line idea into a finished video with five roles, with human checkpoints at casting and storyboard (Episode 9):

Music videos, cut on the beat (Episode 8). Give it a song, a style prompt and a short narrative. Guaardvark analyzes the tempo and beats, writes a distinct prompt for every cut, renders a storyboard still per cut (with optional character LoRAs for identity), and stops for your approval before any GPU time is spent on video. Then it animates each still with an image-to-video model and assembles the clips so they land on the beat, with RIFE frame interpolation for smooth motion. Assembly uses melt from Shotcut (setup in plugins/video_editor/README.md).

Video editor. Drop clips into the bin, pick a song, and press Plan: the Art Director arranges the cut, you adjust it with director's notes, and Render writes an MLT project and an MP4, with undo and keyboard shortcuts. A separate text-overlay tool places captions in nine positions with ffmpeg drawtext.

Self-improvement, System Map and code intelligence

• Self-improvement. Guaardvark runs its own tests, sends a code agent to read the failure and the source, drafts a fix, verifies it, and stages it as a pending fix for your review; applying fixes on its own stays off unless you turn it on. Three modes: scheduled (every six hours), reactive (after repeated server errors) and directed (tasks you give it). A codebase lock stops all changes, and what it learns can be shared with your other machines over the Interconnector (Episode 11).
• System Map. A live, force-directed constellation of the whole codebase computed from its real imports, with lifecycle tags (active, dormant, auto-loaded, test, script, config) and ranked findings you can hand to the self-improvement agent; findings with a mechanical fix arrive as an exact proposal for review (Episode 14).
• Code intelligence. A Monaco code editor with tabs and an assistant pane, repository maps, dependency graphs and AST-aware search (get_repository_map, read_ast_node, search_code, also over MCP). Every AI code write goes through one verified exact-replacement gate behind the codebase lock.

Privacy and safety

• Local by default. Your data, models, LoRAs and generated media stay on your machine unless you choose to send them. Every outbound path is declared in scripts/inbound_guard/egress.json and is off until a setting or a person turns it on: models download when you install one or first use one that isn't on disk, and web access is a switch in Settings, off by default.
• Works offline. With models downloaded, chat, RAG, agents and generation run without internet, and the Swarm has a dedicated Flight Mode.
• Approvals. Publishes, outreach drafts and held code changes wait on the Approvals page, each in its own tab.
• MCP default-deny. Desktop, agent control, shell, browser and test tools are hidden from MCP clients unless you allowlist them.
• Inbound guard. scripts/check_inbound.py reads code before it lands, in pull requests and inside the product, and in Enforce mode holds risky changes for a person to read.
• Uncle Claude is an optional second opinion and code reviewer that calls Anthropic's API. Without an ANTHROPIC_API_KEY in the environment it sends nothing. With a key, it runs only when you start it, unless you change one of two settings:
  • When you start it: /claude … in chat sends that message and the last 10 messages; Test connection sends a fixed test line; advice you ask for sends your GPU memory figures; a code change the agent makes at your request is sent for review as a file excerpt (up to 3,000 characters) and the diff.
  • Escalation: Always (Settings, off by default): every chat message and the last 10 turns go to Anthropic, and Claude's answer replaces the local one.
  • Scheduled sends (Settings → Uncle Claude, off by default): advice twice a day (the time, node id, GPU name and memory) and reviews of changes the self-improvement loop makes on its own (a source excerpt and the diff).
  • A review never applies anything; staged fixes still wait for you. Usage is counted against a monthly token budget.

See SECURITY.md to report a vulnerability.

More built in

• Supervised outreach. Drafts replies to threads on Reddit, YouTube, Discord, X and Facebook, grounded in your own indexed documents, graded for relevance before they reach the queue, with nothing posted until you approve it. Kill switch, per-platform cadence limits and a JSONL audit trail.
• Files and projects. A desktop-style file manager (folders as windows, drag and drop, right-click menus) with clients, projects, websites and notes linked together and indexed recursively. Files stream into the browser's own players and viewers, so video plays without a codec pack and PDFs start rendering before they finish downloading.
• Rules, prompts, lessons and memory. Portable rule bundles, lessons that teach the agent from a good run, and "remember …" notes that carry across chats.
• Discord bot plugin for chat, /imagine images and search against your own install.
• WordPress (opt-in): pull pages and posts from your sites, generate content in bulk, and push it back.
• Multi-machine Interconnector. Master and client nodes with approval gates, code and data sync, and shared learnings.
• Operations. Jobs and scheduling (Celery beat), schema-aware backup and restore, live GPU and CPU monitoring, and 11 first-party plugins with health checks and a GPU memory orchestrator.

How Guaardvark compares

The local-AI ecosystem has excellent tools for every slice: chat UIs, RAG workspaces, node-graph media pipelines, coding agents, assistant gateways. Guaardvark's bet is different: one install on one GPU that is the whole studio, with one GPU orchestrator arbitrating all of it.

Columns describe the typical shape of each category, not any single project; several projects exceed their category in places.

If you need one slice, use the excellent specialist: a chat UI like Open WebUI, a node graph like ComfyUI (Guaardvark hands off to it with one click), a RAG workspace like AnythingLLM. Guaardvark is for when you want the whole studio on one box.

Watch it work

Short screen recordings of the real system doing real work, narrated by its own local speech engine. Watch the full playlist.

Beat-synced music video (watch the short): one style prompt and a short narrative, then go. Guaardvark wrote every shot prompt, generated the storyboards, rendered the clips and cut them to the beat it detected in the song. (The glitch effect was added afterwards in Shotcut, and the song was made in Suno.)

More screenshots are on guaardvark.com.

Requirements

Which tier is your machine? docs/HARDWARE.md says what runs CPU-only, on 8–12 GB, on the 16 GB design target, and with 24 GB+ of headroom.

* The Wan 2.2 5B declares an 11 GB floor: an 11 GB card can select it by hand, and from 12 GB the automatic pick chooses it. A full render on 12 GB has not been confirmed yet. Every other video family needs a 16 GB-class card; see docs/HARDWARE.md.

Platforms. Linux with one NVIDIA card is the primary target. Apple Silicon is supported, with GPU features arriving through Metal (what works today is in INSTALL.md). Windows through WSL2 is being verified.

Running Guaardvark

Install by hand

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

The one-line installer does the same, cloning to ~/guaardvark (override with GUAARDVARK_HOME=/path); re-running it updates an existing install. The first run handles everything: Python 3.12, the virtualenv, Node dependencies, PostgreSQL, Redis, Ollama, Whisper.cpp, database migrations, the frontend build and all services. It asks for your system password once for PostgreSQL setup (and, on fresh Linux installs, optionally for apt packages).

./start.sh                    # Full startup with health checks
./start.sh --fast             # Reuse venv + node_modules as they are: no installs, no frontend build, no preflight
./start.sh --test             # Health diagnostics
./start.sh --plugins          # Start all enabled plugins
./start.sh --external-ollama  # You run Ollama yourself; never started or stopped by these scripts
./stop.sh                     # Stop Guaardvark (and only the Ollama that start.sh launched)
./stop.sh --keep-ollama       # Stop Guaardvark, leave Ollama running whoever started it
./stop.sh --all               # Also stop your own `ollama serve` and the systemd service

An Ollama already running before ./start.sh is adopted, not restarted, and left running on ./stop.sh. To make either policy permanent, flip the switches in Settings → Product Profile → Ollama, or set GUAARDVARK_OLLAMA_KEEP_RUNNING=1 / GUAARDVARK_OLLAMA_EXTERNAL=1 in .env.

Pick a profile

The first start asks what Guaardvark is for here. Creator lists the media workflow (image, video, audio, Film Crew, LoRA, upscaling) and leaves agents, the knowledge index, outreach and automation installed but out of the way; Workstation is everything. Either is a starting point, not a ceiling: switch in Settings → Product Profile, or run ./start.sh --profile creator. Details are in backend/profiles/README.md; building a distribution of your own is docs/EXTENSIONS.md.

Find your way around

Much of the interface is one right-click, drag or key away: menus on dashboard cards and most lists, cards you move and resize, files dropped straight into Files or an image into chat, a floating chat that knows which page you are on, hands-free voice, and ? for the keyboard shortcuts. docs/interface.md walks through all of it.

Making it fast

Chat and agent latency depend on a few settings, all in Settings unless noted. The defaults favor visibility while you learn the system; flip these once you trust it:

• Thinking mode off. Extended reasoning (/thinking, or the chat-thinking default in Settings) adds a long deliberation pass to every turn. Off, simple turns answer in a second or two.
• Developer toggles off. RAG Debug, Verbose Logging and LLM Debug each add per-request work.
• Pick one reliable model and stay on it. Every model switch evicts and reloads weights on the GPU. A single mid-size model that stays resident beats a bigger one that thrashes.
• Mind the VRAM neighbors. Renders wait for the card, but idle services holding VRAM (voice models, image pipelines) slow everything's admission. The Plugins page shows who holds what.

CLI

pip install guaardvark

The package is the guaardvark command, built with Typer, Rich and prompt_toolkit (Episode 20 walks through it). It talks to a running backend on the configured port, or starts one with start.sh from a checkout it finds through GUAARDVARK_ROOT or the current directory; with no checkout it stops with "Guaardvark installation not found". An MCP client can start the server with guaardvark mcp serve from a pip install plus a checkout.

guaardvark                              # Interactive REPL
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
guaardvark plugins list                 # ComfyUI / Ollama / …
guaardvark gpu status                   # VRAM and owner lock
guaardvark mcp install --client cursor  # Wire Guaardvark into Cursor
guaardvark completion zsh               # Shell completion script

/imagine <prompt>       Generate an image (inline preview in Kitty/iTerm)
/video <prompt>         Generate a video from text
/voice <text>           Text-to-speech (plays locally)
/agent [on|off|shot]    Screen-agent mode; shot = desktop screenshot
/web [images|chat]      Open the web UI on the real frontend port
/ingest <path>          Index files or directories for RAG
/plugins list|start     GPU / service plugins
/gpu status|release     VRAM and owner lock
/audio tts|music|sfx    Audio Foundry
/swarm run <prompt>     Parallel agents in worktrees
/lessons begin|end      Lesson pearls
/skills                 List SKILL.md files
/help [query]           Full command reference, or one command

Architecture

Browser / CLI (PyPI: guaardvark) / MCP Client (Claude Desktop, Cursor, etc.)
    | HTTP + WebSocket / stdio MCP
    v
Flask (~100 API blueprints, 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 + 100+ registered tools + 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

Roadmap

Near term

• A hand-editable timeline in the video editor: drag to reorder, a transition per cut, and text overlays in the plan.
• Every pipeline starting its own services (music video, Film Crew, images, audio), the way video renders already start ComfyUI.
• Memory and context budgets sized to the model, and semantic memory recall with embeddings.
• Outreach posting on X, verified end to end.
• Sending a song from Audio Studio straight to the Music Video page.

Longer term

• A cluster dashboard for multi-machine setups: fleet, routing and live node state.
• AST-level code tools for JavaScript and TypeScript.
• Singing voice cloning with consent and watermarking.

Not on the roadmap: cloud-by-default or a SaaS-hosted primary experience. Local-first is the product.

FAQ

Does Guaardvark send my data anywhere? No, not unless you turn something on. Models run locally, and every outbound path (model downloads, web search, posting, the Discord bot, a remote Ollama) is declared in egress.json and stays off until a setting or a person starts it.

Does it work offline? Yes, once the models you use are downloaded. Only features that reach other services by design, such as web search, posting and the Discord bot, need a connection.

What hardware do I need? Linux with one NVIDIA GPU. Chat, RAG, voice and the coding swarm run CPU-only; 8–12 GB adds vector RAG, screen agents, images, upscaling and music; video generation needs a 16 GB-class card. Details in docs/HARDWARE.md.

Does it run on macOS or Windows? Apple Silicon is supported, with GPU features arriving through Metal; see INSTALL.md. Windows through WSL2 is being verified.

Can I use it from Claude Code, Cursor or Codex? Yes. Install the Claude Code plugin with the two lines in Quick start, or run python -m backend.mcp install to wire the MCP server into every agent client it finds. See MCP server, agent skills and the Claude Code plugin.

How is it different from ComfyUI or Open WebUI? They are excellent at one slice each. Guaardvark puts chat, RAG, agents, coding swarms and the whole media pipeline in one install that shares one GPU, and it hands off to ComfyUI with one click when you want the node graph. See How Guaardvark compares.

Is it free? Yes. Guaardvark is open source under the MIT License, and running it costs nothing beyond your own hardware and power.

Get Involved

Guaardvark is open source (MIT) and built in public. Whether you want to try the bot, ship a small PR, or report what broke on your machine, here is the short path.

1. Join the community

2. Run it

Use the one-line Quick start or install by hand: Web UI → http://localhost:5173 · API → http://localhost:5000 (macOS: 5055).
Details: INSTALL.md · agent mental model · full feature list: CAPABILITIES.md

3. Pick a good first issue

Starter issues carry the good first issue label, each with acceptance criteria and a clear out of scope list. When none are open, the safe zones below are the best place to start.

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

4. Safe vs high-risk contribution zones

Agent recipes, rule and lesson bundles, skills and agent instruction files are maintainer-written; to get a new behaviour, open an issue describing it. Full setup, style, and PR expectations: CONTRIBUTING.md.

Coding agents that use Guaardvark start at AGENTS.md and its operating contract, AGENT_GUIDE.md. Contributors, human or agent, follow CONTRIBUTING.md; inside the product, every AI code write goes through one verified gate, guarded_code_service.py::apply_exact_replacement.

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 your GPU model and logs from logs/ (an issue, or email support@guaardvark.com)
• Suggest workflows you wish worked out of the box

Support the Project

If Guaardvark is useful to you, you can support its development:

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

Star the repo if you find it interesting; it helps others find it.

Questions, install trouble, or feedback: support@guaardvark.com. Press, partnerships, and business: info@guaardvark.com.

License

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

"Guaardvark"™ and the Guaardvark logo are trademarks of Albenze, Inc. The MIT License covers the code, not the name; see TRADEMARK.md for what you may do with the name without asking.