HLS — Universal AI Agent Kit

A universal installer for the HLS Agent Kit — a curated set of agents, skills, rules, prompts, and hooks that work across every major AI coding assistant.

What it installs

| Target | Output path | Contents | |--------|-------------|----------| | claude | .claude/ | 16 agents, 53 skills, 5 rule files, templates, CLAUDE.md | | copilot | .github/ | 16 .agent.md, 23 .prompt.md, 5 .instructions.md, 53 skills, hooks | | cursor | .cursor/rules/ | MDC rules: main + dev rules + 16 agent rules | | codex | AGENTS.md | Single merged instructions file for Codex CLI / Responses API |

Install

npm install -g @hls-kit/hls

Install the scoped package @hls-kit/hls. The unscoped hls package on npm is unrelated.

Quick Start

cd my-project

# 1. Interactive setup (recommended)
hls init

# 2. Install all targets at once
hls install

# 3. Build the project AST graph
hls graph build

# 4. Inject graph instructions into AI configs (auto-done if graph exists at install time)
hls graph install

# 5. Optional — install token compressors for leaner AI context
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh   # CLI output compression (60-90%)
curl -fsSL https://raw.githubusercontent.com/nooscraft/tokuin/main/install.sh | bash  # file read compression (50-70%)
hls rtk check       # verify RTK
hls tokuin check    # verify Tokuin

Commands

hls install

Install the agent kit into the current project.

hls install                          # all targets (claude, copilot, cursor, codex)
hls install --target claude          # Claude Code only
hls install --target copilot,cursor  # multiple targets
hls install --force                  # overwrite existing files
hls install --dry-run                # preview without writing

Auto-inject: if hls-graph/index.json already exists in the project, graph-usage instructions are automatically injected into all AI config files after install.

hls init

Interactive wizard — choose targets and configure the kit.

hls init

hls update

Re-install to pick up kit changes (runs install --force).

hls update                           # all installed targets
hls update --target copilot

hls doctor

Verify installation health and report missing or outdated files.

hls doctor                           # check all installed targets
hls doctor --target cursor

hls graph — Knowledge Graph

The graph subcommand builds and queries token-efficient graphs. By default it scans the current project and creates a lightweight JS/TS AST graph of files, symbols, and imports. Use --kit when you want the bundled skill/agent discovery graph.

hls graph build

Index the current project AST into a queryable graph.

hls graph build                      # output → hls-graph/
hls graph build --out .my-graph      # custom output directory
hls graph build --project ../app     # scan a different project
hls graph build --kit path/to/kit    # build kit skill graph instead

Generates four files in the output directory:

| File | Description | |------|-------------| | graph.json | Full graph of project files, symbols, imports, and external modules | | index.json | Flat search index for fast AI/script querying | | GRAPH_REPORT.md | Project AST summary with suggested queries | | graph.html | Interactive D3.js force-graph visualization |

hls graph query

Search the graph for matching skills, agents, files, symbols, or modules.

hls graph query "fix failing tests"
hls graph query "plan and implement a feature" --json
hls graph query "deploy to production" --graph .my-graph

Flags:

| Flag | Description | |------|-------------| | --json | Compact JSON output — ideal for AI/script consumption | | -g, --graph <dir> | Graph directory (default: hls-graph) |

Example JSON output:

{
  "keywords": ["plan", "implement", "feature"],
  "skills": [
    { "name": "create-plan", "score": 8, "desc": "Create a detailed implementation plan...", "hint": "[task] OR [archive|red-team|validate]" },
    { "name": "hls",         "score": 6, "desc": "End-to-end pipeline from planning to shipped feature", "hint": "[task|plan-path]" }
  ],
  "agents": [
    { "name": "planner",     "score": 8 },
    { "name": "implementer", "score": 8 }
  ]
}

Scoring: name match = 4 pts · description match = 2 pts · keyword match = 1 pt. Returns top 6 skills and top 3 agents.

hls graph install

Inject graph-usage instructions into all installed AI platform config files.

hls graph install                    # current project
hls graph install --project /path    # specific project directory

Injects a brief instruction block (idempotent, marker-based) into:

| Platform | File | |----------|------| | Claude Code | CLAUDE.md | | GitHub Copilot | .github/copilot-instructions.md | | Cursor | .cursor/rules/hls-graph.mdc (MDC rule, alwaysApply: true) | | OpenAI Codex | AGENTS.md |

The injected instruction tells the AI:

• Always run hls graph query before activating any skill or agent
• Use hls-graph/index.json for batch lookups instead of reading 53+ SKILL.md files
• Only read the full SKILL.md when the description is insufficient

Re-running hls graph install is safe — the old block is removed and replaced.

All Flags

| Flag | Commands | Description | |------|----------|-------------| | -t, --target <T> | install, update, doctor | Comma-separated: claude, copilot, cursor, codex, all | | -f, --force | install | Overwrite existing files | | --dry-run | install | Preview without writing | | -p, --project <dir> | graph build, graph install | Project directory (default: .) | | -k, --kit <dir> | graph build | Build kit skill graph instead of project AST graph | | -o, --out <dir> | graph build | Graph output directory (default: hls-graph) | | -g, --graph <dir> | graph query | Graph directory (default: hls-graph) | | --json | graph query | Compact JSON output | | -l, --level <lvl> | tokuin compress | Compression level: light, medium (default), aggressive |

hls rtk — Token Optimizer Integration

RTK (Rust Token Killer) is a high-performance CLI proxy that compresses command outputs before they enter the LLM context. It saves 60–90% tokens on every git, aws, docker, npm, and test runner call.

Without RTK:  git status  →  ~2,000 tokens (raw output)
With RTK:     rtk git status  →  ~200 tokens (compressed)

Install RTK

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh

# macOS (Homebrew)
brew install rtk

hls rtk check

Check if RTK is installed and show live token savings stats.

hls rtk check

Output:

  HLS × RTK Token Optimizer

  ✓  rtk 0.42.0

  Token savings:
    Total commands  : 1,240
    Saved (all time): 1,850,000 tokens
    Saved (today)   : 14,200 tokens

hls rtk install

Wire RTK hooks into all installed AI platform configs. After this, bash commands are transparently rewritten to their rtk equivalents — no manual prefix needed.

hls rtk install                       # all installed platforms
hls rtk install --target claude       # Claude Code only
hls rtk install --target cursor       # Cursor only

RTK hook behavior per platform:

| Platform | Hook mechanism | Effect | |----------|---------------|--------| | Claude Code | PreToolUse bash hook | Transparent auto-rewrite | | GitHub Copilot | PreToolUse hook | Transparent auto-rewrite | | Cursor | hooks.json preToolUse | Transparent auto-rewrite | | OpenAI Codex | AGENTS.md instructions | AI uses rtk prefix explicitly |

After install, restart your AI tool to activate the hook.

Commands that RTK compresses

| Category | Commands | Typical savings | |----------|----------|----------------| | Git | git status/diff/log/add/commit/push/pull | 75–92% | | AWS | aws ec2/lambda/logs/s3/iam/dynamodb/cloudformation | 70–85% | | Docker / K8s | docker ps/logs/images, kubectl get/logs | 80% | | Test runners | npm test, jest, pytest, cargo test, go test | 90% | | Build / Lint | tsc, eslint, cargo build, ruff check | 80% | | File ops | ls, grep, find, cat | 70–80% | | Package managers | npm/pnpm/pip list, prisma generate | 75% |

Graph + RTK injection

When you run hls graph install, both the graph-query rules and RTK usage instructions are injected into all AI config files automatically. The AI knows to:

1. Run hls graph query before activating any skill (saves reading 53+ SKILL.md files)
2. Prefix CLI calls with rtk when the hook is not active (saves context on command output)

hls tokuin — File Compression Integration

Tokuin compresses text and document files into the Hieratic format before they enter the LLM context. It saves 50–70% tokens every time an AI agent reads a .md, .log, .txt, .json, or similar file.

Without Tokuin:  cat architecture.md  →  ~2,800 tokens (raw)
With Tokuin:     (auto-compressed)    →  ~1,289 tokens (Hieratic)

Install Tokuin

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/nooscraft/tokuin/main/install.sh | bash

Note: The pre-built binary requires glibc ≥ 2.38 (Ubuntu 24.04+, Fedora 38+). On older systems (Ubuntu 22.04), build from source:

cargo build --release --features compression
cp target/release/tokuin ~/.local/bin/

hls tokuin check

Verify Tokuin installation and show active compression rules.

hls tokuin check

Output:

  HLS × Tokuin Prompt Compressor

  ✓  tokuin 0.3.0

  File-compress hooks: active (PreToolUse · Bash cat <file>)
  Triggers on:
    .log .txt .md .csv .rst   > 3 KB
    .json .yaml .xml .toml     > 10 KB
  Compression level: medium (50-70% token reduction)
  Output format: Hieratic — all major LLMs read natively

  Manual compress: hls tokuin compress <file>

hls tokuin compress

Manually compress a file to Hieratic format.

hls tokuin compress README.md                      # default level (medium)
hls tokuin compress large-log.txt --level light    # lighter compression, more preserved
hls tokuin compress api-docs.md --level aggressive # maximum compression

Compression levels:

| Level | Token reduction | Use when | |-------|----------------|----------| | light | 30–50% | Content that must stay precise (specs, contracts) | | medium | 50–70% | Default — good balance for most docs and logs | | aggressive | 70–90% | Large files where structure matters more than wording |

How automatic compression works

Once Tokuin is installed, the file-compress PreToolUse hook activates automatically — no extra setup needed. When the AI agent runs cat <file>, the hook intercepts the call, compresses the file via Tokuin, and returns Hieratic output instead of raw text. The original file is never modified.

Eligible files (automatically compressed):

| Extension | Threshold | Typical savings | |-----------|-----------|----------------| | .log .txt .md .csv .rst .out | > 3 KB | 50–70% | | .json .xml .yaml .yml .toml | > 10 KB | 30–50% |

Files below the threshold, code files (.js, .ts, .py, etc.), and piped cat commands are passed through unchanged.

Token reduction pipeline

HLS uses three complementary layers to keep context lean:

| Layer | Tool | What it compresses | Savings | |-------|------|-------------------|---------| | Skill discovery | Graph query | 53 SKILL.md → ~200 tokens | 75× cheaper | | CLI outputs | RTK | git, docker, npm, test runners | 60–90% | | File reads | Tokuin | .md, .log, .txt, .json files | 50–70% |

# New project
hls install          # installs all targets
hls graph build      # indexes the project AST
# → graph instructions are auto-injected into AI configs

# Install RTK for token-optimized CLI outputs (optional but highly recommended)
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
hls rtk check        # verify RTK is ready

# Install Tokuin for token-optimized file reads (optional but highly recommended)
curl -fsSL https://raw.githubusercontent.com/nooscraft/tokuin/main/install.sh | bash
hls tokuin check     # verify Tokuin is ready
# → restart your AI tool — file reads and CLI outputs now compressed automatically

# AI usage after setup
hls graph query "write unit tests for a React component"
#   Returns: run-tests (score 9), build-frontend (score 6), debug-code (score 4)
#   → activate the top skill directly

# Visualize the knowledge graph
open hls-graph/graph.html

Development

# In the hls/ directory:
npm install                     # install dependencies
node bin/hls.js --help          # test CLI locally
npm link                        # make `hls` available globally for dev
node tests/smoke.js             # run smoke tests (6 tests)

Kit resolution order

1. npm install: bundled kit/ directory inside the package
2. Development (npm link): falls back to sibling source kit (configurable via HLS_KIT_SOURCE env var)

Publishing

Releases are automated via semantic-release on push to main:

git commit -m "feat: add new skill"   # triggers minor release
git commit -m "fix: parser bug"       # triggers patch release
git push origin main                  # CI publishes to npm automatically