npm package: @fsscoding/fss-link-core
Description: FSS Link Core
Latest version: 1.0.31

# FSS Link 🔗

<div align="center">

[![FSS Link](https://img.shields.io/badge/FSS-Link-emerald.svg)](https://github.com/FSSCoding/fss-link)
[![TypeScript Tools](https://img.shields.io/badge/TypeScript-Tools-blue.svg)](https://github.com/FSSCoding/fss-link)
[![RAG Integration](https://img.shields.io/badge/RAG-Integrated-purple.svg)](https://github.com/FSSCoding/fss-link)
[![Voice Feedback](https://img.shields.io/badge/Voice-Enabled-orange.svg)](https://github.com/FSSCoding/fss-link)
[![Local Models](https://img.shields.io/badge/Local-Models-red.svg)](https://github.com/FSSCoding/fss-link)

**Spin up links. Get work done.** 🚀

</div>

**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

```bash
# 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"
```

## 📦 Installation

**FSS Link v1.0.2 is now published to NPM! Install it globally for the best experience:**

```bash
# Method 1: NPM Global Install (Recommended)
npm install -g @fsscoding/fss-link

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

```bash
# 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
```

```bash
# Method 3: Run without installing globally
npx @fsscoding/fss-link
# OR from source
cd fss-link
npx fss-link
```

**✅ Note**: FSS Link is now published to npm as `@fsscoding/fss-link` v1.0.2!

## 🔧 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# Install from npm (Published v1.0.2)
npm install -g @fsscoding/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.2
```

## ⚙️ **Configuration**

### **Model Profiles**
```bash
# List available profiles
fss-link profiles list

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

# 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

## 🔧 **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](./LICENSE)

## 🌟 **Acknowledgments**

FSS Link builds on [QwenLM/fss-link](https://github.com/QwenLM/fss-link), which itself builds upon [Google Gemini CLI](https://github.com/google-gemini/gemini-cli). We acknowledge and appreciate the excellent work of both teams.

---

<div align="center">

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

[Documentation](./FSS-LINK-IMPLEMENTATION-GUIDE.md) • [Installation Guide](./INSTALL.md) • [Examples](./examples/)

</div>