FSS Link

FSS Link is a terminal-based AI coding agent built for local-first model support and practical tooling in a solo developer's workflow. It reads your codebase, runs tools, and helps you build software — connecting to local models (LM Studio, vLLM) or cloud APIs (OpenAI, Gemini) with full access to file operations, web scraping, search, and shell commands.

What it does

FSS Link is a terminal-based AI assistant that reads your codebase, runs tools, and helps you build software. It connects to local models (LM Studio, vLLM) or cloud APIs (OpenAI, Gemini) and gives the model access to file operations, web scraping, search, and shell commands.

Key capabilities include:

• Local model priority — LM Studio and vLLM as first-class providers, not afterthoughts
• Database-backed model config — switch models via CLI flags, settings persist across sessions
• Web scraper tool — search and extract web content from within the agent
• TTS integration — audio feedback during long-running tasks via multi-voice TTS
• Image generation tool — generate images via CLI from within the agent
• Vision support — send images to vision-capable models with automatic format conversion and resizing
• Custom agents — named agent personalities with distinct roles (research, testing, implementation, etc.)
• Private IP support — works with vLLM/LM Studio on local network without SSL errors

Installation

Requires Node.js 20+.

# From npm
npm install -g fss-link

# From source
git clone https://github.com/FSScoding/fss-link.git
cd fss-link
npm install
npm run bundle
sudo npm install -g .

First run — bootstrap the database

The database (~/.fss-link/fss-link.db) is created on the first command that needs it, not during npm install. If fss-link fails with "Database directory not found" or "Cannot save database", run:

fss-link --version

This is the quickest way to bootstrap everything — it creates the directory, initialises the schema, and inserts default model configs. After that, fss-link (interactive) and fss-link -p "..." will work normally.

Usage

# Interactive mode
fss-link

# One-shot prompt
fss-link -p "refactor the error handling in src/api.ts"

# Specify provider and model
fss-link --provider lm-studio --model qwen3-coder:latest
fss-link --provider openai-api-key --model gpt-4o -p "review this PR"

# Non-interactive with auto-approval
fss-link -p "fix the failing tests" --approval-mode yolo

Slash commands

| Command | Description | |---|---| | /setup-search | Configure Brave Search and Tavily API keys for web search | | /auth | Set up authentication method and model | | /model | Switch between available models | | /theme | Change the UI theme | | /permissions | Manage project-scoped shell permissions (list, revoke) | | /help | List all available slash commands |

Providers

| Provider | Flag | Notes | |---|---|---| | LM Studio | --provider lm-studio | Local, port 1234 | | vLLM / OpenAI-compatible | --provider bob-ai | Local or network | | OpenAI | --provider openai-api-key | Requires OPENAI_API_KEY | | Gemini | --provider gemini-api-key | Requires GEMINI_API_KEY | | BobAI Proxy | --provider bob-ai | Custom proxy endpoint | | Vertex AI | --provider vertex-ai | Google Cloud | | Qwen OAuth | --provider qwen-oauth | Built-in OAuth flow |

Model and provider settings persist to a local SQLite database. Once set, you don't need to specify them again.

Configuration hierarchy

1. CLI flags (--provider, --model) — highest priority
2. Database — persistent settings from previous sessions
3. Environment variables — traditional fallback

Project structure

packages/
  cli/          # CLI entry point, config, model management
  core/         # Tools, services, content generation, utilities
fss-tools/
  webscraper/   # Python-based web scraper with search integration
scripts/        # Build and utility scripts
docs/           # Published documentation
fss-docs/       # Internal development reference

Building from source

# Bundle (esbuild, bundles directly from TS source)
npm run bundle

# Install globally
sudo npm install -g .

esbuild bundles directly from TypeScript source into bundle/fss-link.js. Do not run bare tsc — see issue #64.

Current version

v1.9.1 — see CHANGELOG.md for history.

License

Apache 2.0

Acknowledgments

FSS Link traces its origins to QwenCode, which itself builds on Google Gemini CLI. The two projects have since diverged significantly — FSS Link has evolved independently with a different architecture, tool set, and direction.