@cognisos/liminal

Transparent LLM context compression proxy. Liminal sits between your AI coding tools and the LLM API, compressing context to save tokens, reduce costs, and extend effective context windows — all without changing your workflow.

Install

npm i @cognisos/liminal

Quick Start

liminal init       # Guided setup — auth, tool detection, config
liminal start      # Start the compression proxy
liminal            # Launch the TUI dashboard

Features

Zero-config compression — Routes through Claude Code, Codex, Cursor, and OpenAI-compatible tools automatically
TUI dashboard — Run liminal to launch a full-screen live dashboard with stats, config, and logs
Setup wizard — 5-step guided setup with verification and error recovery
Stats tracking — Session and all-time metrics with token savings, context extension, and cost estimates
Cursor hooks — Transparent file compression via preToolUse hooks (no sudo, no TLS hacks)
Multi-session — Concurrent session management with circuit breakers and graceful degradation
Zero UI dependencies — All terminal rendering uses raw ANSI codes

Commands

liminal                               Launch TUI dashboard
liminal init                          Guided setup wizard
liminal start [-d] [--port PORT]      Start the compression proxy
liminal stop                          Stop the proxy
liminal status                        Quick health check
liminal stats [--json]                Compression metrics & savings
liminal config [--set k=v] [--get k]  View or edit configuration
liminal logs [--follow] [--lines N]   View proxy logs
liminal setup cursor [--teardown]     Install Cursor compression hooks
liminal login                         Log in or create an account
liminal logout                        Log out
liminal trust-ca                      Install CA cert (TLS intercept)
liminal untrust-ca                    Remove CA cert
liminal uninstall                     Remove all Liminal configuration

TUI Dashboard

Run liminal with no arguments to launch the interactive dashboard:

Dashboard — Live daemon health, tool routing status, session metrics, recent activity
Stats — Token savings, cost impact, context extension (session + all-time)
Config — Current configuration at a glance
Logs — Colorized live tail of daemon logs

Navigate with arrow keys or Tab. Press q to exit.

How It Works

Proxy — Liminal runs a local HTTP proxy (default port 3141)
Intercept — Your AI tool sends API requests through the proxy
Compress — RSC (Recursive Semiotic Computation) normalizes and compresses the context
Forward — Compressed request goes to the upstream LLM API
Learn — Patterns are learned over time to improve compression

Supported protocols: Anthropic Messages API, OpenAI Chat Completions, OpenAI Responses API.

Configuration

Config is stored at ~/.liminal/config.json. Key settings:

Key	Default	Description
`port`	`3141`	Proxy listen port
`compressionThreshold`	`100`	Min tokens to compress
`learnFromResponses`	`true`	Learn patterns from LLM responses
`latencyBudgetMs`	`10000`	Max compression time before fallback
`enabled`	`true`	Global compression toggle

Requirements

Node.js >= 18.0.0
A Cognisos account (created during liminal init)

License

MIT

Command Reference

Commands are listed alphabetically. Each links to a dedicated reference page.

Command	Description	Usage
byok list	List providers with a stored key	`liminal byok list [--json]`
byok remove	Remove a stored provider key	`liminal byok remove <provider>`
byok set	Store a provider API key (stdin only)	`liminal byok set <provider>`
config	View or edit configuration	`liminal config [--set k=v] [--get k]`
daemon get-token	Print the stored auth token	`liminal daemon get-token`
daemon inspect	Diagnostic details (port, pid, binary)	`liminal daemon inspect`
daemon logs	View daemon log output	`liminal daemon logs [--follow]`
daemon restart	Restart the Fabric daemon	`liminal daemon restart`
daemon start	Start the Fabric background daemon	`liminal daemon start`
daemon status	Show daemon status and health	`liminal daemon status [--json]`
daemon stop	Stop the Fabric daemon	`liminal daemon stop`
init	Set up Liminal (login, config)	`liminal init`
inspect	Inspect pipeline phases for text	`liminal inspect <text> [--json]`
install-service	Install as a launchd LaunchAgent (macOS) or systemd user unit (Linux)	`liminal install-service`
login	Log in or create an account	`liminal login`
logout	Log out of your account	`liminal logout`
logs	View proxy logs	`liminal logs [--follow] [--lines N]`
mcp-stdio	stdio↔HTTP MCP bridge (used by Codex)	`liminal mcp-stdio`
setup claude-code	Connect Fabric MCP tools to Claude Code	`liminal setup claude-code [--global]`
setup codex	Connect Fabric MCP tools to Codex CLI	`liminal setup codex [--teardown]`
setup cursor	Install file compression hooks for Cursor	`liminal setup cursor [--teardown]`
start	Start the compression proxy	`liminal start [-d] [--port PORT]`
stats	Compression metrics & savings	`liminal stats [--json]`
status	Show proxy health check	`liminal status [--json]`
stop	Stop the running proxy	`liminal stop`
trust-ca	Install CA cert (for TLS intercept)	`liminal trust-ca`
uninstall	Remove Liminal configuration	`liminal uninstall`
uninstall-service	Remove the launchd LaunchAgent (macOS) or systemd user unit (Linux)	`liminal uninstall-service [--purge]`
untrust-ca	Remove CA cert	`liminal untrust-ca`