L.I.N.K

Local Intelligent Network Knowledge — Just A Rather Very Intelligent System

A local-first AI development assistant with a web-based command center, featuring code analysis, self-generated knowledge base, multi-agent delegation, and secure sandboxed execution.

Quick Install · Development · Documentation · Contributing

---

Features

• Multi-Provider LLM — Gemini, OpenAI, Anthropic, DeepSeek, Groq, Mistral, Ollama (local)
• Agent Registry — Create, save, and run custom AI agents with configurable toolsets
• Sub-Agent Delegation — Hierarchical multi-agent execution with depth limiting and trace capture
• Self-Generated Knowledge Base — Markdown wiki + knowledge graph auto-built from your codebase
• Secure Sandbox — All execution runs inside Docker with path boundary enforcement
• Human-in-the-Loop — Mutating commands (rm, pip install, file overwrites) require explicit approval
• Chat-Based Creation — Create agents, skills, and workflows via natural language
• Memory & Context — Conversation history, session persistence, and smart context injection

Quick Install (End Users)

One-Line Install (macOS / Linux)

bash <(curl -fsSL https://raw.githubusercontent.com/pongpitag/link-agent/main/scripts/install.sh)

The script will:

1. Check for Docker
2. Clone the repo to ~/.link
3. Prompt for API Key interactively (or skip to use Ollama)
4. Build & start L.I.N.K automatically

Open your browser at http://localhost:5173 when ready.

Manual Docker Install

# 1. Clone repo
git clone https://github.com/pongpitag/link-agent.git ~/.link
cd ~/.link

# 2. Create environment file
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

# 3. Build & Start
docker compose -f docker-compose.prod.yml up --build -d

# 4. Open browser
open http://localhost:5173

Requirements

• Docker & Docker Compose (only requirement for end users)
• At least one AI Provider (all have free tiers):
  • Google Gemini (recommended, free tier)
  • Ollama (local, no key needed)
  • Groq (free tier, very fast)
  • OpenAI
  • Anthropic

Useful Commands

cd ~/.link

# Stop
docker compose -f docker-compose.prod.yml down

# View logs
docker compose -f docker-compose.prod.yml logs -f

# Update to latest
git pull origin main && docker compose -f docker-compose.prod.yml up --build -d

# Uninstall — WARNING: deletes ALL workspace data permanently
# Back up first: bash ~/.link/scripts/backup.sh
docker compose -f docker-compose.prod.yml down --volumes
rm -rf ~/.link

Maintainer release workflow

If you maintain this repository as a private workspace, do not publish it directly as an end-user repo. Generate a filtered public package first.

# 1) Export a clean public snapshot
bash scripts/export_public_release.sh

# 2) Create and push a clean public repo from that snapshot
bash scripts/publish_public_release.sh <PUBLIC_REPO_URL>

This workflow excludes internal development-only surfaces (for example docs/ADR, local runtime data, and private agent context files) while keeping runtime code, installers, and end-user docs.

---

Development Setup

For developers who want to hack on the code.

Prerequisites

• Docker + Docker Compose
• Node.js 20+
• Python 3.11+
• Gemini API Key (Google AI Studio)

1. Clone & Configure

git clone https://github.com/pongpitag/link-agent.git
cd link-agent
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

2. Start with Docker (Recommended)

# Start all services
docker-compose up --build

# Access:
# Frontend: http://localhost:5173
# API Docs: http://localhost:8000/docs

3. Or Start Manually (Development)

# Terminal 1: Backend
cd backend
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

# Terminal 2: Frontend
cd frontend
npm install
npm run dev

---

Architecture

Layer	Technology
Frontend	React 18 + Vite + Tailwind CSS
Backend	Python 3.11 + FastAPI
LLM Engine	Multi-Provider: Gemini, OpenAI, Anthropic, DeepSeek, Groq, Mistral, Ollama
Knowledge	Markdown wiki (/wiki) + Knowledge Graph (GRAPH_REPORT.md)
Execution	Docker Container (sandboxed)

Project Structure

link/
├── backend/              # FastAPI application
│   ├── main.py           # API endpoints
│   ├── src/
│   │   ├── config.py     # Settings (env-based)
│   │   ├── llm_client.py # Multi-provider LLM client
│   │   ├── models.py     # Pydantic schemas
│   │   ├── security.py   # Path validation, command classification
│   │   ├── hitl.py       # Human-in-the-Loop approval system
│   │   ├── agent.py      # Agentic workflow orchestrator
│   │   ├── agent_registry.py # Agent CRUD persistence
│   │   ├── tools.py      # Tool registry & execution
│   │   ├── graphify.py   # Code structure analyzer
│   │   ├── wiki.py       # Wiki generation & index management
│   │   ├── personas.py   # AI persona registry
│   │   ├── memory.py     # Conversation memory system
│   │   └── pre_tool_hook.py # Context injection middleware
│   └── tests/            # Pytest test suite
├── frontend/             # React application
│   ├── src/
│   │   ├── App.jsx       # Main app
│   │   ├── api.js        # Backend API client
│   │   ├── providers.js  # AI provider registry (7 providers, 35+ models)
│   │   ├── hooks/        # useChat, useOnboarding, useApiHealth
│   │   └── components/
│   │       ├── layout/   # Header, NavBar, AppLayout
│   │       ├── views/    # Chat, Files, Knowledge, Graph, Docs, Settings, Agents
│   │       ├── modals/   # SetupWizard, HitlModal
│   │       └── panels/   # ContentPanel, SynthesisPanel, AgentPanel
├── wiki/                 # Auto-generated knowledge entries
├── raw_sources/          # Read-only source files for analysis
├── docs/                 # SRS, ADR, API Reference, User Guide, Security
├── scripts/              # install.sh, uninstall.sh, version.sh
└── docker-compose.yml    # Full stack orchestration

API Endpoints

Chat

Method	Endpoint	Description
POST	/chat	Send message to LLM (auto-loads context + memory + persona)
POST	/chat/stream	Stream response via SSE

Agent

Method	Endpoint	Description
POST	/agent/run	Run agentic workflow with optional agent config
GET	/agents	List registered agent configurations
POST	/agents	Create new agent config
PUT	/agents/{id}	Update agent config
DELETE	/agents/{id}	Delete agent config

Tools

Method	Endpoint	Description
POST	/tools/read-file	Read file within workspace
POST	/tools/write-file	Write file (HITL for overwrites)
POST	/tools/execute-shell	Run shell command (HITL for mutating)

Settings

Method	Endpoint	Description
GET	/settings	Get current config (API keys masked)
POST	/settings	Update config
GET	/personas	List available AI personas

Memory

Method	Endpoint	Description
GET	/memory/conversations	List conversation history
GET	/memory/conversations/{file}	Read specific conversation

Knowledge

Method	Endpoint	Description
POST	/knowledge/refresh-graph	Regenerate GRAPH_REPORT.md
POST	/knowledge/generate-wiki	Create wiki entry from content
POST	/knowledge/update-index	Refresh wiki/index.md

Security Features

1. Docker Sandbox — Backend runs inside container, never on host OS
2. Directory Boundary — All file ops restricted to working directory
3. Human-in-the-Loop — Mutating commands (rm, pip install, file overwrites) require explicit UI approval
4. Localhost Only — Backend binds to 127.0.0.1, never 0.0.0.0
5. API Key Masking — Keys are never returned in plaintext from settings API
6. Zero Secrets in Source — .env is gitignored; only .env.example is committed

Commands

# Development
make dev              # Start backend + frontend
make dev-backend      # Backend only
make dev-frontend     # Frontend only

# Code Quality
make format           # Format all code (Ruff + Prettier)
make lint             # Lint all code
make test             # Run tests

# Build
make build            # Build Docker images
make clean            # Clean build artifacts

Documentation

• User Guide — Full feature walkthrough
• Developer Guide — Architecture & contribution guide
• API Reference — API documentation
• Setup Guide — Installation & troubleshooting
• Security — Threat model & security architecture
• Software Requirements — Software Requirements Specification

Contributing

We welcome contributions! Please read our Contributing Guide and Code of Conduct before submitting issues or pull requests.

License

This project is licensed under the MIT License.