Loci

Local CLI inventory for AI agents — structured discovery of every executable on your PATH.
Humans get a fuzzy launcher for free. Agents get JSON, existence checks, and bounded lists.

English · 中文

---

English

loci turns your machine's PATH into a stable, cache-backed inventory that AI agents can query without guessing which tools exist.

List only. Jump only.
No version managers. No package installs. No alias memory.

Install (primary)

Unix / macOS / WSL — one line (downloads prebuilt binary when available):

curl -fsSL https://raw.githubusercontent.com/Yaemikoreal/CliLoci/master/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/Yaemikoreal/CliLoci/master/scripts/install.ps1 | iex

Other options: cargo install loci-cli · GitHub Releases · npm i -g @yaemikoreal/loci · from a clone: bash scripts/install.sh / powershell -File scripts/install.ps1.

Verify:

loci -l --json
loci --exists --json git   # optional cheap check

Agent integration (3 lines)

import subprocess, json
data = json.loads(subprocess.check_output(["loci", "-l", "--json"], text=True))
tools = data["executables"]  # full inventory; prefer --exists / --limit for large PATHs

Cheap checks (no full dump):

loci --exists --json git          # {"exists":true,"name":"git",...}  exit 0 / 1
loci -l --json --limit 30 git     # bound context size
loci -l --json --count            # {"total":N} only

Flag	Purpose
--exists / --check	Is tool X on PATH? (exit 0/1)
--limit N / --top N	Bound list size (Top = freq sort)
--count	Count only — no name dump
--json	Structured stdout; errors as loci_error on stderr

Full agent protocol: SKILL.md · workflows: AGENTS.md · manual: docs/usage.md.

Why agents need this

Without loci	With loci
Hard-code git / python / ffmpeg	Query what is actually on PATH
Dump shell completions into the prompt	skill_version + structured JSON
Guess on Windows (git vs git.exe)	--exists stem match + exit codes
Blow the context window with 400 tools	--limit / --count / --tag / keyword

Human usage (secondary)

loci                    # interactive fuzzy TUI (skim)
loci git                # pre-filter then TUI
loci git -- log -1      # pre-filter + args forwarded after selection
loci -l                 # plain text list

Features

• Agent-first JSON — loci -l --json with skill_version, optional meta / tags
• Existence check — loci --exists|--check <name> exit 0/1 (+ structured errors with --json)
• Bounded discovery — --limit N, --top N (freq), --count
• Fast cache — SHA-256 fingerprint of PATH dirs + mtimes
• Cross-platform — Linux, macOS, Windows (PATHEXT)
• Programmatic select — --exact / --pick-first / --index (always confirm before auto-launch)
• Project-local tools — --project (Node / venv / Rust / Conda)

When not to use / non-goals

Do not use loci when you need:

Need	Use instead
Install or switch tool versions	mise, asdf, package managers
Shell aliases / functions / builtins	your shell (alias, type, completions)
Remote host / container / cluster inventory	SSH, Docker, k8s tooling
A full desktop launcher with plugins	Raycast, Alfred, PowerToys

loci only scans local PATH (and optional project bin dirs). That constraint is intentional.

Documentation

• Full manual: docs/usage.md
• Agent skill: SKILL.md

Configuration

Blacklist: ~/.config/loci/blacklist (Linux/macOS) or %APPDATA%/loci/blacklist (Windows)

# One name per line; # for comments
clang
clang++

Extra scan paths: export LOCI_PATH_EXTRA="$HOME/.local/bin:$HOME/go/bin"

Development

git clone https://github.com/Yaemikoreal/CliLoci.git
cd CliLoci
cargo build --release
cargo test -- --test-threads=1
cargo install --path .

License

MIT

---

中文

loci 把本机 PATH 变成 可缓存、可结构化查询的 CLI 清单，专为 AI Agent 设计：少猜工具、少灌上下文。
人类也可把它当命令面板（模糊 TUI），但产品主路径是 Agent 发现层。

只列出，只跳转。
不管版本、不装包、不记别名。

安装（首选）

Unix / macOS / WSL：

curl -fsSL https://raw.githubusercontent.com/Yaemikoreal/CliLoci/master/scripts/install.sh | bash

Windows（PowerShell）：

irm https://raw.githubusercontent.com/Yaemikoreal/CliLoci/master/scripts/install.ps1 | iex

其他：cargo install loci-cli · Releases · npm i -g @yaemikoreal/loci · 克隆后：bash scripts/install.sh / powershell -File scripts/install.ps1。

验证：loci -l --json · 可选：loci --exists --json git

Agent 接入（三行）

import subprocess, json
data = json.loads(subprocess.check_output(["loci", "-l", "--json"], text=True))
tools = data["executables"]

省 token 的查询：

loci --exists --json git          # 是否存在：exit 0/1 + JSON
loci -l --json --limit 30 git     # 限制条数
loci -l --json --count            # 只要数量

参数	用途
--exists / --check	工具是否在 PATH（exit 0/1）
--limit N / --top N	限制条数（Top 按频率）
--count	只要数量
--json	结构化输出；错误在 stderr 的 loci_error

完整协议见 SKILL.md，工作流见 AGENTS.md，手册见 docs/usage.md。

为什么给 Agent 用

没有 loci	有 loci
硬编码工具名	查询 PATH 上真实存在的工具
把补全结果塞进 prompt	稳定 JSON + skill_version
Windows 名称混乱	--exists 支持 stem 匹配
几百个工具撑爆上下文	--limit / --count / --tag

人类用法（次要）

loci                    # 交互式模糊 TUI
loci git                # 预过滤后进 TUI
loci -l --json          # 列表 / Agent 首选

何时不要用 / 非目标

需求	请用
安装/切换版本	mise、asdf、系统包管理
别名 / shell 函数	当前 shell
远程 / 容器 / 集群工具发现	SSH、Docker、k8s
桌面级启动器插件生态	Raycast、Alfred 等

loci 只扫本机 PATH（及可选项目本地 bin）——边界即特性。

文档

• 操作手册：docs/usage.md
• Agent 技能：SKILL.md

配置

黑名单：~/.config/loci/blacklist 或 %APPDATA%/loci/blacklist
额外路径：export LOCI_PATH_EXTRA="$HOME/.local/bin"

开发

cargo build --release
cargo test -- --test-threads=1
cargo install --path .

许可

MIT