> For the complete documentation index, see [llms.txt](https://docs.loci-dev.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.loci-dev.net/loci-plugin-for-ai-coding-assistants.md).

# LOCI Plugin for AI Coding Assistants

## AI Writes Code. LOCI Gates It.

LOCI is a quality-gate agent for Claude Code that models regressions, power, latency, and control-flow safety directly from your compiled binary, from plan to merge. It requires no running code, no instrumentation, and no code changes: every result is grounded in real execution data recovered from the binary itself.

***

### What LOCI does

LOCI connects Claude Code to LCLM (Large Code Language Model), a model trained on billions of assembly blocks and real hardware traces from IoT, networking, and safety-critical systems — not a general-purpose model wrapped around your code. Because analysis happens at the binary level, LOCI can answer questions about timing, energy, memory, and control flow that source-level tools can't: the actual compiled output, not an approximation of it.

***

### Prerequisites

| Requirement                           | Version | Required for                                                                                                                           |
| ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| [Claude Code](https://claude.ai/code) | latest  | Everything                                                                                                                             |
| Python                                | 3.12+   | The `loci` CLI (local ELF/ build analysis)                                                                                             |
| [uv](https://docs.astral.sh/uv/)      | any     | Installs the `loci` CLI as a tool. Install this yourself — the plugin checks for it and gives you the install command if it's missing. |
| jq                                    | any     | Session hooks. Install this yourself - the plugin checks for it and gives you the install command if it's missing.                     |

**Cross-compiler depends on the** project you work with.

Skills that work without a cross-compiler or backend network access: `stack-depth`, `memory-report`, `control-flow`.

***

### Install

Install the plugin from inside Claude Code:

`/plugin marketplace add` [`https://github.com/auroralabs-loci/loci-claude`](https://github.com/auroralabs-loci/loci-claude)

`/plugin install loci@loci`

`/reload-plugins`

`/loci:setup`

\
There is no separate CLI download step. The loci command-line tool is installed automatically in the background the first time a Claude Code session starts, using uv. If uv or jq aren't already on your system, Claude will tell you the install command to run.

***

### Authentication

Timing and energy analysis reach the LOCI backend and require a signed-in session.

1. Run `! loci login` from inside Claude Code (or `loci login` in your terminal).
2. Confirm it worked with `loci auth status` - it should show `signed_in`.

* `stack-depth`, `memory-report`, and `control-flow` run fully offline. 
* `exec-trace`, `loci-preflight`, and `loci-post-edit` require a signed-in session because they call the LOCI backend.

***

### Quick Start

Once installed, try these in any C/C++/Rust project with compiled binaries:

1. **Timing & energy** — ask: "What's the execution cost of main()?"
2. **Memory budget** — ask: "How much ROM/RAM does my build use?"
3. **Stack safety** — ask: "Is my stack safe for TaskMain?"
4. **Control-flow safety** — ask: "What does the call graph for process\_data() look like?"

Two skills also run automatically, with no invocation needed:

* `loci-preflight` fires during `/plan` mode — analyzes callees at the binary level before code is written.
* `loci-post-edit` fires after every edit to C/C++/Rust source — diffs the binary and returns a regression verdict.

***

### Skills Reference

<table data-header-hidden><thead><tr><th width="141"></th><th width="216"></th><th width="93"></th><th></th></tr></thead><tbody><tr><td>Skill</td><td>Trigger</td><td>Sign-in required</td><td>What it does</td></tr><tr><td>loci-preflight</td><td>Automatic, in <code>/plan</code> mode</td><td>Yes</td><td>Audits the plan at binary level before code is written — timing, energy, and control-flow-graph impact.</td></tr><tr><td>loci-post-edit</td><td>Automatic, after edits to C/C++/Rust</td><td>Yes</td><td>Diffs pre/post compiled artifacts and returns a regression verdict on timing, energy, and control flow.</td></tr><tr><td>exec-trace</td><td>User-invoked</td><td>Yes</td><td>Function-level timing and energy from real-time hardware traces, powered by LCLM.</td></tr><tr><td>stack-depth</td><td>User-invoked</td><td>Yes</td><td>Worst-case stack depth via call-graph traversal and per-function frame sizes.</td></tr><tr><td>memory-report</td><td>User-invoked</td><td>Yes</td><td>ROM/RAM section breakdown and top consumers from compiled ELF binaries.</td></tr><tr><td>control-flow</td><td>User-invoked</td><td>Yes</td><td>Annotated control-flow graphs, optimized for LLM analysis.</td></tr><tr><td>trends</td><td>User-invoked</td><td>Yes</td><td>Per-function measurement history and optimization progress on the current branch.</td></tr><tr><td>help</td><td><code>/help</code></td><td>No</td><td>Confirms LOCI is loaded and lists available skills.</td></tr><tr><td>setup</td><td><code>/loci:setup</code>, or automatically on CLI-missing errors</td><td>No</td><td>Installs, repairs, or verifies the <code>loci</code> CLI. Safe to re-run at any time.</td></tr><tr><td>bug-report</td><td><code>/bug-report</code></td><td>No</td><td>Generates a full diagnostic report when something isn't working.</td></tr></tbody></table>

***

### Automatic Hooks

The plugin registers four hooks that run without user action:

<table data-header-hidden data-search="true"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td>Hook</td><td>Trigger</td><td>What it does</td></tr><tr><td><code>SessionStart</code></td><td>Session startup</td><td>Detects your project's build system, compiler, and target architecture; installs the <code>loci</code> CLI in the background if it's missing; and injects session context (auto-run rules, tool policy, response tone) for Claude to use. Never blocks session startup, even if detection or install fails.</td></tr><tr><td><code>PreToolUse</code></td><td>Before Edit, Write, or MultiEdit</td><td>Snapshots the current compiled <code>.o</code> for later delta analysis and runs a static call-graph pre-scan of the incoming code (before it's written to disk), surfacing any findings as context. Advisory only — always exits 0, never blocks the edit.</td></tr><tr><td><code>PostToolUse</code></td><td>After Edit, Write, or MultiEdit</td><td>Checks whether the change could alter a compiled function's body and, if so, injects a reminder instructing Claude to run the <code>loci-post-edit</code> skill immediately. Advisory only — always exits 0, never blocks.</td></tr><tr><td><code>Stop</code></td><td>End of session</td><td>If the <code>loci</code> CLI is present, flushes any pending analysis results to your account (<code>loci stats flush-impacts</code>).</td></tr></tbody></table>

***

### Troubleshooting

`loci` **CLI not found**:

1. Check it's on PATH: `command -v loci` and `loci --version`.
2. If it's missing, the background install may still be running or may have failed. Run `/loci:setup` to reinstall and verify — it's safe to re-run — or `loci doctor` once the CLI is present.
3. Confirm `uv` is installed (`command -v uv`); the plugin needs it to install the CLI.

**A skill reports** `auth_required`:

1. Run `! loci login` in your terminal, then retry.
2. Confirm `loci auth status` shows `signed_in`.<br>

**Auto-skills didn't fire**:

* `loci-preflight` only runs in `/plan` mode — confirm you're planning new logic, not just asking a question.
* `loci-post-edit` only runs after edits to C/C++/Rust source files.
* Both compile the source themselves — they don't need a pre-built binary. They do require a supported LOCI target and a working cross-compiler for it on PATH, plus a valid session context from startup. If the compiler is missing, restore it (or point LOCI at it) and re-run.<br>

**On-demand skills didn't respond**:

* Type `/help` to confirm LOCI is loaded and see the full skill list.
* Restart Claude Code from inside your project directory if the build environment wasn't detected at session start.
* Check that a cross-compiler is installed and on your PATH (see the table above).

**Nothing seems to work**:

Run `/bug-report` to generate a full diagnostic report.

***

### LOCI Portal

Every analysis run from Claude Code is logged and visualized automatically at the LOCI Portal (app.auroralabs.com), no extra configuration needed. The Portal is where you view session history, binary analysis results, PR review status, and team/quota settings.

***

### Account Plans

LOCI is available on a free tier with limited daily interactions. Paid tiers raise or remove that limit and unlock additional capabilities...&#x20;

For current plans and pricing, see [auroralabs.com/pricing](https://www.auroralabs.com/pricing).

***

### Support

* Email: <loci@auroralabs.com>
* Plugin issues: [github.com/auroralabs-loci/loci-claude/issues](https://github.com/auroralabs-loci/loci-claude/issues)

***

### Reference

* Quick Start (web): `auroralabs.com/product#quick-start`
* Talk to us: `auroralabs.com/contact`
* LOCI install endpoint: `https://loci.auroralabs.com/install.sh`