Coding agents write code. LOCI thinks ahead.
LOCI predicts what AI-generated code will do — time, power, memory, and system behavior — during planning and code writing, before it runs.
Without running code. No instrumentation. No code changes.
| Requirement | Version | Required for |
|---|---|---|
| A coding agent: Claude Code or GitHub Copilot CLI | Claude Code: latest. Copilot CLI: 1.0.90 or newer | everything |
| Python | 3.12+ | the loci CLI (local ELF/build analysis) |
| uv | any | installs the loci CLI as a tool — install yourself; the plugin checks for it and, if missing, the agent gives you the install command |
Windows only: PowerShell 7 and Git for Windows, with its bash on PATH |
— | the hooks under GitHub Copilot CLI (see Under GitHub Copilot CLI); Claude Code finds Git Bash on its own |
| Compiled binaries | .elf / .o / .axf |
all skills |
| Network access to the LOCI backend | — | exec-trace, loci-preflight, loci-post-edit |
Cross-compiler (one required, depending on your target):
| Target | Compiler |
|---|---|
| ARM Cortex-M | arm-none-eabi-gcc |
| ARM Cortex-A | aarch64-linux-gnu-gcc |
| ARM Neoverse V2 (ARMv9-A) | aarch64-linux-gnu-gcc or clang, with -mcpu=neoverse-v2 or -march=armv9-a |
| TriCore | tricore-elf-gcc |
| TI ARM | tiarmclang or armcl |
| x86/x64 | g++ or clang++ |
Skills that work without a cross-compiler or the backend: /loci:stack-depth, /loci:memory-report, /loci:control-flow, /loci:contract
In Claude Code:
/plugin marketplace add auroralabs-loci/loci-claude
/plugin install loci@loci
/loci:setup
With GitHub Copilot CLI, from a terminal (it reads the same marketplace),
then /loci:setup inside a session:
copilot plugin marketplace add auroralabs-loci/loci-claude
copilot plugin install loci@loci
/loci:setup installs the loci CLI as a uv tool and verifies the
environment. The plugin also starts that install in the background at session
start, so it often finishes on its own; running the skill makes it deterministic
and names whatever is missing. It is idempotent — run it again any time analysis
fails with loci: not found.
The same plugin serves both hosts: Copilot reads the plugin's hooks/hooks.json
and skills/ as they are, so everything below about skills, hooks and verdicts
holds there too. What differs is around the edges:
- Prerequisites on Windows. Copilot CLI needs PowerShell 7 (its own
requirement), and it hands every hook command to PowerShell, which resolves
bashthrough PATH. AddC:\Program Files\Git\binto PATH ahead ofC:\Windows\System32(a default Git for Windows install adds onlyGit\cmd, andSystem32\bash.exeis the WSL launcher):where.exe bashmust list Git's first.Git\binholds onlybash,shandgit, and itsbashputs Git's tools on its own PATH;Git\usr\binwould also shadow Windows'find,sortandtimeoutfor everything else. Claude Code locates Git Bash itself, so this is a Copilot-only step. - Sign-in.
! loci loginworks the same way: Copilot's!prefix runs a command in your shell, which is where the browser flow has to run. - What runs automatically. The six hooks in the table below fire under Copilot
as they do under Claude Code:
loci-preflightin/planmode (or a--planrun),loci-post-editafter an edit to C/C++/Rust/Go/Python source, the contract guard on every edit and command. Copilot's subagents inherit the parent turn's id through theSubagentStarthook. - Version.
copilot plugin listshows the installed version, andcopilot plugin update loci@locipulls a newer one from the marketplace. The marketplace serves what the public repositoryauroralabs-loci/loci-claudecarries. - Removing it.
copilot plugin uninstall loci@loci, thencopilot plugin marketplace remove loci. On Windows the uninstall has answeredAccess is denied(Copilot CLI 1.0.90 and 1.0.91, with other Copilot sessions open; a fresh profile uninstalls cleanly). If it refuses, quit the other Copilot sessions and retry, orcopilot plugin disable loci@lociuntil you can;copilot plugin marketplace remove loci --forceclears a row the uninstall left behind. - Direct installs.
copilot plugin install auroralabs-loci/loci-claudealso works, but Copilot prints a deprecation warning for it ("only plugin@marketplace installs will be supported in a future release"), so use the two commands above.
Copilot CLI updates itself; the versions this plugin is verified against are 1.0.90 and 1.0.91 on Windows 11, which is where the floor in the prerequisites table comes from.
Sign in once per machine. Every analysis skill is gated on a session, including the ones that never reach the backend:
! loci login # at the agent's prompt: `!` runs it in your shell, which can open a browser
loci auth status # must report signed_in
Then run /loci:init once per clone. It records how the project builds — target
ISA, compiler, build system, artifact — into .loci/build.yaml, and every
measurement after that resolves its flags from that file instead of guessing.
Both it and LOCI's own build output (.loci/build/) are machine-local and
gitignored, so a fresh clone needs its own /loci:init. Another checkout of a
repository you set up on this machine — a git worktree, the kind Copilot runs each
session in — reuses the recipe you confirmed, at session start. It does not when
that recipe is tied to the folder it was made in: it names that folder, builds in
a container, reaches outside it with ../, builds outside it (a shadow build
directory every checkout would share), or uses a compile database LOCI
synthesized there. Then that checkout needs its own /loci:init.
Then try these in any C/C++/Rust project with compiled binaries.
- Timing & energy — ask: "What's the execution cost of main()?"
- Memory footprint — ask: "How much ROM/RAM does my build use?"
- Stack safety — ask: "Is my stack safe for TaskMain?"
- Control-flow safety — ask: "What does the call graph for process_data() look like?"
- Bounds — say: "TaskMain must not exceed 4 kB of stack" — LOCI drafts the bound, you apply it. Bounds are what let a report pass or fail; without one it reports the number and argues about it instead.
LOCI also runs automatically:
- loci-preflight fires during
/plan- analyzes callees at the binary level before code is written. - loci-post-edit fires after every edit - diffs the binary and reports what the change cost.
Guardian — human-on-the-loop. LOCI predicts, warns, and guides; you review the verdict.
| Skill | Trigger | What it does |
|---|---|---|
| loci:init | User-invoked | Records how this project builds into .loci/build.yaml — target ISA, compiler, build system, artifact. Once per clone, which its worktrees reuse; every skill that compiles or measures rests on it. Needs sign-in. |
| loci-preflight | Auto in /plan mode |
Audits the plan at binary level before code is written — timing, energy, and CFG impact. |
| loci-post-edit | Auto after edits | Diffs pre/post compiled artifacts — timing, energy and control-flow impact of the edit. |
| exec-trace | User-invoked | Function-level timing and energy from real workloads and platform traces, powered by LCLM. |
| stack-depth | User-invoked | Worst-case stack depth via call-graph traversal, per-function frame sizes |
| memory-report | User-invoked | ROM/RAM section breakdown and top consumers from compiled ELF binaries. No runtime instrumentation. No code modifications. |
| control-flow | User-invoked | Annotated control-flow graphs optimized for LLM analysis |
| trends | User-invoked | Per-function measurement history and optimization progress on the current branch. |
| contract | User-invoked | Authors and inspects .loci/contract.yaml — the stack, timing, energy, memory and structural bounds every measurement is judged against. LOCI drafts, you apply. |
| setup | User-invoked | Installs the loci CLI and verifies the environment; repairs a broken or stale install. No sign-in needed. |
| help | User-invoked | Lists every skill and shows this checkout's recorded target, compiler and recipe path. No sign-in needed. |
| bug-report | User-invoked | Writes a timestamped forensic diagnostic when a skill fails or never fires. No sign-in needed. |
Under GitHub Copilot CLI. Copilot shows the model a skill's description only, so every skill's frontmatter description carries its own trigger clause; Claude Code also reads the richer when_to_use key. Skill prose names tools as Claude Code does — Edit/Write, Bash, Read, and the question tool for AskUserQuestion — and the session context's host: line maps them to Copilot's edit/create, bash or powershell, view and ask_user; neither host's -p mode has a question tool, so a headless /loci:init reports instead of asking. Plugin skills are addressed as /loci:<skill> — Copilot's built-in /init and /help are its own commands, not ours. In programmatic mode (copilot -p) a bare /init or /setup resolves to the plugin skill. Copilot does not substitute $ARGUMENTS; a skill reads the words after its command from the prompt itself, which is how /loci:setup doctor works on both hosts.
A LOCI report closes on one of two word sets, and which one tells you how much it is worth.
| Words | When | Means |
|---|---|---|
PASS / CAUTION / FAIL |
a bound covered the signal | the measurement was compared against a requirement, and this is the result |
flagged / cleared |
no bound covered it | LOCI reasoned about the number. flagged raises a concern and names the block or callee behind it; cleared raises none, and is not a pass |
Most reports close on cleared, because most repositories have no bounds set. A
bound comes from .loci/contract.yaml (/loci:contract drafts one) or from your own
request, as in "keep this under 200 ns". LOCI never supplies one of its own,
which is why a large number on its own cannot fail: nothing has said what large
means for your project.
| Hook | Trigger | Action |
|---|---|---|
SessionStart |
startup, resume | CLI install, context injection, build-state cleanup, the confirmed recipe for a new checkout of a repository already set up |
UserPromptSubmit |
every prompt | stamps the turn id every measurement is filed under |
PreToolUse |
Edit, Write, Bash | keeps .loci/contract.yaml and .loci/build.yaml read-only to the agent; .o snapshot for delta analysis |
PostToolUse |
Edit, Write, Bash | asks whether the edit can change a compiled function, and reminds loci-post-edit if so |
SubagentStart |
a subagent spawned | under GitHub Copilot CLI, lets the subagent's edits inherit the parent turn's id |
Stop |
end of turn | flushes impact records, nudges on a pending contract draft, cleans the turn's build state |
loci cockpit shows what LOCI catches that your coding agent might miss during planning and coding — live, in your terminal, no browser, no sign-in.
It reads the same measurement store the skills write to, so what it shows is what the session reported.
Open it in a separate terminal: it takes over the one it runs in, so it will not share a terminal with a coding agent session.
loci cockpit # live TUI
loci cockpit --once # one snapshot as a JSON envelope
loci cockpit --altitude contract # open on the contract panel
loci cockpit --catches-only # event feed filtered to non-OK verdicts
| View | Shows |
|---|---|
| hotspots | The functions costing the most time, energy and stack on this branch |
| prevented | Regressions the Guardian caught before they merged |
| time-saved | Analysis time LOCI spent vs. runtime measurement it replaced |
| contract | Every bound in .loci/contract.yaml and the latest measurement judged against it |
--project / --branch select what to look at; both default to the most recent.
LCLM (the execution model behind AI Physics) is trained on real workloads and platform traces — six years of them — and reads the compiled binary directly. Not a GPT wrapper: no source-only reasoning, no hallucinated timing.
Connects to the LOCI backend for Binary Execution Grounding powered by LCLM — real-time execution data, no instrumentation required. Plug LOCI into your CI/CD pipeline at any stage — code, build, test, or merge.
All analysis runs through the loci command — a uv tool the plugin installs in
the background at session start. If skills fail with "loci not found" or nothing
happens:
- Check it's on PATH:
command -v lociandloci --version. - If it's missing, the background install may still be running or may have
failed — run the
/loci:setupskill in your coding agent to reinstall and verify (it's idempotent and repairs whatever's missing), orloci doctoronce it's present. - Confirm
uvis installed (command -v uv); the plugin needs it to install the CLI.
Every LOCI analysis skill requires a signed-in session. The local ELF skills
(/loci:stack-depth, /loci:memory-report, /loci:control-flow) don't reach the backend, but
the CLI still gates them behind a session. If a skill reports auth_required:
- Type
! loci loginat the agent's prompt (orloci loginin a terminal), then retry. - Confirm
loci auth statusshowssigned_in.
Skills that work signed-out: /loci:help, /loci:setup, /loci:bug-report, /loci:contract
Skills that need sign-in: /loci:init, /loci:exec-trace, /loci:stack-depth, /loci:memory-report, /loci:control-flow, /loci:trends, loci-preflight, loci-post-edit
Every measurement resolves its flags from .loci/build.yaml, which /loci:init
writes. It is machine-local, so a fresh clone has none until you run it there. A
worktree of a repository you already set up reuses its recipe when the session
starts, unless that recipe is tied to its own folder (see Quick Start). A recipe
confirmed before plugin v0.3.23 is offered to other checkouts once /loci:init
has run again where it was made.
- Run
/loci:init. It reads the project, asks at most one question — the target ISA when more than one is possible, otherwise just "does this look right?" — and names anything it needs and cannot find. /loci:helpshows the recorded target, compiler and recipe path once it succeeds.
Auto-skills didn't fire:
loci-preflightonly runs in/planmode. Make sure you're planning new logic, not just asking a question.loci-post-editonly runs after edits to C/C++/Rust/Go/Python source files, or a header they include, in a project a LOCI recipe governs.- Both auto-skills require compiled binaries (
.elf,.o,.axf) to be present. If your project hasn't been built yet, compile it first.
On-demand skills didn't respond:
- Type
/loci:helpto confirm LOCI is loaded and see the full skill list. - Verify this checkout is initialized —
/loci:helpshows the recipe path, and/loci:initrecords one if it is missing. - Check that a cross-compiler for your target is installed and on your PATH (
/loci:initreports which one this project needs):- ARM Cortex-M:
arm-none-eabi-gcc - ARM Cortex-A:
aarch64-linux-gnu-gcc - ARM Neoverse V2 (ARMv9-A):
aarch64-linux-gnu-gccorclang, with-mcpu=neoverse-v2or-march=armv9-a - TriCore:
tricore-elf-gcc
- ARM Cortex-M:
Nothing seems to work:
Run /loci:bug-report to generate a full diagnostic report.
- LOCI Portal — sessions, binary analysis results, Guardian verdicts, PR review, and account plans
- agents.txt — this setup path as one downloadable plain-text file a coding agent can follow
- setup/setup.sh — full setup script with platform-specific install logic
- LICENSE — Aurora Labs Proprietary License