FSS Link 🔗

Spin up links. Get work done. 🚀

FSS Link is a portable, scriptable agent that links tools, models, and knowledge into multi-instance workflows. Install anywhere with Node.js, launch 1-8 agents at once, feed them templated tasks, and watch them go.

• Lightweight distribution (~15 MB bundle, requires Node.js 20+)
• Spawn many agents with structured prompts
• Portable Mini-RAG indices that travel with your projects
• Local-first with LM Studio/Ollama priority
• Professional tools built in TypeScript for seamless integration

🎯 Why "Link"?

Link connects things—tools, models, tasks, and knowledge. FSS Link is a lightweight distribution that runs wherever Node.js is installed. Start an agent, or spawn eight in parallel with templated prompts. Each project carries its own Mini-RAG index, so knowledge travels with the work.

🚀 Quick Start

# Interactive mode
fss-link

# Single-shot task
fss-link run "Audit the repo for security keys and open PR fixes."

# Launch 6 parallel agents with templated plan
fss-link spawn --count 6 --template ./templates/regression.yml

# Portable RAG - indexes travel with projects
cd project && fss-link rag index . && fss-link rag query "error handling"

⚡ NEW: UNIFIED PROVIDER SYSTEM (v1.0.54)

Zero complexity model switching! Complete provider/model management unification with eliminated spaghetti code:

# Quick Ollama tasks
fss-link --provider ollama --model qwen3:4b -p "explain this code"
fss-link --provider ollama --model qwen3-coder:latest -p "refactor this function"

# LM Studio for specialized models  
fss-link --provider lm-studio --model llama-3.1-8b -p "write documentation"

# OpenAI for advanced reasoning
fss-link --provider openai-api-key --model gpt-4o -p "complex analysis task"

# Gemini for multimodal tasks
fss-link --provider gemini-api-key --model gemini-2.0-flash-thinking -p "analyze this image"

# Google Cloud providers (NEW)
fss-link --provider vertex-ai --model gemini-1.5-pro -p "enterprise analysis"
fss-link --provider oauth-personal --model gemini-flash -p "personal tasks"
fss-link --provider cloud-shell --model default -p "cloud development"

🎯 All 8 Providers Supported

• ollama - Local Ollama server (default port 11434)
• lm-studio - LM Studio server (default port 1234)
• openai-api-key - OpenAI API (requires API key)
• gemini-api-key - Google Gemini API (requires API key)
• vertex-ai - Google Vertex AI (enterprise)
• oauth-personal - Google OAuth (personal)
• cloud-shell - Google Cloud Shell
• qwen-oauth - FSS Link OAuth

🔄 Fallback Hierarchy

1. CLI Arguments - --provider and --model flags (highest priority)
2. Database Configuration - Persistent model settings
3. Environment Variables - Traditional env var fallback

📦 Installation

FSS Link v1.0.54 is now published to NPM with UNIFIED PROVIDER SYSTEM! Install it globally for the best experience:

# Method 1: NPM Global Install (Recommended)
npm install -g fss-link

# Now you can use fss-link anywhere
fss-link --help
fss-link --version  # Should show v1.0.54

🎉 NEW: Welcome Back System (v1.0.43)

FSS Link now features an intelligent Welcome Back dialog that appears when you return to projects with existing history:

• 🔍 Project Status Dashboard - Git status, session history, momentum analysis
• 📊 Smart Context Generation - Priority-based information filtering (7 levels)
• ⚡ Multi-Agent Awareness - Universal session tracking across all agents
• 🎯 Seamless Resumption - Intelligent context population for continuing work
• 🚀 Production Quality - Comprehensive error handling, performance optimization

🔄 Node.js Version Requirements

FSS Link requires Node.js 20+. If you have an older version, upgrade first:

# Check your current Node version
node --version

# If you have Node 18 or older, upgrade to Node 20:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install nodejs -y

# Verify upgrade
node --version  # Should show v20.x.x
npm --version   # Should show v10.x.x

# Method 2: Clone and Build from Source (Development)
git clone http://192.168.1.3:3000/foxadmin/fss-link.git
cd fss-link
npm install
npm run build

# Install globally for 'fss-link' command
npm link

# Now you can use fss-link anywhere
fss-link --help

# Method 3: Run without installing globally
npx fss-link
# OR from source
cd fss-link
npx fss-link

✅ Note: FSS Link is now published to npm as fss-link v1.0.54!

🔧 Enhanced Features & Tools

This agent extends FSS Link v0.0.10+ with professional development tools and intelligent workflow automation:

🧠 TypeScript Mini-RAG System

Built-in semantic search that travels with your projects. No Python dependencies, no setup complexity.

• Deep Semantic Search: Find code by describing what it does, not just what it's called
• Cross-Reference Analysis: Discover how different parts of the system interact
• Context-Aware Suggestions: Get recommendations based on the entire project context
• Portable Indices: Knowledge travels with your projects

📋 Enhanced Task Management

Built on FSS Link's native TodoWrite tool with professional enhancements for complex development workflows.

• Persistent Task Lists: Never lose track of what needs to be done
• Visual Progress Indicators: Instantly see what's complete, in-progress, or pending
• Intelligent Task Breakdown: Automatically decompose complex features into actionable steps
• Multi-Agent Coordination: Tasks shared across multiple agent instances

🔍 Professional Web Research

TypeScript-native web research tools eliminate context switching between development and external resources.

• Integrated Research: Gather documentation without leaving the development workflow
• Content Processing: Smart extraction and summarization of technical content
• Project Memory: Maintain research context across sessions

🎵 Voice Feedback System

Long-running operations need progress updates. Audio feedback enables multitasking during complex automated tasks.

• TTS Integration: Stay informed about progress without watching the screen
• Multi-Voice Support: Assign different voices to different types of work
• Bluetooth Audio: Use wireless speakers for clear feedback

⚡ Local Model Optimization

Designed for local-first development with intelligent model switching.

• LM Studio Priority: Optimized for local inference workflows
• Ollama Secondary: Fallback for different model architectures
• Cloud Enhancement: Remote models as capability extension, not dependency

🖥️ Local Model Recommendations

Based on extensive testing with the FSS Enhanced FSS Link prototype:

⚡ High-Speed Development - qwen/qwen3-4b-2507

• Performance: 120+ tokens/second on dual RTX 3090 setup
• Context Window: 190k tokens with KV quantisation + Flash Attention
• Best for: Code completion, refactoring, documentation, analysis
• Experience: Comparable to Gemini Flash with enhanced system prompts

🧠 Complex Problem Solving - qwen/qwen3-30b-a3b-2507

• Performance: Slower but significantly more capable reasoning
• Context Window: 131k tokens with KV quantisation + Flash Attention
• Best for: Architecture decisions, complex debugging, system design
• When to use: Multi-step problems requiring deep analysis

🚀 CLI Commands

Interactive Mode

# Launch FSS Link interactive shell
fss-link

# Launch with specific model
fss-link --model qwen/qwen3-4b-2507

# Launch with RAG index
fss-link --rag ./project-index

Single-Shot Execution

# Execute prompt and exit
fss-link run "Analyse this codebase structure"

# With specific model
fss-link run "Review security patterns" --model qwen/qwen3-30b-a3b-2507

# With RAG context
fss-link run "Find authentication bugs" --rag .

Multi-Agent Workflows

# Launch multiple agents with template
fss-link spawn --count 8 --template ./templates/build-test.yml

# Parallel code review
fss-link spawn --count 4 --template ./templates/code-review.yml --files src/

# Load-balanced task processing
fss-link spawn --count 6 --template ./templates/regression-test.yml

RAG Operations

# Index current directory
fss-link rag index .

# Index with specific extensions
fss-link rag index . --extensions py,js,md

# Query with filters
fss-link rag query "authentication logic" --topk 5

# Cross-reference search
fss-link rag query "error handling patterns" --files py,js --recent

📦 Installation

Prerequisites

• Node.js 20+
• LM Studio or Ollama (recommended for local models)

Quick Install

# Install from npm (Published v1.0.13)
npm install -g fss-link

# Or clone from source for development
git clone http://192.168.1.3:3000/foxadmin/fss-link.git
cd fss-link
npm install && npm run build && npm link

# Verify installation
fss-link --version  # Should show v1.0.54

⚙️ Configuration

Model Profiles

# List available profiles
fss-link profiles list

# Create new profile
fss-link profiles add local-fast --model qwen/qwen3-4b-2507 --provider lm-studio

# Set default profile
fss-link profiles default local-fast

Core Providers

• Qwen OAuth - 2000 requests/day free tier
• OpenAI Compatible - OpenRouter, custom endpoints, local APIs
• Local Models - LM Studio/Ollama priority for privacy and speed

🛠️ Database System Status

✅ PRODUCTION READY: Async locking system implemented and verified
✅ Statement Closed Errors: ELIMINATED via comprehensive async locking
✅ 44/44 Critical Tests: All async locking tests passing
✅ Auth System: Race conditions eliminated, reliable model switching
✅ Production Validation: Complete - zero database errors under load

Implementation Complete: See fss-docs/DATABASE-ASYNC-LOCKING-PLAN.md for full details.

🔧 Development Philosophy

Fresh Fork Strategy

FSS Link builds on FSS Link v0.0.10+ using a clean fork approach:

1. Start Clean: Fork latest upstream for stable foundation
2. TypeScript Native: Build tools in TypeScript for seamless integration
3. Selective Enhancement: Add value without complexity explosion
4. Professional Focus: Target professional development workflows

Tool Integration Principles

• No Python Dependencies: Everything builds with npm
• Portable by Design: Works anywhere Node.js runs
• Performance First: Local models, fast feedback, efficient workflows
• Professional Quality: Battle-tested, reliable, focused on core needs

🎨 Brand & Visual Identity

• Colour: Emerald #10B981 (linking/connection theme)
• Background: Slate #0F172A
• Accent: Green headers, dim slate separators
• Icon: Chain-link with spark (🔗⚡)
• Tagline: "Spin up links. Get work done."

📄 License

Apache 2.0

🌟 Acknowledgments

FSS Link builds on QwenLM/fss-link, which itself builds upon Google Gemini CLI. We acknowledge and appreciate the excellent work of both teams.

FSS Link - Portable, scriptable, multi-instance AI agent

Documentation • Installation Guide • Examples