🧠 Farnsworth: Your Claude Companion AI

9crfy4udrHQo8eP6mP393b5qwpGLQgcxVg9acmdwBAGS

🎯 What is Farnsworth?

Farnsworth is a companion AI system that integrates with Claude Code to give Claude capabilities it doesn't have on its own:

All processing happens locally on your machine. Your data never leaves your computer.

⚔️ See how Farnsworth compares to other agents (Clawdbot, Marge, etc.)

✨ What's New in v2.1.0 (The Skill Swarm)

• 🦝 Grok X Search - Real-time X (Twitter) search and deep thinking via xAI
• 🎬 Remotion Video - Programmatic React-based video generation and rendering
• ⚡ Parallel AI - High-reliability consensus via multi-model concurrent dispatch
• 📈 Financial Intelligence - DexScreener, Polymarket, & Pump.fun/Bags.fm tracking
• 💹 Market Sentiment - Crypto Fear & Greed index and global market macro
• 📺 YouTube Intelligence - Transcript extraction and semantic video analysis
• 🧩 Sequential Thinking - Systematic "Chain-of-Thought" reasoning tool
• 🗄️ Database Manager - Secure, read-only SQL access to local/remote databases
• 🔌 Discord Bridge - Full "ChatOps" integration for remote commanding
• 📊 Mermaid Diagrams - Native architecture and flowchart visualization
• 🦾 Agentic OS - Deep system diagnostics and process management
• 🧙 Granular Setup Wizard - Step-by-step feature control (python main.py --setup)
• 🎥 Video v2.1 - Advanced Spatio-Temporal Flow Analysis (Optical Flow)
• 🧠 Synergy Engine - Automated cross-domain learning (GitHub -> Memory -> Projects)
• 🧊 3D Reconstruction - Building spatial mental models from video (SfM)

The Spatio-Temporal Era (v2.0)

• 🎥 Video v2.0 - Duo-Stream Analysis (Visual Saliency + Audio Narrative)
• 🌐 P2P Swarm Fabric - Decentralized agent discovery and Task Auctions (DTA)
• 🧠 Decentralized Knowledge Graph (DKG) - Federated fact-sharing across trust pools

Cutting Edge (v1.6 - v1.9)

• 🎭 Theory of Mind (v1.6) - Predictive Coding simulation of user intent
• 👁️ Visual Intelligence (v1.7) - Visual Debugger & Diagram Understanding
• 📅 Personal Assistant (v1.8) - Meeting Prep & Learning Co-Pilot
• 🔗 Connected Ecosystem (v1.9) - Integrations with GitHub, Notion, O365, X, n8n
• 🧠 Neuromorphic Core (v1.4) - Sparse Distributed Memory & Hebbian Learning
• 🦾 Agentic OS (v1.4) - Deep system context awareness bridge
• ♾️ Continual Learning (v1.5) - Experience Replay & Elastic Consolidation
• 🔮 Causal Reasoning (v1.5) - Causal graphs, interventions, and counterfactuals

Previously Added

• 🖼️ Multimodal - Vision (CLIP/BLIP) & Voice (Whisper) support
• 📦 Docker Support - One-command deployment with GPU support
• 👥 Team Collaboration - Shared memory pools, multi-user sessions
• 🔍 Advanced RAG - Hybrid search with semantic layers

🛠️ Usage & Examples

📈 Financial Intelligence

Ask Farnsworth about any token or market:

• "Check the price and liquidity of $SOL on DexScreener."
• "What's the bonding curve progress for [MINT_ADDRESS] on pump.fun?"
• "Show me the trending tokens on bags.fm."
• "What are the current odds on Polymarket for the next SpaceX launch?"

🎬 Video & Diagrams

• "Generate a Remotion video script summarizing our last project."
• "Create a Mermaid sequence diagram showing the P2P handshake protocol."

🧩 Systematic Reasoning

• "Explain quantum tunneling using the Sequential Thinking tool."

🐝 Model Swarm: Collaborative Multi-Model Inference

The Model Swarm system enables multiple small models to work together, achieving better results than any single model:

Swarm Strategies

🏗️ Architecture & Privacy

Farnsworth runs 100% locally on your machine.

• No Server Costs: You do not need to pay for hosting.
• Your Data: All memories and files stay on your computer.
• How it connects: The Claude Desktop App spawns Farnsworth as a background process using the Model Context Protocol (MCP).

Supported Models (Jan 2025)

Hardware Profiles

Farnsworth auto-configures based on your hardware:

minimal:     # <4GB RAM: TinyLlama, Qwen3-0.6B
cpu_only:    # 8GB+ RAM, no GPU: BitNet, SmolLM2
low_vram:    # 2-4GB VRAM: DeepSeek-R1, Qwen3-0.6B
medium_vram: # 4-8GB VRAM: Phi-4-mini, Qwen3-4B
high_vram:   # 8GB+ VRAM: Full swarm with verification

⚡ Quick Start

📦 Option 1: One-Line Install (Recommended)

Farnsworth is available on PyPI. This is the easiest way to get started.

pip install farnsworth-ai

Running the Server:

# Start the MCP server
farnsworth-server

# Run the GRANULAR setup wizard
python main.py --setup

🛡️ Isolated Mode

For maximum privacy, Farnsworth can run in complete isolation:

• Set FARNSWORTH_ISOLATED=true in your .env
• All P2P discovery and network broadcasting is HARD-DISABLED.
• Perfect for offline usage or highly sensitive environments.

🐳 Option 2: Docker

git clone https://github.com/timowhite88/Farnsworth.git
cd Farnsworth
docker-compose -f docker/docker-compose.yml up -d

🛠️ Option 3: Source (For Developers)

git clone https://github.com/timowhite88/Farnsworth.git
cd Farnsworth
pip install -r requirements.txt

🔌 Configure Claude Code

Add to your Claude Code MCP settings (usually found in claude_desktop_config.json):

For PyPI Install:

{
  "mcpServers": {
    "farnsworth": {
      "command": "farnsworth-server",
      "args": [],
      "env": {
        "FARNSWORTH_LOG_LEVEL": "INFO"
      }
    }
  }
}

📖 Full Installation Guide →

🌟 Key Features

🧠 Advanced Memory System

Claude finally remembers! Multi-tier hierarchical memory:

🤖 Agent Swarm (11 Specialists)

Claude can delegate tasks to AI agents:

🖼️ Vision Understanding (v0.4+)

See and understand images:

• CLIP Integration - Zero-shot classification, image embeddings
• BLIP Integration - Captioning, visual question answering
• OCR - Extract text from images (EasyOCR)
• Scene Graphs - Extract objects and relationships
• Image Similarity - Compare and search images

🎤 Voice Interaction (v0.4+)

Hear and speak:

• Whisper Transcription - Real-time and batch processing
• Speaker Diarization - Identify different speakers
• Text-to-Speech - Multiple voice options
• Voice Commands - Natural language control
• Continuous Listening - Hands-free mode

👥 Team Collaboration (v0.4+)

Work together with shared AI:

• Shared Memory Pools - Team knowledge bases
• Multi-User Support - Individual profiles and preferences
• Permission System - Role-based access control
• Collaborative Sessions - Real-time multi-user interaction
• Audit Logging - Compliance-ready access trails

📈 Self-Evolution

Farnsworth learns from your feedback and improves automatically:

• Fitness Tracking - Monitors task success, efficiency, satisfaction
• Genetic Optimization - Evolves better configurations over time
• User Avatar - Builds a model of your preferences
• LoRA Evolution - Adapts model weights to your usage

🔍 Smart Retrieval (RAG 2.0)

Self-refining retrieval that gets better at finding relevant information:

• Hybrid Search - Semantic + BM25 keyword search
• Query Understanding - Intent classification, expansion
• Multi-hop Retrieval - Complex question answering
• Context Compression - Token-efficient memory injection
• Source Attribution - Confidence scoring

📊 Project Tracking (v1.2+)

Turn conversations into concrete progress:

• Auto-Detection - Identifies new projects from natural conversation
• Task Management - Tracks dependencies, priorities, and status
• Milestone Tracking - Monitors progress towards key goals
• Cross-Project Knowledge - Transfers learnings between related projects
• Smart Linking - Semantically links related initiatives

🛠️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Claude Code                             │
│              (The User Interface)                           │
└─────────────────────────────────────────────────────────────┘
                              │ FCP Context Injection
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Farnsworth Nexus                          │
│                (The Neural Event Bus)                       │
│                                                             │
│  ┌──────────┐   Signals    ┌──────────┐   Signals           │
│  │ Agents   │ ◄──────────► │ FCP      │ ◄──────────► User   │
│  │          │              │ Engine   │              State  │
│  └──────────┘              └──────────┘              Files  │
│       ▲                          │                          │
│       │                          ▼                          │
│       │             ┌─────────────────────────┐             │
│       │             │ Vision | Focus | Horizon│             │
│       │             └─────────────────────────┘             │
│       │                                                     │
│       ▼                                                     │
│  ┌──────────┐              ┌──────────┐                     │
│  │ Resilience│             │ Omni-    │                     │
│  │ Layer     │             │ Channel  │ ◄────► Discord/Slack│
│  └──────────┘              └──────────┘                     │
└─────────────────────────────────────────────────────────────┘

🔧 Tools Available to Claude

Once connected, Claude has access to these tools:

📦 Docker Deployment

Multiple deployment profiles available:

# Basic deployment
docker-compose -f docker/docker-compose.yml up -d

# With GPU support
docker-compose -f docker/docker-compose.yml --profile gpu up -d

# With Ollama + ChromaDB
docker-compose -f docker/docker-compose.yml --profile ollama --profile chromadb up -d

# Development mode (hot reload + debugger)
docker-compose -f docker/docker-compose.yml --profile dev up -d

See docker/docker-compose.yml for all options.

📊 Dashboard

Farnsworth includes a Streamlit dashboard for visualization:

python main.py --ui
# Or with Docker:
docker-compose -f docker/docker-compose.yml --profile ui-only up -d

🚀 Roadmap

See ROADMAP.md for detailed plans.

Completed ✅

• v0.5.0 - Model Swarm + 12 new models + hardware profiles
• v1.0.0 - Production Release - Performance, reliability, scaling
• v1.1.0 - Conversation Export - multiple formats
• v1.2.0 - Project Tracking - Tasks, milestones, knowledge transfer

Version 2.0.0 - Spatio-Temporal era 🚀

• Video Duo-Stream: Visual Saliency + Audio-Visual Narrative
• 3D Scene Reconstruction: SfM-based sparse point cloud generation
• P2P Swarm: mDNS discovery & Distributed Task Auctions
• DKG: Decentralized Knowledge Graph with CRDT resolution

Version 1.9.0 - Connected Ecosystem 🔗

• External Framework: GitHub, Notion, Calendar, Office365, X (Twitter)
• Universal AI Gateway: Hybrid route to Grok/Gemini/OpenAI
• n8n Bridge: Infinite extensibility via workflows
• IDE Integrations: VS Code LSP & Cursor Shadow Workspace

Coming Next

• 🪐 Planetary Memory (Global shared vector cache)
• 🪐 Biological Neural Interfacing (SDK)

💡 Why "Farnsworth"?

Named after Professor Hubert J. Farnsworth from Futurama - a brilliant inventor who created countless gadgets and whose catchphrase "Good news, everyone!" perfectly captures what we hope you'll feel when using this tool with Claude.

📋 Requirements

Supported Platforms: Windows 10+, macOS 11+, Linux

Optional Dependencies:

• ollama - Local LLM inference (recommended)
• llama-cpp-python - Direct GGUF inference
• torch - GPU acceleration
• transformers - Vision/Voice models
• playwright - Web browsing agent
• whisper - Voice transcription

📄 License

Farnsworth is dual-licensed:

See LICENSE for details. For commercial licensing, contact via GitHub.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Priority Areas:

• Video understanding module
• Cloud deployment templates
• Performance benchmarks
• Additional model integrations
• Documentation improvements

📚 Documentation

• 📖 User Guide - Complete usage documentation
• 🗺️ Roadmap - Future plans and features
• 🤝 Contributing - How to contribute
• 📜 License - License terms
• 🐳 Docker Guide - Container deployment
• 🐝 Model Configs - Supported models and swarm configs

🔗 Research References

Model Swarm implementation inspired by:

• Model Swarms: Collaborative Search via Swarm Intelligence
• Harnessing Multiple LLMs: Survey on LLM Ensemble
• Small Language Models - MIT Tech Review

⭐ Star History

If Farnsworth helps you, consider giving it a star! ⭐